AEP.API Customizing in der B2B | Produktdokumentation

AEP.API B2B Customizing

Allgemeine Konfiguration

Im Folgenden werden die Schritte zur Konfiguration der B2B beschrieben, sodass diese mit AEP.API verbunden ist und API-Anfragen austauschen kann.

Customizing Export

Für eine Schnell-Konfiguration kann das unter folgendem internen Link das Customizing als Zip-Datei heruntergeladen werden. Gehen Sie hierfür gerne auf unseren Support zu. Diese kann in der Admin-UI unter Administration -> Global Properties -> Customizing Import hochgeladen werden.

Important: Dabei sollte aber vor dem Import darauf geachtet werden, dass die Action IDs und Channel-Namen noch nicht vergeben sind. Änderungen an bereits vorhandenen Extensions sollten manuell durchgeführt werden!

Ausgehende Verarbeitung von API-Anfragen in der B2B

Fachliche Backend-Systeme können API-Anfrage Informationen in die B2B senden, sodass diese sie an den api-webservice-client zum Versand in den Markt übergibt. Dazu können (abhängig vom fachlichen Backend-System, dass diese Informationen bereitstellt) alle bestehenden Eingangsservices und Schnittstellen der B2B verwendet werden.

In der B2B-Verarbeitung müssen dann die folgenden Schritte durchgeführt/konfiguriert werden, um die API-Anfrage Informationen erfolgreich ans AEP.API System zu übermitteln:

Konfiguration der Formaterkennung (abhängig vom Format in der das Backend die API-Anfrage Informationen bereitstellt).
Routing ausgehender API-Anfrage Informationen in eigene Channel-Verarbeitung z.B. den Channel OUT_API-REQUEST.
Mapping der Daten in die Json-Zielstruktur der API-Anfrage Informationen und hinzufügen der B2B MessageId.
Übergabe der Daten an die RabbitMQ Queue des api-webservice-clients zur Weiterverarbeitung.

Auf die Konfigurationen der einzelnen Schritte wird im Folgenden genauer eingegangen.

Konfiguration der Formaterkennung

Die Konfiguration der Formaterkennung hängt von Eingangsformat der API-Anfrage Informationen ab.

Es wird empfohlen wird, dass die Daten bereits im Json-Zielformat der B2B übermittelt werden. Hierzu kann die generische B2B-Formaterkennung für Json Nachrichten entsprechend konfiguriert werden.

Routing in ausgehenden Channel

Die Ermittlung des Ziel-Channels zur Verarbeitung in der B2B von ausgehenden API-Anfragen geschieht meist über die EdiConditionDistributorAllPresentationsOutbound ChannelDistribution. Dies kann hierbei durch den folgenden Eintrag in der GENERIC_EDICONDITION_DISTRIBUTION_OUT Extension anhand des spezfischen Format-Typs (definiert in der Format-Erkennung) der API-Anfrage Nachricht umgesetzt werden:

"OUT_API-REQUEST" <== $messagecontext.FORMAT.specificPresentation == "OutboundApiRequest";

Mapping der API-Anfrage Information in die Ziel-Struktur

Transformation der Daten in die Json-Zielstruktur mithilfe aller Möglichkeiten in der B2B wie z.B. Mapping Actions, Transformationen, dynamischen Funktionen etc. Das Hinzufügen der B2B MessageId in den übermittelten API-Anfrage Informationen kann durch folgende dynamische Funktion umgesetzt werden (unter der Annahme, dass die API-Anfrage Informationen bereits in der Json-Zielstruktur im CURRENT_PAYLOAD vorliegen):

