Zum Hauptinhalt springen

Aus einer Warteschlange abholen und quittieren

„Kessler Logistik“ meldet jede Änderung an einer Sendung – abgeholt, unterwegs, zugestellt, fehlgeschlagen – und legt sie dazu in eine Warteschlange. Sie richten die Route „Statusmeldungen Kessler“ ein, die dort alle zehn Minuten nachsieht, jede Nachricht abholt und Kessler bestätigt, dass sie angekommen ist.

Eine Warteschlange verhält sich anders als ein Datenbestand. Xchange nimmt entgegen, was ihm gereicht wird, statt zu suchen und zu filtern. Und eine Nachricht verschwindet dort erst, wenn Xchange sie quittiert hat. Bleibt die Quittung aus, bekommen Sie dieselbe Nachricht beim nächsten Mal noch einmal.

Was Sie brauchen​

  • Die Berechtigung Routen in der Stufe Voll – siehe Berechtigungen.
  • Eine Anbindung an das System, das die Warteschlange führt – im Beispiel „Kessler Logistik“. Wie eine entsteht, steht unter Eine Anbindung anlegen.
  • Vom Betreiber der Warteschlange drei Angaben: wo abgeholt wird, welches Feld eine Nachricht eindeutig benennt und wo die Bestätigung hingeht.
  • Einstieg: Konfiguration → Routen, dann Neue Route.

Xchange sichert jede Eingabe automatisch. Im Betrieb wirkt sie erst mit dem aktivierten Konfigurationsstand.

1. Die Route auf die Warteschlange stellen​

Im Dialog Neue Route:

  1. Name: Statusmeldungen Kessler.
  2. Richtung: Import.
  3. Typ: Verteilung – die Route gibt jede Nachricht an die zuständige Zielroute weiter.
  4. Datenherkunft: Warteschlange. Bei diesem Typ ist sie die einzige Wahl.
  5. Anbindung: „Kessler Logistik“.
  6. Anlegen wählen.

Mit der Datenherkunft Warteschlange verändert sich der Reiter Quelldaten: Datenfilter und Änderungsfilter verschwinden. Beide gehören zu einem Datenbestand, den Xchange durchsieht – hier reicht das Quellsystem heraus, was es für fällig hält, und Xchange nimmt es so an. Dafür erscheint ein Abschnitt, den nur die Warteschlange hat: Quittierung.

2. Sagen, wo abgeholt wird​

Im Abschnitt Datenquelle:

  1. Abrufendpunkt: events/pending.
  2. Abruf liefert: eine Nachricht – Kessler gibt bei jedem Abruf genau eine Meldung heraus.

Wie viele Nachrichten ein Abruf bringt, legt das Partnersystem fest – Sie bilden es nur nach. Viele Warteschlangen geben mehrere Nachrichten auf einmal heraus, in einer Liste. Deshalb steht eine neue Warteschlangenroute zunächst auf mehrere Nachrichten. Enthält die Testnachricht eine solche Liste, schlägt der Editor mehrere Nachrichten vor; umgestellt wird nur von Ihnen. Bei einer Anbindung an SAP Business One fehlt die Wahl: Dort bringt jeder Abruf eine Nachricht.

Abruf liefertWas Xchange mit einer Antwort tut
eine NachrichtDie ganze Antwort ist die Nachricht; Umschlag, Token für die nächste Seite und der Hinweis auf weitere Seiten bleiben dabei außen vor.
mehrere NachrichtenJeder Eintrag der Liste ist eine Nachricht und wird einzeln verarbeitet und einzeln quittiert. Wo die Liste in der Antwort steht, sagt die Anbindung in ihrem Feld Datensätze.

Ist die Anbindung nicht für Listen eingerichtet, meldet der Editor „Anbindung ist nicht für mehrere Nachrichten je Abruf eingerichtet“. Tragen Sie dann bei der Anbindung Datensätze nach.

Xchange ruft den Endpunkt wiederholt auf, bis die Warteschlange leer ist. Leer heißt dreierlei, und jedes beendet den Lauf: das Quellsystem antwortet ohne Inhalt (HTTP 204), mit einem leeren Rumpf – {} und [] gelten genauso –, oder mit einer leeren Liste. Ein Lauf mit siebzehn einzelnen Nachrichten hat also achtzehn Mal abgerufen; der letzte Abruf ist der leere.

