Beschreibung zur Verwendung der B2B Marktkommunikation mit dem PKS

Allgemeines

Die B2B und das PKS Backend tauschen in der gemeinsamen Verwendung PARTIN Nachrichten im edi-json Format miteinander aus.

Dabei gibt es zwei Szenarien:

  • Inbound: Es wird eine PARTIN von einem Marktpartner an der B2B empfangen, dort validiert, mithilfe des edi-json.converter ins edi-json Format konvertiert und per REST ans PKS übergeben.
  • Outbound: Es wird/werden (aus der PKS-UI durch den Anwender getriggert) PARTIN Nachrichten im PKS im edi-json Format erstellt und an die B2B per REST übergeben, dort zu EDIFACTs konvertiert und an den jeweiligen Marktpartner versendet.

Das PKS Backend ist dabei Keycloak abgesichert, sodass die Kommunikation B2B -> PKS ebenfalls per Keycloak OAuth2 abgesichert stattfinden muss. Die verarbeitenden B2B Knoten (mit Queue Service), die diesen REST Aufruf ausführen, sind häufig noch nicht Keycloak abgesichert, sodass diese eine entsprechende Keycloak Konfiguration benötigen.

Für beide REST Endpunkte zum Empfang der PARTIN edi-json (an der B2B und PKS) werden entsprechende Rollenberechtigungen der Services benötigt.

B2B Customizing für PARTIN Nachrichten

Mit Schnell-Customizing Import

B2B Schnell-Customzing ( interner Link/kann von uns bereitgestellt werden), welches gezippt in die B2B über den Customizing-Upload hochgeladen werden kann. Achtung: Es muss dieses bereits vor dem Hochladen geprüft werden, ob dieses in einer kunden-individuellen B2B einfach hochgeladen werden kann (passen die Action bzw. Service IDs?).

Danach müssen noch manuell folgende Schritte durchgeführt werden:

  • Anpassung der Extensions zum Routing der Nachrichten in die Channel IN_PKS bzw. OUT_PKS. Dies sind im Standardfall die Extensions EXT_CHANNEL_DIST, GENERIC_EDICONDITION_DISTRIBUTION und GENERIC_EDICONDITION_DISTRIBUTION_OUT.
  • Beim Routing über die EdiConditionDistributorAllPresentations sollte eine Erweiterung der GENERIC_EDICONDITION_DISTRIBUTION(_OUT) um die folgenden Einträge genügen:
"IN_PKS" <== $messagecontext.FORMAT.type == "PARTIN";
Bzw.
"OUT_PKS" <== $messagecontext.FORMAT.type == "PARTIN";
  • Anpassung der URLs aus dem Customizing (URL Service Eigenschaften der drei RestClientServices “EdiJson2EdifactMapper”, “ Edifact2EdiJsonMapper” und “PKS_IN”) zur Verbindung mit dem ausgerollten PKS Backend bzw. edi-json.converter.

Manuelles Customizing

Falls die B2B-Konfiguration manuell durchgeführt werden soll, dann sind grundsätzlich die folgenden Schritte in der Channel-Verarbeitung zu beachten:

  • Inbound:
    • (Volltextindizierung standardmäßig über Channel-Distribution)
    • Validierung
    • CONTRL Erzeugung/Versand
    • APERAK Erzeugung/Versand
    • EDIFACT nach edi-json Mapping (via RestClientService)
    • Übergabe ans PKS (ebenfalls via RestClientService)
  • Outbound:
    • edi-json nach EDIFACT Mapping (via RestClientService)
    • Volltextindizierung
    • Optional und nur für Testsysteme empfohlen: Ausgehende Validierung
    • Nachrichtenversand an Markt

Genauer Einstellungen können am besten aus dem obigen exportierten Schnell-Customizing entnommen werden.

PARTIN Übergabe von B2B Basic-Auth an PKS

Einrichtung

