Nachrichten per REST neu starten

Die REST-Endpunkte zum Neustarten von Nachrichten sind unabhängig von der Konfiguration der Clearing Codes dokumentiert. Für die Konfiguration der verwendeten Clearing Codes siehe Clearing Codes.

In den folgenden Beispielen steht B2B_URL für die Basis-URL der B2B einschließlich Kontextpfad, zum Beispiel http://b2b.example.com/b2bbp-engine/api.

Für das Neustarten von Nachrichten stehen vier aktuelle REST-Endpunkte zur Verfügung:

Authentifizierung und Berechtigungen

Für OAuth2 beziehungsweise die rollenbasierte Authentifizierung muss das Access Token die Rolle B2B-MessageMonitor-Write enthalten. Diese Rolle wird von allen vier Endpunkten verlangt.

Bei BASIC Authentication prüft der B2B-Container zuerst die Rolle b2bbp.

Für die beiden Filter-Endpunkte restart-all und clear-all-items werden die Nachrichten mit dem Benutzerkontext gesucht. In einer klassischen B2B-Instanz muss der BASIC-Benutzer deshalb mindestens ein Rollenattribut mit einem Wert Systems=... besitzen. Bei aktivierter Mandantenfilterung bestimmt dieses Attribut, welche Systeme sichtbar sind. Ohne ein solches Attribut werden keine Nachrichten als Treffer geliefert. Die Einrichtung ist in der Dokumentation zur Mandantenfilterung beschrieben.

Ein BASIC-Benutzer mit Zugriff auf alle Systeme kann beispielsweise so eingerichtet werden. Der Account restart-user in B2BBP_ADM_ACCOUNT wird dabei vorausgesetzt:

INSERT INTO B2BBP_ADM_ROLE_ATTRIBUTE (roleAttributeId, roleAttributeValue)
VALUES ('AllowedSystemAll', 'Systems=all');

INSERT INTO B2BBP_ADM_ROLE (roleId, roleAttributeId, description)
VALUES ('allow-all-systems', 'AllowedSystemAll', 'Allow all systems');

-- Erforderlich für die Container-Autorisierung von BASIC Authentication.
INSERT INTO B2BBP_ADM_USER (userId, roleId, description)
VALUES ('restart-user', 'b2bbp', 'BASIC Authentication');

-- Erforderlich für die Filterung auf alle Systeme.
INSERT INTO B2BBP_ADM_USER (userId, roleId, description)
VALUES ('restart-user', 'allow-all-systems', 'Allow all systems');

AllowedSystemAll ist eine empfohlene, aber nicht technisch vorgeschriebene Bezeichnung des Rollenattributs. Entscheidend ist der Attributwert mit dem Präfix Systems=; all muss kleingeschrieben werden. Für eine Einschränkung auf einzelne Systeme wird statt Systems=all beispielsweise Systems=,99000000001,99000000002 verwendet.

Direkter Neustart: restart

Der Endpunkt POST $B2B_URL/b2b-messages/restart startet die angegebenen Nachrichten direkt neu. Der Request Body ist eine JSON-Liste von Message-IDs:

[
  "MESSAGE_ID_1",
  "MESSAGE_ID_2"
]

Neustart über einen Filter: restart-all

Der Endpunkt POST $B2B_URL/b2b-messages/restart-all ermittelt die Nachrichten über einen messageFilter und startet sie neu. Für diesen Endpunkt sind nur die Verarbeitungszustände ERR, MAN, SDJ und RUW neustartbar; mindestens einer dieser Zustände muss im Filter angegeben werden.

{
  "processStates": "ERR"
}

Eine oder mehrere Nachrichten: clearItem

Der Endpunkt POST $B2B_URL/clearings/clearItem setzt den Clearing Code für die angegebenen Nachrichten und startet sie unmittelbar neu. immediateRestart muss true sein: Nur dann wird die Nachricht neu gestartet. Das Verhalten von Services beim Neustart wird über die Konfiguration des verwendeten Clearing Codes gesteuert.