Bringt ein Abruf nur Nachrichten, die in diesem Lauf schon da waren, endet der Lauf. Das geschieht, wenn das Quellsystem eine Nachricht erneut herausgibt, obwohl sie quittiert ist – etwa weil es die Quittung verzögert verarbeitet. Xchange legt für eine solche Nachricht keinen zweiten Vorgang an und versucht es beim nächsten Lauf wieder.

3. Die Nachrichtenkennung angeben​

Tragen Sie als Nachrichtenkennung event_id ein – den Pfad zu dem Feld, mit dem Kessler die Nachrichten durchnummeriert.

Dieses Feld entscheidet, was bei einer doppelten Zustellung passiert, und allein dieses Feld kann es. Eine Warteschlange verspricht, jede Nachricht mindestens einmal zu liefern – zweimal ist also möglich. Kommt dieselbe Nachricht ein zweites Mal:

  • Mit Nachrichtenkennung erkennt Xchange sie wieder. Ist der Inhalt derselbe, endet der zweite Vorgang als Übersprungen (Keine Änderung); verbucht wird einmal. Weicht der Inhalt ab, obwohl die Kennung dieselbe ist, geht der Vorgang in die Manuelle Klärung – dann hat jemand etwas nachträglich geändert, und das soll ein Mensch ansehen.
  • Ohne Nachrichtenkennung ist jede Zustellung für Xchange eine neue Nachricht. Bei eine Nachricht ist das Feld technisch freiwillig; lassen Sie es nur dann leer, wenn das Quellsystem ohne Kennung liefert – und rechnen Sie dann mit Doppelungen.

Bei mehrere Nachrichten ist die Nachrichtenkennung Pflicht. Ohne sie könnte Xchange die Einträge einer Liste weder auseinanderhalten noch einzeln quittieren. Fehlt einer Nachricht im Betrieb die Kennung, hält Xchange die Route an; sie steht dann auf Pausiert (Fehler).

Die Kennung begleitet den Vorgang danach: Sie steht im Verlauf bei jedem Vorgang unter Nachrichtenkennung und ist dort auch durchsuchbar.

4. Die Quittierung einrichten​

Im Abschnitt Quittierung:

  1. Quittierungsendpunkt: events/confirm.

  2. Eine Zeile anlegen. Jede Zeile hat ein Zielfeld – so heißt es in der Bestätigung – und eine Quelle, aus der der Wert stammt:

    ZielfeldQuelle
    event_idevent_id

Mehr braucht Kessler nicht: Die Bestätigung muss sagen, welche Nachricht angekommen ist, und die Kennung sagt genau das. Bis zur ersten Zeile steht dort Keine Quittierungsfelder.

Erwartet das Quellsystem neben der Kennung einen festen Eintrag, z. B. "result": "success", legen Sie dafür eine zweite Zeile an: Zielfeld result, und die Quelle stellen Sie mit der Schaltfläche am linken Rand auf Konstante und tragen success ein.

Manche Systeme erwarten die Kennung im Endpunkt statt in der Bestätigung, z. B. membership-applications/{{id}}/ack. Der Platzhalter in geschweiften Klammern wird bei jeder Quittung durch die Nachrichtenkennung der Nachricht ersetzt – aus {{id}} wird etwa A-1. Sein Name ist frei wählbar. Die Schaltfläche mit dem Schlüssel neben dem Feld fügt ihn an der Schreibmarke ein; sie erscheint, sobald eine Nachrichtenkennung eingetragen ist. Der Endpunkt darf nur einen Platzhalter enthalten, und ein Platzhalter verlangt eine Nachrichtenkennung – sonst markiert der Editor den Quittierungsendpunkt mit einer Meldung, die das Problem benennt.

Bei mehrere Nachrichten ist der Quittierungsendpunkt Pflicht: Jede Nachricht der Liste wird einzeln bestätigt.

Der Abschnitt Quittierung mit Endpunkt und einer Quittierungszeile.