{"b2bMessageId":"${template(&(this.B3P_OBJ_MESSAGE.messageId))}","isResend":${if(${equals(${var(MESSAGE_IS_RESTARTED)},true)},true,false)},${stringsplit(${var(CURRENT_PAYLOAD)},^\s*\{,1)}

Übergabe an RabbitMQ Queue

Hierzu wird empfohlen das B2B Outbox Feature mit der OutboxAction. zu verwenden. Dieses schreibt die API-Anfrage Informationen zunächst in eine eigene Datenbank Tabelle, von wo der B2B Message Service die Daten abholt und in einen RabbitMQ Exchange schreibt.

Voraussetzung für die Verwendung des Outbox Features ist, dass die B2B Datenbank Tabelle B2BBP_OUTBOX angelegt, der B2B Message Service installiert und für die Verwendung des Outbox Features konfiguriert ist, siehe dazu die Outbox Relay Dokumentation.

Zielformat der API-Anfrage Informationen zur Übergabe ans AEP.API

Damit der api-webservice-client die API-Anfrage Informationen verarbeiten kann, müssen diese im folgenden Json-Format in der OutboxAction in den RabbitMQ Exchange geschrieben werden, wie das folgende Beispiel zeigt:

{
  // Wird in der B2B zur Zuordnung der ausgehenden API-Anfrage Verarbeitungsdaten hinzugefügt
  "b2bMessageId": "7c7f1a81-8c7d-11ef-bd3c-0242ac120025",
  // Pfad des API-Endpunktes gemäß BDEW Spezifikation (Versions-Suffix wird nicht benötigt)
  "endpointPath": "/maloId/dataForMarketLocationNegative",
  // Header Felder des jeweiligen API-Webservice Endpunkts gemäß BDEW Spezifikation
  "headers": {
    "transactionId": "02f91fa5-c8c6-4ed6-8d87-8bdad8616ffa",
    "creationDateTime": "2023-08-01T12:30:00.1704Z"
  },
  // MPID des Marktpartners als Empfänger des API-Requests
  "partnerMpId": "9979046000004",
  // Eigene Mandanten MPID als Absender/Signierer des API-Requests
  "tenantMpId": "9907647000008",
  // Json-Body des jeweiligen API-Webservice Endpunkts gemäß BDEW Spezifikation
  "body": "{ \"decisionTree\": \"E_0594\", \"responseCode\": \"A10\", \"reason\": \"Ich bin ein Freitext.\", \"networkOperator\": 9900987654321}",
  // Request Parameter Felder des jeweiligen API-Webservice Endpunkts gemäß BDEW Spezifikation
  "parameters": {
    "referenceId": "111d4fae-7dec-11d0-a765-00a0c91e6bf6"
  },
  // API-Kennung des API-Endpunktes (gemäß Anwendungsübersicht der Prüfidentifikatoren)
  "apiId": "API00003"
}

Das Beispiel beschreibt eine API-Anfrage der API-Webdienste zur Ermittlung der MaLo-ID der Marktlokation (mit apiId API00003) des Endpunkts “Negative Rückmeldung auf die Anfrage der MaLo-ID der Marktlokation”. In den API-Anfrage Informationen müssen abhängig vom konkreten API-Endpunkt der Anfrage alle erforderlichen (und optionalen) Request Headers, Request Parameter und Request Body gefüllt werden, damit dieser den API-Request erfolgreich bestätigt. Denn genau diese werden an den API-Webservice des Marktpartners entsprechend übermittelt (und um Protokoll-anhängige Request Header zur Signatur erweitert).

Eine exakte Schnittstellen Definition der AMQP Schnittstellen des AEP.API Systems finden Sie hier.

Empfang der Verarbeitungsdaten versendeter API-Anfragen in der B2B

Hierzu übergibt der AEP.API Webservice Client die Verarbeitungsdaten in einen AMQP Exchange. Der B2B-Message-Service konsumiert diese Daten und aktualisiert die B2B Nachricht entsprechend, siehe dazu Konfiguration des b2b-message-service.

Verarbeitung empfangener API-Anfragen in der B2B

Das AEP.API System (genauer der api-webservice-server) stellt API-Webservice Endpunkte bereit, welche Marktpartner API-Clients zur Übermittlung von API-Anfragen aufrufen können.

Nachdem die API-Anfragen gemäß Regulatorik vom api-webservice-server verarbeitet und beantwortet wurden wird die API-Anfrage samt (Transport- und Verarbeitungsdaten) über eine AMQP Queue an den b2b-message-service übermittelt. Dieser erzeugt eine neue B2B Nachricht, speichert an dieser alle Nachrichten und gibt die API-Anfrage Inforamtionen in die B2B Queue zur B2B Workflow Verarbeitung.

In der B2B-Verarbeitung müssen dann die folgenden Schritte durchgeführt/konfiguriert werden, um die eingehende API-Anfrage Informationen erfolgreich zu verarbeiten:

Konfiguration der Json-Formaterkennung für eingehende API-Requests.
Routing eingehender API-Anfrage Informationen in eigene Channel-Verarbeitung z.B. den Channel IN_API-REQUEST.
Konfiguration der Ziel-Channel zur Verarbeitung von (positiv und negativ) bestätigten API-Anfragen (für die Übergabe an das Backend zur fachlichen Verarbeitung)

Auf die Konfigurationen der einzelnen Schritte wird im Folgenden genauer eingegangen.

Konfiguration der Formaterkennung

Das AEP.API System übergibt der B2B API-Request Inforamtionen als BASE_MESSAGE in json-Format auf welcher die Formaterkennung angewendet wird. Entsprechend kann hierzu die generische B2B-Formaterkennung für Json Nachrichten konfiguriert werden.

Routing in den eingehenden Channel

Konfiguration der EdiConditionDistributorAllPresentations ChannelDistribution

Die Ermittlung des Ziel-Channels zur Verarbeitung in der B2B von ausgehenden API-Anfragen geschieht meist über die EdiConditionDistributorAllPresentations ChannelDistribution. Dies kann hierbei durch den folgenden Eintrag in der GENERIC_EDICONDITION_DISTRIBUTION Extension anhand des spezifischen Format-Typs ( definiert in der Format-Erkennung) der API-Anfrage Nachricht umgesetzt werden:

"IN_API-REQUEST" <== $messagecontext.FORMAT.specificPresentation == "InboundApiRequest";

Damit wird der Ziel-Channel IN_API-REQUEST für die Verarbeitung von bestätigten API-Anfragen definiert.

Falls im Einsatz: Deaktivierung der WrongFormatFilterChannelDistribution für API-Requests

Diese Konfiguration wird nur benötigt, falls Sie die WrongFormatFilterChannelDistribution bereits einsetzen.

Um zu verhindern, dass eingehende API-Anfragen von der Channel-Distribution abgelehnt werden, muss ein Eintrag in der Extension EXT_CHANNEL_DIST hinzugefügt werden:

org.b2bbp.channels.extension.WrongFormatFilterChannelDistribution.contextParserCondition=${not(${equals(${template(&!(this.FORMAT.specificPresentation))},InboundApiRequest)})}

Falls Sie die B2B auch bereits für AS4 Fahrplan Nachrichten nutzen, kann die WrongFormatFilterChannelDistribution so für beide Nachrichtenarten gemeinsam deaktiviert werden:

org.b2bbp.channels.extension.WrongFormatFilterChannelDistribution.contextParserCondition=${not(${anyof(${equals(${template(&!(this.FORMAT.attributes.formatClass))},Schedule)},${equals(${template(&!(this.FORMAT.specificPresentation))},InboundApiRequest)})})}

Konfiguration der Channel-Verarbeitung

Die Konfiguration des Ziel-Channels hängt von der Anbindung des Fach-Backends ab, welches ggf. ein Mapping API-Anfrage Daten benötigt und die Übergabe dieser an die Schnittstelle des Fach-Backends. Hierzu stehen i.A. alle Möglichkeiten der B2B Konfiguration zur Verfügung.

Nicht positiv bestätigte API-Anfragen von Marktpartnern (z.B. Fehler in der Signatur oder Validierung) werden vom b2b-message-service bereits direkt in einen konfigurierbaren Fehler-Channel ausgesteuert. Dieser Channel (Default: IN_API-REQUEST_ERROR) sollte entsprechend konfiguriert werden, um eine Fehlerbehandlung nach Wunsch auszuführen.

Archivierung

API-Request Nachrichten, die per AEP.API verschickt oder empfangen wurden, können mit allen notwendigen Informationen ausgehend von der B2B archiviert werden. Hierzu sind vermutlich Anpassungen an einer bestehenden Archivierung von EDIFACT Nachrichten notwendig, damit diese auch für API-Request Nachrichten verwendet werden kann.

View Me Edit Me