Ist ein B2B Knoten zur Nachrichtenverarbeitung (Knoten mit zugeordnetem Queue-Service) ein per basic-auth abgesicherter Knoten, so benötigt dieser zur Kommunikation mit dem Keyclaok-abgesicherten PKS Backend eine Konfiguration zur OAuth2 Kommunikation.

Der RestClientService läd mit der Konfiguration AUTH_METHOD=OAUTH2_KEYCLOAK dazu eine authorisierte keycloak.json aus seinem tomcat/lib Verzeichnis.

Wir empfehlen hierzu die bereits vorhandene keycloak.json des Keycloak Clients B2B Backends in dieses Verzeichnis zu verwenden. Für den Fall, dass das bestehende B2B Backend nicht mit dem Access Type “confidential” läuft (und damit kein Credential in´der keycloak.json zur Authentifizierung), kann dafür einfach ein neuer B2B Backend Client in der Keycloak Administration analog mit dem Access Type “confidential” angelegt und verwendet werden. Die keycloak.json kann unter Clients -> “B2B Tomcat Backend” -> Installation per JSON heruntergeladen werden. Achtung: “ssl-required” muss ggf. auf “none” gesetzt werden!

Zudem muss der Client im Keycloak die Konfiguration “Service Accounts Enabled” aktiviert haben haben und der entsprechenden “Serivce Account Role” zugeordnet sein, siehe auch Einrichtung Keycloak.

Nachdem die keycloak.json in den B2B Tomcats hinterlegt ist, müssen diese einmal neu gestartet werden, damit diese verwendet geladen wird.

Vergleiche auch mit Doku zur Einrichtung der OAuth2 abgesicherten B2B -> FSS Kommunikation.

Hinweise zur Einrichtung

Erhält man in der B2B bei der PARTIN Nachrichten Übergabe ans PKS den Fehlercode 302 (Found), so stimmt die PKS URL Konfiguration, jedoch gelingt die Authorisierung der REST Anfrage über die keycloak.json noch nicht.

Erhält man in der B2B bei der PARTIN Nachrichten Übergabe ans PKS den Fehlercode 406 (Not Acceptable), so hat das PKS den POST Request-Body nicht als PARTIN edi-json erkannt. Dies kann zum Beispiel durch ein Nachrichten-Neustart ohne Services in der B2B verursacht worden sein, wodurch das EDIFACT -> edi-json Mapping am Converter nicht erneut (erfolgreich) durchgeführt wurde und die B2B somit versucht hat eine EDIFACT ans PKS zu versenden.

Übergabe erstellter PARTIN an die B2B

Hierzu muss nur (mindestens) die B2B URL in der application.properties des PKS Backends (in der Docker Installation als Umgebungsvariable in der .env Datei) angegeben werden.

Achtung: Ab dem Release 2022-09-xx (siehe BTOB-8284) empfehlen wir die Kommunikation PKS -> B2B per Keycloak statt BasicAuth abzusichern. Die Verbindung wird dabei automatisch per Keycloak abgesichert, wenn kein pks.b2b.basicUserName und pks.b2b.basicPassowrd in der application.properties des PKS Backends und stattdessen die URL der Keycloak abgesicherten B2B angegeben sind. Für eine BasicAuth Kommunikation muss neben der BasicAuth B2B URL auch noch ein B2B Datenbank User/Password angegeben werden.

Keycloak Rollenberechtigungen

Die PARTIN Übergabe zwischen B2B und PKS funktioniert nur dann erfolgreich, wenn der anfragende Client auch die entsprechende Rollenberechtigung für die Verwendung des entsprechenden REST Endpunkts besitzt. Diese Konfiguration ist in der Keycloak Einrichtung beschrieben.

Anbindung edi-json.converter

Das EDIFACT <-> edi-json Mapping wird durch edi-json.converter Service durchgeführt. Dieser besitzt dazu REST Endpunkte, die die B2B über den RestClientService aufruft. Näheres zu edi-json.converter und seiner Installation findet sich hier.

View Me   Edit Me