{
  "immediateRestart": true,
  "clearingItem": {
    "messageIds": [
      "MESSAGE_ID_1",
      "MESSAGE_ID_2"
    ],
    "code": "<CLEARING_CODE>",
    "shorttext": "<KURZTEXT>",
    "longtext": "<LANGTEXT>"
  }
}

Alle Nachrichten eines Filters: clear-all-items

Der Endpunkt POST $B2B_URL/clearings/clear-all-items ermittelt die Nachrichten über messageFilter, setzt für jede den Clearing Code und startet sie unmittelbar neu. Das folgende Beispiel beschränkt den Aufruf auf Nachrichten im Verarbeitungsstatus ERR.

{
  "immediateRestart": true,
  "clearingItemWithoutMessageIds": {
    "code": "<CLEARING_CODE>",
    "shorttext": "<KURZTEXT>",
    "longtext": "<LANGTEXT>"
  },
  "messageFilter": {
    "processStates": "ERR"
  }
}

Aufruf mit OAuth2

Ein Access Token kann für einen dazu berechtigten Keycloak-Client über den Client-Credentials-Flow bezogen werden:

ACCESS_TOKEN=$(curl --silent --show-error --fail \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode "grant_type=client_credentials" \
  "$TOKEN_URL" | jq --raw-output '.access_token')

Mit dem erhaltenen Token können beispielsweise alle vier Endpunkte aufgerufen werden:

curl --fail-with-body --request POST "$B2B_URL/b2b-messages/restart" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '["MESSAGE_ID_1"]'

curl --fail-with-body --request POST "$B2B_URL/b2b-messages/restart-all" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"processStates":"ERR"}'

curl --fail-with-body --request POST "$B2B_URL/clearings/clearItem" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "immediateRestart": true,
    "clearingItem": {
      "messageIds": ["MESSAGE_ID_1"],
      "code": "<CLEARING_CODE>",
      "shorttext": "<KURZTEXT>",
      "longtext": "<LANGTEXT>"
    }
  }'

curl --fail-with-body --request POST "$B2B_URL/clearings/clear-all-items" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "immediateRestart": true,
    "clearingItemWithoutMessageIds": {
      "code": "<CLEARING_CODE>",
      "shorttext": "<KURZTEXT>",
      "longtext": "<LANGTEXT>"
    },
    "messageFilter": {
      "processStates": "ERR"
    }
  }'

Aufruf mit Basic Auth

Der Benutzername und das Passwort werden mit --user übergeben. Die folgenden Beispiele zeigen dieselben vier Aufrufe mit BASIC Authentication:

curl --fail-with-body --user "$B2B_USER:$B2B_PASSWORD" \
  --request POST "$B2B_URL/b2b-messages/restart" \
  --header "Content-Type: application/json" \
  --data '["MESSAGE_ID_1"]'

curl --fail-with-body --user "$B2B_USER:$B2B_PASSWORD" \
  --request POST "$B2B_URL/b2b-messages/restart-all" \
  --header "Content-Type: application/json" \
  --data '{"processStates":"ERR"}'

curl --fail-with-body --user "$B2B_USER:$B2B_PASSWORD" \
  --request POST "$B2B_URL/clearings/clearItem" \
  --header "Content-Type: application/json" \
  --data '{
    "immediateRestart": true,
    "clearingItem": {
      "messageIds": ["MESSAGE_ID_1"],
      "code": "<CLEARING_CODE>",
      "shorttext": "<KURZTEXT>",
      "longtext": "<LANGTEXT>"
    }
  }'

curl --fail-with-body --user "$B2B_USER:$B2B_PASSWORD" \
  --request POST "$B2B_URL/clearings/clear-all-items" \
  --header "Content-Type: application/json" \
  --data '{
    "immediateRestart": true,
    "clearingItemWithoutMessageIds": {
      "code": "<CLEARING_CODE>",
      "shorttext": "<KURZTEXT>",
      "longtext": "<LANGTEXT>"
    },
    "messageFilter": {
      "processStates": "ERR"
    }
  }'

Das ältere GET-Servlet /b2bbp-engine/restartMessage ist kein Bestandteil dieser vier REST-Endpunkte. Es wird separat im RestartMessageServlet beschrieben.