The basic model
An integration in Xchange consists of three building blocks: the connection, the route and the step. The configuration snapshot brings them together and defines in which version they apply. If you keep the four apart, you know where a setting belongs: the address of the online shop in the connection, the schedule in the route, the target field in the step. Whether a change already takes effect is told by the configuration snapshot.
This page plays the four through on a single job: an order from the online shop of Cambira Sanitärtechnik GmbH.
The case
At 8:41 AM, someone orders two single-lever mixers in the online shop. At 8:45 AM, the order is in SAP Business One as a document, with customer number, order date, payment method and two lines.
| Term | The question it answers | In the case |
|---|---|---|
| Connection | Which system do we talk to, at which address, with which sign-in? | Webshop Cambira |
| Route | In which direction does it go, where do the data come from, what starts it? | Bestellungen Webshop |
| Step | What is created at the target, and which field gets which value? | one step that creates the document |
| Configuration snapshot | Which version of these settings applies right now? | Version 7 (active) |
Along the way of the order, they relate to each other like this:
The connection — the counterpart
A connection is an external system as Xchange reaches it: with type, address and sign-in. The transferring is done by the routes that use it.
Cambira has three of them:
| Connection | Type | Base address |
|---|---|---|
| Webshop Cambira | REST | https://shop.cambira.example.com/api |
| Cambira Austria | SAP Business One | https://sap-at.cambira.intern:50000 |
| Kessler Logistik | REST | https://edi.kessler-logistik.example.com/v2 |
A connection is set up once and then used by several routes. "Webshop Cambira" carries the orders in and the items out — two directions, two routes, one connection. If the shop changes its address, that is a change in one place.
A route names exactly one connection. The other side is fixed: always the SAP Business One in which Xchange works. That is why a connection of the type SAP Business One always means a second, external system: at Cambira, the company database of the Austrian sister company. If the data stays within SAP Business One, that is an internal route, and it names no connection.
More on this: Connections.
The route — the way for a data exchange
A route is a way in one direction, over one connection. It says:
- Direction — Import, Export or Internal, measured from Xchange. Orders come in, so import.
- Connection — with which counterpart. Here: "Webshop Cambira".
- Data origin — where the data comes from: from a dataset that Xchange queries, from a queue into which the external system places it, or from a dispatch input. The shop places every order in a queue.
- Trigger — what starts it. Here a schedule, every five minutes.
What the route actually transfers — its object — is not an entry of its own; it reads off its
configuration: for an export or internal route, the fetch endpoint; for an import route, the target path of its
primary step. For "Bestellungen Webshop" that is Orders, the sales orders in SAP Business One.
The number of routes follows from this: Cambira has nine, because there are nine such ways — orders in, items out to the shop, items out to Austria, delivery orders out to the logistics partner and five more for the messages it sends back. Each of these ways is its own route — even where two of them, such as "items out to the shop" and "items out to Austria" here, transfer the same object.
More on this: Routes and Triggering.
The step — what is created at the target
A route describes the way, a step the arrival: which object is created in the target system and which field gets which value.
The step of the route "Bestellungen Webshop" creates the document. Its mapping reads from the shop's message and writes to SAP Business One:
| Target field | Source |
|---|---|
CardCode | OriginalPayload.customer_no |
NumAtCard | OriginalPayload.order_id |
DocDate | OriginalPayload.placed_at |
DocDueDate | OriginalPayload.placed_at |
PaymentMethod | OriginalPayload.payment |
DocumentLines | OriginalPayload.lines[*] |
DocumentLines → ItemCode | sku |
DocumentLines → Quantity | qty |
DocumentLines → "Fracht" | FRACHT-PAUSCHAL, quantity 1, price from OriginalPayload.shipping_total |
Two values are transformed on the way. The date comes from the shop with a time
(2026-10-08T08:41:12Z); SAP Business One expects it as 2026-10-08. The shop writes the payment
method as paypal; SAP Business One expects PP. This translation is kept in a
value table, which several routes can use.
The shop does not send the second line of the document as a line: the shipping costs come as one
amount in the header of the order, and the mapping turns it into an additional row with the freight item
FRACHT-PAUSCHAL.
A route can have several steps — then more than one object is created at the target, or something is reported back after the writing. One of them is the primary step: the one that writes the main object of the route. There is exactly one, and the key of the route depends on it. For the orders, the primary step is the one that creates the document.
More on this: Mapping and Writing to the target system.
The configuration snapshot — which version applies right now
Connections, routes, steps and value tables together form one version of the configuration, and this version is called a configuration snapshot.
In daily work, you deal with at most two snapshots:
- The active configuration snapshot — Xchange works by it in ongoing operation. At Cambira this is Version 7, activated on Oct 2, 2026, 4:40 PM by M. Brandt. This morning's order ran by this version.
- The draft — it collects your changes as long as they are not yet activated; in operation it takes effect only after the activation. At Cambira this is Version 8, last changed today at 8:57 AM. It contains an additional row in the value table "Zahlungsarten Webshop", and this row does not take effect yet.
Only the activation of a snapshot makes a change effective — it is saved before that. Xchange saves every entry on its own — it lands in the draft.
More on this: Configuration Snapshots.
What belongs to operations
Two more terms come up constantly. The four building blocks above describe the setup, these two the operations:
- A run is one pass of a route. The run at 8:45 AM emptied the queue.
- A job is a single record on its way. The order
WS-2026-104877was one of them.
A run bundles the jobs it created. Both belong to execution.
More on this: Execution.
See also
- A tour of the UI (getting started) — where connections, routes and configuration snapshots are found on the screen
- Routes (reference) — every field of the route, explained one by one
- Permissions (core concept) — what a person may see and change