Routes
A route describes a single data flow between an external system and SAP Business One — which kind of object is transferred (e.g. articles or sales orders), in which direction the data flows, which connection is used for it, and how fields are mapped between the systems.
Routes are the central configuration object: you create one route per individual integration. A route uses exactly one connection; a connection in turn can be used by any number of routes.
Direction: Import and Export
Every route has a direction. It says where the data flows — seen from SAP Business One: Import brings data from an external system into SAP Business One, Export takes data from SAP Business One to an external system.
Type: Processing and Dispatch
Every route also has a type, which determines its processing pattern:
- Processing is the standard case — a route of this type transfers business records of an object type (e.g. Lieferung or Geschäftspartner) between SAP Business One and an external system.
- Dispatch does not transfer business records itself. Instead it evaluates an incoming message against rules and forwards it to one or more processing routes as targets. This models scenarios where a single incoming message needs to be processed differently depending on its content.
An example of the second case: a web shop reports orders, complaints, and contact requests together — everything arrives at one inbox, whatever it is about. A dispatch route accepts those messages, recognizes from the content what each one is, and hands every message to the matching processing route.
Direction and type depend on each other: a dispatch route is always an import route — it receives a message and forwards it onward. Export, on the other hand, only exists as processing. This yields three valid combinations: import with processing, export with processing, and import with dispatch.
Data origin: where a route gets its data from
Besides direction and type, every route has a data origin. It answers the question of how the records reach the route in the first place:
- Dataset — the route reads by itself: it calls an endpoint and fetches the records. That is the case for export routes.
- Queue — the route fetches waiting entries one after another and processes them until nothing is left. It scans no dataset while doing so.
- Dispatch input — the route gets its data from a dispatch route and reads nothing itself.
These three characteristics cannot be combined freely: direction and type determine which data origins are available at all.
| Direction | Type | Data origin |
|---|---|---|
| Export | Processing | Dataset |
| Import | Processing | Queue or Dispatch input |
| Import | Dispatch | Queue |
The data origin is the central switch of the configuration: it determines what there is to set up as source data in the editor at all, and which run types are available.
Object type
Every processing route transfers exactly one object type — the business kind of object the route is about. That can be master data (Artikel, Geschäftspartner, Preisliste) just as well as documents (Kundenauftrag, Lieferung, Gutschrift). The object type is the route's main object and remains the common thread across all further configuration steps. An object type denotes a type, not a quantity — which is why it is written in the singular (Kundenauftrag, not Kundenaufträge). The same object type can be used by several routes: an article export and an article import share the object type Artikel; the routes are distinguished by name, direction, and connection. How to pick a suitable object type while creating a route is shown in the guide Create a route.
That completes the four defining characteristics of a route: direction, type, data origin, and object type. All four are fixed once the route has been created; name and connection stay changeable. For a different combination, create a new route.
Triggers: when a route runs
For a route to run automatically, it needs at least one trigger. Without a trigger, a route can only be started manually. Xchange offers three trigger variants:
- Scheduled — the route starts on a fixed schedule, e.g. daily at a fixed time or every 15 minutes.
- Event — the route reacts to a transaction event in SAP Business One, such as a document being created or changed. This variant is only available for export routes, since only there does an event in SAP Business One meaningfully trigger the export of the affected data.
- Dispatch input — links a route as the target route of a dispatch route. The term deliberately appears twice in the configuration: as a data origin it says where the data comes from, as a trigger it says when the route starts on it. This trigger is created automatically as soon as a dispatch rule names the route as a target, and cannot be added or removed manually.
A trigger also determines which data a run processes (the run type) — and which run types are available follows from the data origin: a route reading from the dataset distinguishes between an incremental run (only records changed since the last run) and a full run (all records); a route with data origin Queue drains the waiting entries instead.
Naming
The name of a route is free to choose, but it carries more weight than it might seem at first: many views — Execution, History, Configuration Snapshots, selection lists, and the duplicate warning — show a route by its name alone, without the Direction, Type, and Object type columns beside it. The name must therefore make the route unambiguous and self-explanatory on its own. Which naming pattern has proven itself for this is shown in the guide Create a route.