Run a database update
Xchange creates its own structures in SAP Business One, and a new Xchange version brings new ones. Until the database has caught up, Xchange stands still — the Operating state then shows Processing Stopped with the sentence The database is not at the expected state.
The update ends the interruption of operation. Putting it off prolongs the standstill.
What you need
You need the System permission — Full. At Cambira, only M. Brandt has it; for A. Vogt, the System Status menu item is hidden.
Halfway through, the SAP Business One Service Layer must be restarted, and that happens outside of Xchange. The update waits as long as that takes.
What the System Status screen shows in detail is described in the reference under System Status.
Operation has already stopped
The update meets an operation that is already at rest. Until the database is at the expected state, Xchange holds processing of jobs — that is the purpose of the halt. During this time, reading stays possible: you see routes, configuration snapshots and the history; changing and executing are blocked.
Two things follow for planning:
- The best time is now. Every hour of delay is an hour of standstill in the transfer.
- During the run itself, the UI shows only a progress screen. Operation is at rest anyway — the outage does not get bigger because of it.
First read what is pending
The first step is a look: it shows what a click would do.
- Open System Status. The strip at the very top shows the reason.
- Click the Update database button in the Database section. It opens the dialog.
- Wait until the scope has been determined. Xchange checks the database for this; it takes a moment.

If this sentence appears there, you are done. You can open the dialog at any time: it only checks.
If a table appears there, that is the scope of the update. What each row means is described under System Status — Database.
The last row is the most important one. Service Layer restart afterwards says expected to be required or not expected to be required. That is a prediction: whether the restart really becomes due depends on what the run actually created in the end. Expect the restart, even if it says not expected to be required.
When the dialog says it is not possible
Instead of a table, the dialog can also say that the update is not possible right now. The Update button is then missing. There are three groups of reasons, and they lead to quite different next steps.
The Xchange service must be restarted. Either the setup of the database remained incomplete, or the runtime structure is behind the state this update needs. In both cases, the service catches up on its own at the next start. Then open the dialog again.
The Service Layer must be restarted. Then the structure has already been changed and is only waiting for completion — so you are already in the middle of it. Skip to the section about the restart further down.
This Xchange version reaches its limit here. The database has a newer state than the service, there is no path from this state to the expected one, or the database contains a status that this version does not know. Your work ends at this point: the message says so itself and refers you to your administrator.
Update
In the dialog, click Update. The dialog closes, and the UI switches to a progress screen with the notice that the database is being brought to the expected state.
The run works independently of your screen — you can leave it.
After that, there are exactly two outcomes:
- The run created nothing the Service Layer would need to know. Then Xchange continues on its own, and you are done. The Operating state shows Operational again.
- The run created or removed structures. Then Xchange stays stopped, and the strip at the top now says: The database structure has changed. That is the intended intermediate stop.
If the run fails, the strip says so as well. The way out is the same: open the dialog, read, update again.
The restart in between
After a structural change, the Service Layer must be restarted before anything continues. Why that is so is described under System status and license. The restart takes place outside of Xchange.
Xchange waits for as long as it takes — hours or days, it does not matter. Everything stays preserved and valid. The database shows Restart pending, and the state stays until you take the last step.
Finalize
Once the Service Layer has been restarted, click Finalize structural change in the Database section. Xchange asks for confirmation and reminds you that the restart must have taken place beforehand.
Finalize checks by itself whether the restart has taken place: it checks whether the Service Layer knows the changed structure by now — also when the change only removed something. You get one of three answers:
- Finalizing runs. The UI shows a progress screen again, after which Xchange is operational.
- Xchange reports that the Service Layer still has to be restarted. Then the restart is still pending or had no effect; after the restart, click again.
- Xchange reports Restart not confirmed. Then the Service Layer did not answer the check — it is out of service right now, or the restart is still pending. Make sure it was restarted and is running, and click again.
How you can tell it works
- The Operating state shows Operational with the sentence All processing functions are active.
- In the Database section, Configuration structure and Runtime structure both show Up to date.
- The Update database and Finalize structural change buttons have disappeared or are inconspicuous — the work is done.
- The Update history shows the new row with status Completed, your name and the time. That is the proof you can show later.
- In the Execution list, the routes start running again.
Easily confused: fetching the field structure
On the same screen, there is a second section in which a Service Layer restart comes up — Field structure. It belongs to a separate process, apart from the database update: there, it is about fields that someone else created in SAP Business One and that Xchange sees only afterwards. The description is under System Status.
What comes next
After finalizing, Xchange is at the state of the new version, and your configuration is unchanged: routes, connections and configuration snapshots survive an update.
If jobs piled up during the halt, Xchange works through them on its own — the automation starts running again as soon as the operating state allows it. Whatever ended up in Clarification, however, stays put until someone deals with it: Retry failed jobs describes how to take care of several at once.
See also
- System Status (reference) — every state, every reason, every button
- Overview (reference) — where a halt is noticed first
- System status and license (core concept) — why there is a halt and what it means for your work
- Permissions (core concept) — why this page may concern a different person than the others