Skip to main content

Pass incoming messages to the responsible route

"Kessler Logistik" reports pickup, transport, delivery and failed delivery — all through the same queue. On your side, these are four jobs that update four different fields in the delivery. This guide builds "Statusmeldungen Kessler": the route that fetches, looks inside and passes on. At the end there are four rules that pass each message to the responsible route.

What dispatch does in principle and why the order of the rules matters is described under Dispatch.

What you need​

  • The permission Routes at the level Full — see Permissions. Even opening the rules requires Full.
  • A connection to the partner system. In the example, that is "Kessler Logistik".
  • Starting point: Configuration → Routes, then New route.

Xchange saves every entry automatically. It takes effect in operation only with the activated configuration snapshot — that is the last section.

1. Create the dispatch route​

For a dispatch route, the New Route dialog asks for five things. Dispatch exists only as import: the dialog offers the type Dispatch only with direction Import. If you then choose Export, the type jumps back to Processing.

  1. Name: Statusmeldungen Kessler.
  2. Direction: Import.
  3. Type: Dispatch. A dispatch route only passes messages on, instead of processing them.
  4. Data origin: is already set to Queue. The field stays visible and usable, but offers only this one value.
  5. Connection: "Kessler Logistik".
  6. Choose Create.

The creation dialog of a dispatch route with Import, Dispatch and Queue.

Direction, type and data origin cannot be changed after creation — the tooltip "Immutable after creation." says so. If you made a mistake, create the route again.

2. Set up the queue​

The route now knows that it reads from a queue — but not yet from where. That is on the Source data tab:

FieldValue in the example
Fetch endpointevents/pending
Message IDevent_id
Acknowledgment endpointevents/confirm

The Message ID is the most important of the three: by it, Xchange recognizes a single message and acknowledges it. What the three fields mean in detail and where a queue fetch ends is described in Fetch from a queue and acknowledge.

For anyone to fetch at all, the route needs a trigger. In the example, it runs every ten minutes with the run type Drain queue — the way there is described in Run on a schedule.

3. Provide the target routes​

Before a rule can point to a route, the route must be built for it. It appears in the selection only if all four entries match:

EntryValue
DirectionImport
TypeProcessing
Data originDispatch input
Connectionthe same as that of the dispatch route

Pay particular attention to the connection. A flawlessly built target route on a different connection is missing from the selection list, and without comment. In the example, "Abholung Kessler", "Transport Kessler", "Zustellung Kessler" and "Fehlzustellung Kessler" all hang on "Kessler Logistik" — just like the dispatch route itself.

If a target route is missing, create it from the Rule Details via New target route. This opens the same creation dialog, and all fields are open as for an ordinary new route: you can also build a route there that is unsuitable as a target. It is created anyway — Xchange then tells you that it was not selected, and the new route sits there unused. In that case, go through the four entries above before you try a second time.

4. Build the rules​

Before you create the first rule: the order is part of the statement — Xchange stops at the first rule that matches (Dispatch). For building, that means one thing: a rule without a condition matches everything; if it is in first place, it catches every message, and all rules below it have no effect. On screen, that looks like a complete, error-free list. Such a catch-all rule belongs at the end — or it is dropped.

The Dispatch tab appears only on this route. First, store a test message on the right — the next section shows how. The field picker in the condition builds its list from exactly this message; without it, it shows Enter a test message. You can also type the field name by hand, but then it is unchecked.

For each of the four message types:

  1. Choose Add rule. The new row is at the bottom.
  2. The gear at the end of the row opens the Rule Details.
  3. Under Condition: enter status as the field, equals as the operator, picked as the value.
  4. Under Target routes: select "Abholung Kessler". Several are allowed — then the same message goes to each of them, and each gets its own run.
  5. Choose Done.

This produces the four rules, in this order:

RuleConditionTarget route
1status equals pickedAbholung Kessler
2status equals in_transitTransport Kessler
3status equals deliveredZustellung Kessler
4status equals failed OR status equals returnedFehlzustellung Kessler

The fourth shows how two conditions come together: Add condition in the group header creates a second row, and the AND / OR switch next to it applies to the rows of that group — here, OR.

Finally, the row below the list: Otherwise — if no rule matches. In the example, it is set to Manual review, so that every unknown message type stays visibly in place. When the other option is the right one is described under Dispatch.

5. Test before it counts​

To the right of the rule list is the test area. You provide the message yourself; the partner system stays untouched.

  1. Paste a real message into the Test message field, e.g.:

    {
    "event_id": "ev-20261008-0901",
    "shipment_id": "KS-778341",
    "sender_ref": 80234,
    "delivery_no": "80234",
    "status": "in_transit",
    "timestamp": "2026-10-08T09:01:00Z",
    "location": "Verteilzentrum Hannover"
    }
  2. Choose Test.

Under Result, you then see which rule applies and where the message would go — here rule 2 with the target "Transport Kessler". In the Test column of the rule list, each row additionally gets a mark. Pay attention to the gray check mark: it means "also matches, but does not get its turn" and is the only place where you can see a wrong order before it does damage. What the three marks mean exactly is described in Routes — Dispatch.

The test area shows that rule 2 applies and passes on to "Transport Kessler".

Do the counter-check. Enter "status": "customs_hold" and test again: no rule applies, and the result names the otherwise behavior instead. That is exactly what happened on October 8 at 9:05 AM with the shipment KS-778102 — the message has been in Clarification since then, with the cause No dispatch rule. See Clarification.

A test is a pure trial, without passing anything on and without a run. Its only effect: it first saves your open changes to the rules.

Activate​

Your changes are in the draft. Validate it and activate it — only then does the route dispatch. The way there is described in Validate and activate.

What comes next​

See also​