Bring a configuration into the production system
What was built on one system can be transferred to another without typing it in again. For this, Xchange writes a file and reads it back in on the other system.
Up front:
- You add the credentials by hand in the target system. Passwords, tokens and client secrets stay on the source system; only with them can the snapshot be activated.
- The import creates a draft and leaves what exists in place. What exists in the target system and is missing in the file is kept.
In the example: Alongside the production system, Cambira runs a test system. A tenth route has been built there, "Retouren Webshop", and it is now to run in production. A. Vogt exports the snapshot there; M. Brandt imports the file here, because that requires Activation.
What you need
- Reading is enough for the export. The two buttons Export and Export Draft are open to everyone allowed to see the Configuration Snapshots.
- For the import you need the Activation permission at the Full level. With it, the Import button appears in the header of the screen.
- The target system must not be older than the source system. A file from a newer installation cannot be imported into an older one — more on this below.
- You need the credentials that are to be added in the target system. Look them up before you start.
Export: always a whole snapshot
On the Configuration Snapshots screen there are two buttons for exporting:
- Export in the Active Configuration panel exports the active snapshot — what is running right now.
- Export Draft in the Draft panel exports the draft — what is waiting for activation. The button appears only as long as there is a draft.
Everything is always exported. Every file contains the whole snapshot — all connections, all routes, all value tables and everything attached to them: triggers, filters, mappings, steps. That is the reason why the import later shows a decision list.
Xchange suggests a file name that carries the snapshot and the time, e.g.
xchange-config-v12-20261008084500.json; a draft also gets draft in the name.
Keep it — it is the only thing about the file that reveals from the outside where it comes from.
You add the credentials
A transfer gets stuck on the credentials more often than anywhere else. A connection consists of two parts: the description — address, method, time limits — and the secret with which it signs in. Only the first part is in the file.
Xchange says so, too: as soon as the import dialog opens, a warning at the top says that credentials are missing and must be re-entered after the import.
What happens if you miss it: The import goes through, the draft is there — and the check reports an error for every affected connection. Only a snapshot without errors can be activated. So add the credentials before activating — it is quickest if you already have them at hand during the import.
The reason: a configuration file travels by email, through a file share or on a stick; a password in it would be traveling along.
Import: select the file
Import is in the header of the Configuration Snapshots screen. The dialog has two steps; this is the first.
As soon as you have chosen the file, Xchange reads the envelope and shows it before anything happens: Exported With, Source System, Exported At and three numbers — Connections, Routes, Value Tables. Exported With names the version of Xchange that wrote the file, e.g. "Xchange 1.1.0"; for a file that does not carry this detail it shows "—".

Read Source System and Exported At before you continue. It is the only place where you can check whether you have picked the file you meant — and the only opportunity before you make decisions.
The three numbers name exactly the three object types you are about to decide on individually. What is attached to a route — its trigger, its filters, its mapping — travels with the route, without a number of its own.
Replace or merge: the one decision
The question arises when a draft is already open in the target system. Then a selection with two options appears above the file field.
Both words refer to your draft alone.
| What happens with it | |
|---|---|
| Replace | The existing draft is thrown away. Xchange creates a new one — a copy of the active snapshot — and lays the file on top of it. |
| Merge | The existing draft stays as it is. The file is laid on top of it. |
Both leave the configuration in place. Replace, too, starts from the active snapshot instead of a blank sheet — a route that exists here and is missing in the file survives both.
Merge is preselected; it keeps the open draft. Replace throws it away immediately as soon as you import, without any further prompt. If there is a draft you do not know, first look at what is in it — the Compare button shows it line by line: Change a running configuration.
In the example: Vogt's draft, version 8, is open and already checked. Brandt leaves Merge selected, and Vogt's work stays in the draft.
The decision takes effect on the preview immediately. Xchange compares the file with the snapshot it lands on in the end: with Replace the active snapshot, with Merge your draft. So switch here, so that the list in the second step shows what the result will be.
Import: the preview
Next leads to the second step. Xchange now compares every connection, every route and every value table from the file with what is here, and sorts them into three groups:
| Change Type | What it means | What you can choose |
|---|---|---|
| New | Does not exist here yet. | Import or Skip |
| Conflict | Exists here too, with different content. | Overwrite or Skip |
| Identical | Exists here, with the same content. | not applicable — the content already matches |
The rows with Identical are collapsed; Show identical objects shows them. If the file contains only such rows, Xchange says so and locks Import.

