Fetch from a queue and acknowledge
"Kessler Logistik" reports every change to a shipment — picked up, in transit, delivered, failed — and puts it into a queue for this. You set up the route "Statusmeldungen Kessler", which checks there every ten minutes, fetches each message and confirms to Kessler that it has arrived.
A queue behaves differently from a dataset. Xchange accepts what is handed to it instead of searching and filtering. And a message disappears there only once Xchange has acknowledged it. If the acknowledgment is missing, you get the same message again the next time.
What you need
- The Routes permission at the Full level — see Permissions.
- A connection to the system that runs the queue — in the example "Kessler Logistik". How one is created is described under Create a connection.
- Three details from the operator of the queue: where to fetch, which field uniquely names a message and where the confirmation goes.
- Starting point: Configuration → Routes, then New Route.
Xchange saves every entry automatically. In operation, it takes effect only with the activated configuration snapshot.
1. Set the route to the queue
In the New Route dialog:
- Name:
Statusmeldungen Kessler. - Direction: Import.
- Type: Dispatch — the route passes each message on to the responsible target route.
- Data origin: Queue. With this type, it is the only choice.
- Connection: "Kessler Logistik".
- Choose Create.
With the data origin Queue, the Source data tab changes: Data filter and Change filter disappear. Both belong to a dataset that Xchange looks through — here the source system hands out what it considers due, and Xchange accepts it as it is. Instead, a section appears that only the queue has: Acknowledgment.
2. Say where to fetch
In the Data source section:
- Fetch endpoint:
events/pending. - Fetch returns: one message — Kessler hands out exactly one report per fetch.
How many messages a fetch brings is decided by the partner system — you only mirror it. Many queues hand out several messages at once, in a list. That is why a new queue route starts out on several messages. If the test message contains such a list, the editor suggests several messages; only you switch it. With a connection to SAP Business One the choice is missing: there every fetch brings one message.
| Fetch returns | What Xchange does with a response |
|---|---|
| one message | The whole response is the message; envelope, next page token and the indication of more pages are left out of it. |
| several messages | Each entry of the list is a message and is processed and acknowledged on its own. Where the list sits in the response is stated by the connection in its Records field. |
If the connection is not set up for lists, the editor reports "Connection is not set up for several messages per fetch". Then fill in Records on the connection.
Xchange calls the endpoint repeatedly until the queue is empty. Empty means three things, and
each ends the run: the source system responds without content (HTTP 204), with an empty body —
{} and [] count the same —, or with an empty list. A run with seventeen single messages has
thus fetched eighteen times; the last fetch is the empty one.
If a fetch brings only messages that were already there in this run, the run ends. That happens when the source system hands out a message again although it has been acknowledged — e.g. because it processes the acknowledgment with a delay. Xchange creates no second job for such a message and tries again in the next run.
3. Specify the message ID
Enter event_id as the Message ID — the path to the field with which Kessler numbers the
messages.
This field decides what happens with a duplicate delivery, and this field alone can. A queue promises to deliver each message at least once — so twice is possible. If the same message comes a second time:
- With a message ID, Xchange recognizes it. If the content is the same, the second job ends as Skipped (no change); it is posted once. If the content differs although the ID is the same, the job goes to Clarification — then someone has changed something afterwards, and a person should look at it.
- Without a message ID, every delivery is a new message for Xchange. With one message the field is technically optional; leave it empty only if the source system delivers without an ID — and then expect duplicates.
With several messages the message ID is required. Without it, Xchange could neither tell the entries of a list apart nor acknowledge them one by one. If a message lacks the ID in operation, Xchange stops the route; it then shows Paused (fault).
The ID accompanies the job afterwards: it appears in the History for each job under Message ID and can also be searched there.
4. Set up the acknowledgment
In the Acknowledgment section:
-
Acknowledgment endpoint:
events/confirm. -
Create a row. Each row has a Target field — its name in the confirmation — and a Source the value comes from:
Target field Source event_idevent_id
Kessler needs no more: the confirmation must say which message has arrived, and the ID says exactly that. Until the first row, it says No acknowledgment fields.
If the source system expects a fixed entry beside the ID, e.g. "result": "success", add a
second row for it: Target field result, then switch the Source to Constant with the button
at its left edge and enter success.
Some systems expect the ID in the endpoint rather than in the confirmation, e.g.
membership-applications/{{id}}/ack. With every acknowledgment, the placeholder in curly braces
is replaced by the message's ID — {{id}} becomes, say, A-1. Its name is up to you. The button
with the key next to the field inserts it at the cursor; it appears as soon as a Message ID is
entered. The endpoint may contain only one placeholder, and a placeholder needs a Message
ID — otherwise the editor marks the Acknowledgment endpoint with a message naming the
problem.
With several messages the Acknowledgment endpoint is required: each message of the list is confirmed on its own.

When it acknowledges, and what the acknowledgment states. Xchange confirms a message as soon as it is stored permanently — before processing ends. So the acknowledgment means "arrived"; posting comes afterwards. Consequence: if a job fails later — e.g. because a required field stays without a value —, it is in Clarification but has long been acknowledged. It has disappeared from the queue and is thus out of reach for later runs. Either the source system sends it again, or someone decides the case by hand.
5. Create the schedule
A queue is drained regularly. On the Automation tab, create a scheduled trigger: Frequency
Every N minutes, Interval 10. The only Run type on offer is Drain queue. The path in
detail is described under Run on a schedule.
Most of these runs find the queue empty, and that is the normal case. If Items per cycle limits the run, each message counts on its own — the entries of a list too. If the run ends in the middle of a list, the rest stays unacknowledged and comes again in the next run.
This run type stands alone: a queue route has exactly one trigger — a further scheduled trigger or an event trigger beside it is ruled out.
6. Activate and release
- Validate and activate the configuration snapshot — see Validate and activate.
- Switch to Execution and flip the switch in the Automation column for this route. Only then does the schedule fetch.
When the acknowledgment is missing
The queue always hands out the oldest message not yet acknowledged. An unacknowledged message thus blocks everything behind it — that is why Xchange stops on a failed acknowledgment.
| What happens | What Xchange does |
|---|---|
| The acknowledgment fails temporarily — the source system is unreachable at the moment | The run ends at this point. The next run fetches the same message again, recognizes it by the message ID and acknowledges it afterwards. This happens on its own. |
| The acknowledgment fails permanently — the endpoint is wrong, rejects the confirmation or contains a placeholder for which the message brings no ID | Xchange blocks the route's automation if it is switched on, and the run ends Failed with the reason "Source system rejected the acknowledgment". The jobs keep their status — they were processed; what stays behind is the message in the queue. |
You recognize the block on Execution: the route shows Paused (fault), and a notice strip reports "Acknowledging the fetched messages failed permanently — automation is blocked." Then check the Acknowledgment endpoint and the acknowledgment rows, and switch automation back on afterwards. Or start the route by hand with Start run: if the source system accepts an acknowledgment during that run, Xchange lifts the block itself. Until then it stays — it prevents the same message from going round in circles for hours.
What comes next
What becomes of an arrived and confirmed message is decided by the route: in the example, "Statusmeldungen Kessler" passes it on to one of four target routes, depending on the status. That is a task of its own — see Pass incoming messages to the responsible route.
See also
- Find and trace a single job (guide) — find a specific message again by its message ID
- Routes — Source data (reference) — all fields of the Data source and Acknowledgment sections
- Dispatch (core concept) — how a message finds its responsible route
- Execution (core concept) — what a run is and what it summarizes