Wann quittiert wird, und was die Quittung aussagt. Xchange bestätigt eine Nachricht, sobald sie dauerhaft gespeichert ist – vor dem Ende der Verarbeitung. Die Quittung heißt also „angekommen“; das Verbuchen kommt danach. Folge: Scheitert ein Vorgang später – etwa weil ein Pflichtfeld ohne Wert bleibt –, liegt er in der Manuellen Klärung, ist aber längst quittiert. Aus der Warteschlange ist er verschwunden, für spätere Läufe also außer Reichweite. Entweder schickt das Quellsystem ihn erneut, oder jemand entscheidet den Fall von Hand.

5. Den Zeitplan anlegen​

Eine Warteschlange wird regelmäßig geleert. Legen Sie im Reiter Automatik einen zeitgesteuerten Auslöser an: Häufigkeit Alle N Minuten, Intervall 10. Als Lauftyp steht nur Warteschlange leeren zur Wahl. Der Weg im Einzelnen steht unter Nach Zeitplan laufen lassen.

Die meisten dieser Läufe finden die Warteschlange leer, und das ist der Normalfall. Begrenzt Datensätze pro Zyklus den Lauf, zählt jede Nachricht einzeln – auch die Einträge einer Liste. Endet der Lauf mitten in einer Liste, bleibt der Rest unquittiert und kommt beim nächsten Lauf wieder.

Dieser Lauftyp steht allein: Eine Warteschlangenroute hat genau einen Auslöser – ein weiterer zeitgesteuerter oder ein Ereignisauslöser daneben ist ausgeschlossen.

6. Aktivieren und freigeben​

  1. Prüfen und aktivieren Sie den Konfigurationsstand – siehe Prüfen und aktivieren.
  2. Wechseln Sie nach Ausführung und legen Sie den Schalter in der Spalte Automatik dieser Route um. Erst dann holt der Zeitplan ab.

Wenn die Quittung ausbleibt​

Die Warteschlange gibt immer die älteste noch nicht quittierte Nachricht heraus. Eine unquittierte Nachricht blockiert damit alles, was hinter ihr liegt – deshalb hält Xchange bei einer fehlgeschlagenen Quittung an.

Was passiertWas Xchange tut
Die Quittung scheitert vorübergehend – das Quellsystem ist gerade unerreichbarDer Lauf endet an dieser Stelle. Der nächste Lauf holt dieselbe Nachricht erneut, erkennt sie an der Nachrichtenkennung wieder und quittiert sie nach. Das geschieht von selbst.
Die Quittung scheitert dauerhaft – der Endpunkt ist falsch, weist die Bestätigung ab oder enthält einen Platzhalter, für den die Nachricht keine Kennung mitbringtXchange sperrt die Automatik der Route, sofern sie eingeschaltet ist, und der Lauf endet Fehlgeschlagen mit dem Grund „Quellsystem hat die Quittierung abgelehnt“. Die Vorgänge behalten ihren Status – verarbeitet sind sie; zurück bleibt die Nachricht in der Warteschlange.

Die Sperre erkennen Sie auf der Ausführung: Die Route steht auf Pausiert (Fehler), und ein Hinweisstreifen meldet „Die Quittierung der abgeholten Nachrichten ist dauerhaft fehlgeschlagen – die Automatik ist gesperrt.“ Prüfen Sie dann den Quittierungsendpunkt und die Quittierungszeilen, und schalten Sie die Automatik anschließend wieder ein. Oder starten Sie die Route mit Lauf starten von Hand: Nimmt das Quellsystem dabei eine Quittung an, hebt Xchange die Sperre selbst auf. Bis dahin bleibt sie – sie verhindert, dass dieselbe Nachricht stundenlang im Kreis läuft.

Wie es weitergeht​

Was aus einer angekommenen und bestätigten Nachricht wird, entscheidet die Route: Im Beispiel gibt „Statusmeldungen Kessler“ sie an eine von vier Zielrouten weiter, je nach Status. Das ist eine eigene Aufgabe – siehe Eingehende Nachrichten an die zuständige Route geben.

Siehe auch​