Skip to main content

Create a connection

Cambira has taken on a logistics provider: "Kessler Logistik" is to handle deliveries from now on and report back their processing status. Before a single route can be created, Xchange must know the system — address, sign-in, and where it learns which fields exist there.

The steps follow what A. Vogt did on September 30, 2026 — from creating the connection to the point at which a route can use it.

After the passed connection test, the field structure still follows (step 4).

What you need​

  • The Connections permission at the Full level — see Permissions.
  • From the foreign system: the base address, the credentials and — if available — the address of its interface description. The last one is almost always missing at the first meeting; it can be added later, see step 4.
  • Starting point: Configuration → Connections → New Connection.

Xchange saves every entry automatically. In operation, it takes effect only with the activated configuration snapshot.

1. Create: name and type​

The New Connection dialog asks two things, and the second decides everything else.

  1. Name: Kessler Logistik. It later appears in every route list — choose the name by which the system is known in-house.
  2. Type: REST or SAP Business One.
  3. Create.

The type cannot be changed afterwards. In the detail view it appears only as text. A typo costs the connection — in that case, create a new one and delete the wrong one, as long as its Used in routes list is empty.

It also branches the entire rest of the screen:

RESTSAP Business One
Sign-inYou choose the kind — e.g. OAuth 2.0always Service Layer login
Additional required field—Company database
Field structureYou enter Source and Formatthe system brings it along
Batch fetchpresentnot applicable — SAP Business One describes its responses itself

For Kessler, the type is REST. The SAP case is walked through with a complete example in Transfer master data into a second company.

2. Enter address and sign-in​

The Technical configuration section holds the base address: https://edi.kessler-logistik.example.com/v2. It is the common beginning of all calls; the routes carry the individual paths later.

In the Authentication section, choose the Authentication type OAuth 2.0. Two fields appear below it, which you fill from Kessler's credentials:

  • Token endpoint: https://edi.kessler-logistik.example.com/oauth/token
  • Client ID: cambira-xchange

Below them is the Client secret, initially in the state Not configured:

  1. Click Replace next to it. An input field opens.
  2. Enter the client secret and click Save.

The state changes to Configured. The secret is stored encrypted, and from then on only this state is displayed; how to replace it later is described in Replace credentials.

The sign-in of a REST connection with OAuth 2.0 and a stored client secret, before the first connection test.

3. Test the connection​

Test connection sends a real call to the system and reports the result in a green or red banner. For Kessler it was green at 9:16 AM — one minute after the connection was created.

The banner remembers its result: Succeeded with Last tested: Sep 30, 2026, 9:16 AM is still there tomorrow. Whether it is still true then, only a new test shows.

For an SAP connection, the green banner also names the company in which the call landed. That is the real check there: the address can be correct and still hit the wrong company.

Which result stands for what is listed in full in Connections. One of them has a consequence beyond the banner: A failed test holds up the activation — the check reports the connection as an error. What the check says about an untested connection is described in The first connection.

4. Set up the field structure​

This step is easy to overlook. The connection works, the banner is green — and the first route still shows an empty list in every field selection.

The Field structure section answers a different question than the test: which objects and fields exist there. For a REST connection, it consists of two entries:

FieldFor KesslerWhat it means
Sourceopenapi.jsonthe path to the interface description, below the base address
FormatOpenAPI (version 3.0 and 3.1)in which language this description is written

Below them is Fetch field structure. The button fetches the description and reports how many objects it found — for Kessler at 9:18 AM.

As long as one of the two fields is empty, the routes get empty lists — and silently so. The selection of the Fetch endpoint stays empty, and so does the field selection. That is the state every new connection starts in: Format is set to No field structure. So if the list stays empty, check the connection first.

If your system permanently has no description, No field structure is the right setting — how to map in that case is described in When the field selection stays empty.

What test and fetch each check​

The connection shows two banners with two timestamps — Last tested and Last fetched.

For "Webshop Cambira" they are far apart: the connection test is from Oct 8, 2026, 8:44 AM, the field structure from Oct 2, 2026, 4:05 PM. Both are fine. A green test only says that the system answers — only fetching tells you about the field structure.

The relationship is one-sided:

You press …… and thereby check
Test connectiononly the connection
Fetch field structurethe field structure and with it the connection

Fetching is therefore the more thorough of the two buttons — and the only place where you see before the first route whether the description is readable at all. Press it as soon as Source and Format are set, and again when the foreign system has changed its description.

What else is on the connection​

The screen holds more than these four steps touch. Two sections are worth a look as soon as the first route runs:

  • Batch fetch — where in the system's response the records are. If a route reads a data set from this connection, Records is required. If a run ends with "Connection does not match the response", see When the external system responds differently than expected.
  • Used in routes — which routes depend on this connection. The connection can be deleted only once this list is empty.

All fields and all results in full: Connections.

What comes next​

See also​