Expect a long list, with Skip as the normal case. Because every file contains a whole snapshot, it brings along everything that is on the other system — including objects that are to stay here as they are.
In the example: Brandt sees fourteen objects. One is New — the route "Retouren Webshop", the actual goal, preselected to Import. The three connections are on Conflict, because the test system has its own addresses and its own access; Overwrite is preselected there, and Brandt sets all three to Skip. The remaining ten — nine routes and the value table — are Identical and stay collapsed.
Skip is right for the connections. With Overwrite, "Webshop Cambira" would afterwards carry the test address in the production configuration.
What happens with the skipped connection
The new route points to a connection — does it point into nothing if that connection is skipped?
As long as the connection exists here, the reference stays valid. Xchange redirects the reference to the existing one. The imported route then depends on your connection, with your address and your credentials.
There is one exception. If the connection was New — that is, previously unknown here — and you skip it while importing its route, the point of reference is missing. The route lands in the draft, but the check reports "'Connection' is not a valid reference" for it. If you see this message after an import, this is the cause: either you import the connection afterwards or you enter the right one on the route.
If an object comes from another system and only has the same name, Xchange recognizes this and puts an information icon next to the change type. An Overwrite then takes over the content but keeps the local identity — your runs and your history thus stay attached to the object they already know. If the Overwrite renames an object in the process, the icon says so as well; everything it reports is under Configuration Snapshots.
Import closes the dialog. The result is a draft; it runs only after the activation.
When the file does not go through
Xchange checks in three places.
When you select the file — this is only about the file itself:
- It is not an Xchange export file or it is damaged.
- It is too large; the limit is 10 MB.
On Next — here Xchange compares the content with this installation. Most of the messages say essentially the same thing: the file comes from a newer installation. Either it was exported with a newer version of Xchange — if the file carries its version, the message names both, e.g. "This configuration file was exported with Xchange 1.1.0 and is newer than this installation (Xchange 1.0.0)." — or it contains fields that do not exist here yet.
The way out is the same in both cases, and the message names it: update this installation and import the file again afterwards. The file itself stays as it is. A file from an older installation, on the other hand, Xchange imports.
"The configuration file is incomplete or damaged and cannot be imported." means that the file lacks a part every export file contains — usually because it was edited by hand or cut off in transfer. Export the configuration again.
An unknown field leads to an abort only if it actually contains something; Xchange silently drops an empty one. That is why, between the same two systems, one file can go through and the next can be rejected — depending on whether the new field is filled in it.
A duplicate row has a different cause. If a value table, or the mapping or acknowledgment of a route, contains the same row twice, the message names the affected value table or route. This happens when the file was edited by hand after the export. Export the configuration again and import the new file.
If a condition of the additional data compares a field with another field, Xchange rejects the file as well; the message names the route concerned. In the additional data, a condition compares a field only with a value or placeholder. Change the condition in the exporting system, export again and import the new file.
In the preview — if a route shows Mapping in the file cannot be read or a value table Entries in the file cannot be read, the file cannot be imported as a whole. Import stays locked, even if you set the entry to Skip. Correct the route or value table in the source system and export the configuration there again.
What comes next
- Add the credentials — on every connection that has newly come in.
- Check, and do so before you tell anyone it has been transferred. Missing credentials show up there as errors.
- Activate. Until then the old snapshot keeps running: Validate and activate.
If something has been activated by mistake in the process: Go back to an earlier snapshot.
See also
- Change a running configuration (guide) — when someone besides you is working on the draft
- Connections (reference) — where the credentials are entered
- Configuration Snapshots (core concept) — why there is always a draft at the end