Connections
The Connections screen manages the target systems Xchange talks to. On the left is the list of all connections, on the right the selected one with all its fields.
What a connection is is explained under Connections.
Permissions
The screen follows the Connections permission:
| Level on Connections | What you can do |
|---|---|
| None | the Connections menu item is hidden |
| Read only | view every connection and each of its fields; the fields are grayed out, and New Connection, Delete, Test connection, Fetch field structure, Replace, Paste sample response and Reset to derived value are hidden |
| Full | create, change all fields, test, delete |
In the example: A. Vogt has Full and builds the connections. M. Brandt has Read only — Brandt sees the same fields, grayed out.

Layout
| Area | Content |
|---|---|
| List (left) | all connections, a search field and the New Connection button |
| Detail (right) | the selected connection in two columns, with a header; the footer appears only when it has something to report |
Both are one page: a click on a row opens it on the right, and the list stays in place.
The list
| Column | Content |
|---|---|
| Name | the name of the connection |
| Type | a tag with REST or SAP Business One |
| Base address | the address at which the target system can be reached |
| Usage | how many routes use this connection |
| Last modified | within the last 24 hours the time since the change (9 hours ago), after that date and time; the exact point in time appears when you point at it with the mouse |
The search field above it filters by name and description. If the search hit the description, it appears below the name. The search term is in the page address and is kept when you reload and when you return from the detail — see History — The filters are in the address.
These indicators can also appear below the name:
| Indicator | Meaning |
|---|---|
| Blocked | Xchange blocked the connection after a fault — routes that use it are at a standstill. The reason is on the connection itself, and a successful connection test lifts the block (below). |
| An edit icon | Someone else has this connection open right now. The tooltip names them. |
If the list is empty or the search finds nothing, the screen says so:
| Situation | What it shows |
|---|---|
| No connection yet | No connection created yet — "Create your first connection — it forms the foundation for all routes." |
| Search without results | No results — "No connection matches your search." |
| Service Layer not reachable | Data not available — "Service Layer currently not reachable — entries cannot be loaded right now." |
| Loading failed | Loading failed — "Connections could not be loaded." |
Creating a connection
New Connection opens a dialog with two fields:
| Field | Meaning |
|---|---|
| Name | Required, at most 150 characters. Only spaces count as empty. |
| Type | Required, REST or SAP Business One. The tooltip reads "Immutable after creation." — the type is fixed once the connection is created. |
The dialog reports an empty required field only when you choose Create: the field turns red with the hint Required, and the dialog stays open. As soon as you fill the field in, the marking disappears.
Create creates the connection and opens it on the right — at first without a sign-in and without an address. Both are added in the detail.
Header and footer
| Element | Effect |
|---|---|
| Delete | removes the connection, provided no route uses it (below) |
| Full screen / Exit full screen / Close | control how much space the detail gets |
| Messages (footer) | appears as soon as something is open, carries a number and opens the list of messages |
| The bar for working through the list (footer) | appears while you work through the checklist |
| The autosave bar (footer) | shows Saving… and Saved, on a fault Error saving with Retry, and when the Service Layer cannot be reached Waiting for Service Layer |
The messages
The button's tooltip reads Messages for this connection. It knows three kinds of entries: errors, warnings and missing required entries.
The number counts the weightiest kind present. If there are errors, it counts the errors; otherwise the warnings; otherwise the missing required entries. The color says what is counted — red, orange or neutral.
The list is unordered, in one piece. Missing required entries appear in it as Missing required entry or, if there are several, as Missing required entries: 3. A click on an entry takes you to its field.
A newly created connection shows its missing required entries only here at first. After the next validation of the draft they count as errors: the button turns red, and the field shows it.
On the field itself an error is shown in red and a warning in orange. A blue mark Being re-checked means that Xchange is evaluating your last input right now — it disappears as soon as the result is in. The field for the client secret or password stays unmarked while you type; it is evaluated only once it has been saved.
Working through the checklist
If you come here through Work through checklist on the Configuration Snapshots screen, the footer carries the bar for working through the list. What it shows is described under The bar for working through the list.
Saving
Xchange saves every input by itself; the autosave bar in the footer shows the state. Only the secret is confirmed with its own Save — see Credentials. If someone else has changed the same connection in the meantime, the bar offers Reload and Save anyway.
Notices above the form
| Notice | When it appears |
|---|---|
| "Currently being edited by … — your changes may conflict" | Someone else has the connection open right now. |
| "You are already editing this record in another session …" | You have the connection open yourself in a second session. If both apply, the strip names the other person. |
| "An existing connection addresses the same target: …. Check whether you can use the existing connection instead." | A change to the base address, the company database or the authentication type was saved, and another connection addresses the same target. If there are several, it reads "Existing connections address the same target: …. Check whether you can use one of them instead." Up to five names are given; beyond that, "… and … more" follows. |
| The block notice | The connection is blocked. |
The notice about the same target is only a notice: the connection is saved, and both remain usable. It does not appear when you merely open a connection.
When the detail cannot be loaded
Three situations replace the whole content of the detail:
| Situation | What it shows |
|---|---|
| Service Layer not reachable | Data not available — "Service Layer currently not reachable — entries cannot be loaded right now." |
| Runtime store not reachable | Data not available — "Runtime store currently not reachable — entries cannot be loaded right now." |
| Connection no longer there | Connection is no longer available — "This connection was deleted or removed after the configuration changed.", plus Back to connections |
General
| Field | Meaning |
|---|---|
| Name | Required, at most 150 characters. The name under which the connection appears in lists and on routes. |
| Description | Free, multi-line text, at most 254 characters. The search in the list finds it too. |
| Type | Display only — the connection type chosen at creation. |
Technical configuration
| Field | Meaning |
|---|---|
| Base address | Required. The address at which the target system can be reached — for REST the common root of all fetch endpoints, for SAP Business One the address of the Service Layer. |
In the example: https://shop.cambira.example.com/api for "Webshop Cambira",
https://sap-at.cambira.intern:50000 for "Cambira Austria".
Authentication
Authentication type
The selection is offered for REST connections. An SAP Business One connection knows only the Service Layer login — there the selection is omitted and only its fields appear.
| Value | Additional fields |
|---|---|
| No authentication | — |
| OAuth 2.0 | Token endpoint, Client ID, plus a Client secret |
| Service Layer login | Company database, User name, plus a Password |
| Field | Meaning |
|---|---|
| Token endpoint | Required with OAuth 2.0. The address at which Xchange obtains the access token — e.g. https://shop.cambira.example.com/oauth/token. |
| Client ID | Required with OAuth 2.0. The identifier under which the target system knows Xchange. |
| Company database | Required with the Service Layer login. The name of the database that is worked in — e.g. CAMBIRA_AT. |
| User name | Required with the Service Layer login. The user Xchange signs in with. |
Credentials
With OAuth 2.0 and with the Service Layer login, the state of the credentials appears below the fields — Configured or Not configured — and next to it Replace.
Replace opens a single input field, labeled Client secret with OAuth 2.0 and Password with the Service Layer login, plus Save and Cancel. Save becomes active only once something has been entered.
A stored secret can only be replaced. The display therefore only says whether one exists.
Test connection
Test connection first checks the required entries — base address, authentication type, token endpoint, client ID and the credentials. If one of them is missing, Xchange reports it, and the test is skipped.
Otherwise the test runs (Testing connection…) and the result appears as a strip with the timestamp Last tested.
| Result | Meaning |
|---|---|
| Succeeded | Xchange reached the target system and signed in. If the test learned which company it is talking to, its name follows. |
| Address not found | The base address leads nowhere. |
| No response from target | The address is correct, but no answer came within the expected time. |
| Connection failed | The network refuses the connection. |
| Secure connection failed | Setting up the encrypted connection failed — usually because of a certificate. |
| Sign-in failed | The target system rejected the credentials. |
| Access denied | The sign-in went through, but the account lacks rights. |
| Target system error | The target system answers with an error of its own. |
| Invalid configuration | The entries contradict each other at one point. |
| Unexpected result | The answer falls outside all the situations listed. |
Usually the result is followed in the same strip, after a colon, by what caused it — with the Service Layer login, e.g. "Sign-in failed: Sign-in was refused — check user name, password and company database". Below it, a gray line Technical details: … may appear.
The block notice
If the target system rejected the credentials during operation, a notice appears above the form: "The target system rejected the stored credentials. This connection is blocked — no routes run. Re-enter the credentials and test the connection to lift the block." If decrypting the credentials failed, the same notice appears there with this cause.
A successful connection test lifts the block. As soon as Test connection answers with Succeeded, the connection is free again, and the routes that use it run again on their next trigger. If the credentials were in order — for example because the target system only rejected them temporarily —, the test alone is enough.
If the stored technical parameters cannot be read, Xchange blocks the connection as well — this only happens after an import or a write through the programming interface, never after input in this form. The notice then reads: "The stored technical parameters cannot be read. This connection is blocked — no routes run. Enter the parameters again, then switch automation back on." Xchange does not overwrite the damaged content on its own. The connection has no automation that could be switched on here: enter the connection's fields again and click Test connection — a successful test lifts this block too. Automation is switched per route on Execution; the block does not change it.
The notice appears only when there is a fault. Why Xchange blocks at all is explained under Connections.
Field structure
The section looks different depending on the connection type.
With SAP Business One, Xchange reads the structure itself. Here there is only the button Fetch field structure.
With REST, the origin of the field structure can be entered. For this, two fields stand in front of the button:
| Field | Meaning |
|---|---|
| Source | The path at which the target system provides its field structure — e.g. openapi.json. At most 254 characters. |
| Format | No field structure, Shopware field structure (version 6 and later) or OpenAPI (version 3.0 and 3.1). |
Fetch field structure fetches the structure from the target system again and checks the connection along the way. If Source or Format is empty, Xchange reports "Field structure source and format not configured", and the fetch is skipped.
Otherwise the fetch runs (Fetching field structure…) and the result appears as a strip of its own with the timestamp Last fetched:
| Result | Meaning |
|---|---|
| Field structure fetched — 247 objects found. | The fetch worked; the number says how many object types the structure describes. For a single one it reads "Field structure fetched — 1 object found." |
| The field structure is currently unreachable. Try again later. | A temporary fault — the next attempt may succeed. |
| The field structure could not be fetched. Check the source and format. | With REST: a permanent fault — the next attempt first needs a change to the two fields. |
| The field structure could not be fetched. Check user name, password and company database. | With SAP Business One: a permanent fault — the next attempt first needs a change to the login. |
This strip and the one of the connection test are two different ones. They have their own results and their own timestamps — Last tested versus Last fetched —, and each speaks only for itself.
Validating the draft reports the state of the field structure on the connection. With SAP Business One and with REST where a Source is entered, the fetch counts, not the connection test:
| Finding | Kind | Meaning |
|---|---|---|
| "Field structure never fetched — fetch field structure" | Warning | The routes of this connection were checked against no field structure. A click on Fetch field structure fixes it. |
| "The connection's field structure cannot be read — check the connection and fetch the field structure again" | Error | The last fetch failed permanently. |
| "Field structure could not be read just now — dependent rules not checked, fetch field structure" | Warning | The connected system did not answer during the check. |
The first two findings disappear only with a fetch that succeeds — a changed Source alone is not enough.
The draft check needs the field structure of every connection in use and reads it from the connected system where needed. If the connected system does not answer, the check reports that as a warning at the connection and leaves out the rules that need the field structure — it does not report them as passed. The check itself does not fail because of it.
Batch fetch
The section appears only for REST connections. It tells Xchange how to ask the system for a data set, where in its answer to find what, and how to take along only what has changed.
| Field | Meaning |
|---|---|
| Records | Where in the answer the list of records is — e.g. data. |
| Paging | How the system delivers the next page: None, Page number, Offset or Next page token. |
| Page parameter | The name under which Xchange sends the page number or the offset — e.g. page or offset. Visible only with Page number and Offset, and then required. At most 50 characters. |
| Size parameter | The name under which Xchange sends the page size — e.g. limit. Visible and required like Page parameter. At most 50 characters. |
| Sort | How the system sorts ascending by a field, with the placeholder {{field}} — e.g. sort={{field}}. Visible like Page parameter, optional. At most 254 characters. |
| Token parameter | The name under which Xchange sends the token when fetching the next page — e.g. cursor. Visible only with Next page token, and then required. At most 50 characters. |
| Token path | Where in the answer the token for the next page is — e.g. meta.next_cursor. Visible and required like Token parameter. |
| More pages | Where the answer says that another page follows — e.g. meta.has_more. Visible like Token parameter, optional. |
Below follows the group Read changes only. There Detect changes sets who recognises what has changed in an incremental run; only the fields of the chosen option are visible:
| Field | Meaning |
|---|---|
| Detect changes | Xchange filters after reading (default), Source filters by date or Source returns a change token. |
| Filter from | How the system delivers only records from a value onwards: a piece of the query with the placeholders {{field}} for the field and {{value}} for the value — e.g. {{field}}[gte]={{value}}. Xchange inserts both and sends the rest as it stands. Visible only with Source filters by date, and then required. At most 254 characters. |
| Change token parameter | The name under which Xchange sends the remembered change token — e.g. since. Visible only with Source returns a change token, and then required. At most 50 characters. |
| Change token path | Where in the answer the token is from which the system delivers the changes on the next run — e.g. changeToken. Visible and required like Change token parameter. |
An empty field is not specified. Xchange inserts no value for it and looks in no other place.
If a route fetches through this connection, Records is required. Without the entry, validating the draft reports ""Records" is missing". If the connection serves only as a target, the field is ignored.
How Xchange pages:
| Paging | How Xchange reads |
|---|---|
| None | One request per run, so only the first page. |
| Page number | Page 1, 2, 3 … with the page size, until a page comes back empty. |
| Offset | From 0, then one page size further each time, until a page comes back empty. |
| Next page token | From token to token, until the answer carries no token or More pages reports that nothing follows. |
A short page does not end the read — only an empty page or the end of the tokens does.
How Xchange reads only changes follows from Detect changes:
| Detect changes | How Xchange reads in an incremental run |
|---|---|
| Xchange filters after reading | Every run reads everything, and the route's change filter lets only what has changed through. |
| Source filters by date | Xchange asks through Filter from only for the records from the remembered position of the change filter onwards. |
| Source returns a change token | Xchange sends the token of the last run, the system delivers only the changes since then, and Xchange remembers the new token for the next run. The first run reads everything. The route needs no change filter for this. |
Fields of an option that is not chosen stay stored, but have no effect and are not checked. If a required field of the chosen option is missing, the check reports the missing field, and an incremental run is not possible; Start run then gives the reason "The connection lacks details for the chosen change detection. Complete them on the connection to make incremental runs possible."
Without a sort, the pages can turn out differently from one query to the next with Page number and Offset. The Sort is not a required field — a full run does without it. If it is missing there, however, the check reports "Connection is not set up to read in sorted order" at the Run type of a route with an incremental run type — see Routes — Automation. With Source returns a change token this does not apply.
The templates need their placeholders. If one of the two is missing in Filter from, the field
reports "Field or value placeholder missing"; if {{field}} is missing in Sort, it reports "No
field placeholder".
With a Shopware field structure, the read fields are prefilled. If you set the Format of the field structure to Shopware field structure (version 6 and later), Xchange fills the empty fields among Paging, Page parameter, Size parameter, Sort, Detect changes and Filter from with the values Shopware understands; Paging set to None and Detect changes set to Xchange filters after reading count as empty. Whatever is already entered stays. You can change every field; Reset to derived value next to the field restores the Shopware value.
If the answer does not match the entries, the run aborts. If there is no list under Records
or More pages reports more without a token for the next page being present, the
run ends as Failed with the reason Connection does not match the response — see
Execution — Last run. Only an empty list or null in that place
counts as an empty page.
Paste sample response opens a dialog into which a real answer of the system is pasted: "Paste one response from this system. It fills the suggestion lists for the fields below and is not saved." If the text is not valid JSON or only a single value, the dialog says so and stays open.
The suggestions from the sample response are kept as long as the screen is open. Without a pasted sample response the lists say "Paste a sample response, or enter the path directly." — you can still type the path.
Data spelling
The section tells Xchange how the connected system writes its values; it concerns only that system's side.
| Field | Options | Default |
|---|---|---|
| Dates with slashes | Day first (10/01 = 10 January), Month first (10/01 = 1 October) | Day first |
| Numbers | 1234.56, 1.234,56 | 1234.56 |
Unlike Batch fetch, the section appears on every connection.
The setting only applies to ambiguous values. 25/12/2026 is December 25, whatever
is set — 25 can only be the day. Only 05/12/2026 needs the answer: with Day
first it is December 5, with Month first May 12.
Xchange always reads dates with dots day first. 10.01.2027 is January 10, whatever is
set; the setting only concerns dates with slashes.
The setting belongs to the connection. It applies whether the connection is the source or the target in a route.
One of the two spellings is always set. Xchange always reads the values according to this setting.
The hint below the field
A sentence can appear below the selection: "The route's sample data looks like "Month first (10/01 = 1 October)"."
It appears only when what was seen differs from the setting, and disappears as soon as you switch to the spelling named. You change the setting yourself; Xchange leaves it as it is.
Used in routes
The list of all routes that use this connection, each row with name, object and the direction. A click opens the route.
If no route uses the connection, this shows Not used — "No route uses this connection."
In the example: "Webshop Cambira" lists "Bestellungen Webshop" and "Artikel Webshop" here, "Kessler Logistik" six routes.
Deleting a connection
Delete asks for confirmation: "The connection '…' will be deleted. This action cannot be undone." You confirm with Delete.
Only an unused connection is deleted. Instead of the confirmation, a notice then appears saying how many routes use it and that the references must be removed first.
What else applies
- A change here takes effect only with activation. It is in the draft and applies in operation with the activated configuration snapshot — see Validate and activate.
- The connection test checks immediately. It queries the target system with the entries currently in the draft — even before activation.
- A connection cannot be paused. Pausing and resuming is per route — on Execution, in the list or in the route's details. This screen only shows whether Xchange has blocked the connection.
- The type is fixed once the connection is created.
See also
- The first connection (getting started) — the way from the empty list to a passed connection test
- Routes (reference) — the route that uses a connection
- Connections (core concept) — what a connection is and when Xchange blocks it
- Permissions (core concept) — what the levels on Connections mean