Der Edifact und EdiJson Konvertierungsservice

Grund für die Entwicklung

Da das Mapping von Edifact auf JSON und umgekehrt eine Dependendency auf den EdiGenerator benötigt, die in der B2B über den Validation Content geliefert wird und wir dort somit keine Kontrolle über die vorliegende Version haben und es so zu Versionskonflikten kommen kann. Haben wir uns entschieden hier einen Microservice zu implementieren, der die Abhängigkeit selbstverwaltet ausserhalb des B2B Kontextes nutzen kann.

Aufbau

Der Microservice ist eine eigenständige SpringBoot Applikation, die einen Post Endpunkt pro Konvertierungrichtung anbietet. Streng genommen wäre hier die GET Methode angebrachter, diese übermittelt ihre Daten aber nicht im Request Body, der bei einer Größe von potentiell mehreren Megabytes die bessere Option darstellt. Alternativ wäre eine Datenübermittlung im Rahmen eines File Uploads. Dieser Weg wurde aber hier nicht gewählt.

Datenverarbeitung

Die übermittelten Daten werden synchron konvertiert und die Resultate im Responsebody übertragen.

Konfiguration des Microservice

Der Microservice wird über die Datei application.yaml konfiguriert. Relevante Settings dabei

• server.port - Der Port unter den der Service erreichbar sein soll
• andere aus SpringBoot bekannte parameter wie logging etc.

Versionsinfo

Die aktuelle Version des Microservice kann mit Hilfe des Endpunkts /actuator/info abgerufen werden.

Artefakt

Der edi-json.converter wird im Jenkins gebaut und ist NLI intern im Nexus verfügbar.

Release

Ein EdiJson-Converter Release ist meistens unabhängig von einem B2B Release, d.h. weder erfolgt er geplant zeitgleich mit einem B2B Release, noch müssen B2B und EdiJson-Converter Versionen aufeinander abgestimmt werden.

Release Notes

Die Release Notes zum EdiJson-Converter finden sich im hier.

Verwendung zusammen mit der B2B

Schnell-Customizing

Es folgt ein minimales Customizing. Dieses stellt die Edi-Json Grundfunktionalitäten zur Verfügung, die in den folgenden Abschnitten genauer erläutert werden.

globalProperties:
  EDIJSON_CONVERTER_URL: "http://edi-json-converter:8080"

services:
  "ProcessTrigger":
    name: EdiJsonMeta an ProcessTrigger
    class: com.nextlevel.services.outbound.http.ProcessTriggerService
    type: REST
    direction: OUT
    properties:
      URL: "http://sxp-processtrigger-sim:8080"
      MONITOR_OUTPUT: true
  "EdiJsonInbound":
    name: EdiJson Receiver
    type: REST
    channel: OUT_SEP
    direction: IN
      
actions:
  "SXP-ProcessTrigger #730":
    id: 730
    class: org.b2bbp.runtime.actions.internal.SetPropertyAction
    description: 'Ruft den Service auf, der das EdiJson-Meta an den SXP-ProcessTrigger übergibt.'
    properties:
      B3P_USED_SERVICE_ID:
        value: "ProcessTrigger"
        techMon: true
  "EdiJson-2-Edifact #731":
    id: 731
    class: com.nextlevel.edifactjson.mapping.EdiJson2EdifactMappingAction
    description: 'Action, die das EdiJson in eine Edifact konvertiert.'
    properties:
      URL:
        value: "http://edi-json-converter:8080"
        techMon: true
  
channels:
  -
    id: IN_SXP
    direction: IN
    actions:
      "ValidatorAction": true
      "Contrl erzeugen": true
      "Aperak erzeugen": true
      "Übergabe an SXP-ProcessTrigger #730": true
      "ErrorMailHandler": false
  -
    id: OUT_SXP
    direction: OUT
    actions:
      "EdiJson-2-Edifact #731": true
      "IndexingService Volltext": true
      "Msg versenden (Mail/AS2)": true
      "ErrorMailHandler": false

Einleitung

Die folgenden zwei Schaubilder zeigen schematisch wie der edi-json.converter Microservice zusammen mit der B2B und einem angeschlossenen Backend (z.B. der SXP Process Engine) konfiguriert werden kann, welches über EdiJsons (mit der B2B) kommuniziert. Dabei sind die folgenden zwei Kommunikationsrichtungen zu beachten:

Markt -> Backend (Edifact -> JSON)

Innerhalb der B2B findet zunächst eine normale Nachrichtenverarbeitung statt. Hier findet keine Push-Kommunikation statt. Es wird nur ein GET Endpoint angeboten, der es erlaubt über die MessageId einer verabeiteten Nachricht diese im JSON-Format abzurufen.

Eine Push-Kommunikation kann jedoch separat über den ProcessTrigger realisiert werden: Am Ende der Verarbeitung wird der ProcessTriggerService im Channel aufgerufen, welches ein MetaDaten-JSON ans Backend-System sendet. Dieses enthält u.a. die MessageId.

Nach Abschluss der Verarbeitung kann die JSON-Representation der verarbeiteten Edifact über den folgenden B2B REST Endpoint (tatsächliche Adresse über Swagger einsehbar) erhalten werden. Ist die verarbeitete Nachricht keine Edifact, sondern ein EdiJson, so wird dieses direkt zurückgegeben.

GET [b2b]/api/edifactjson/v1/edifact/{messageid}

Hierfür baut die B2B eine Verbindung zum edi-json.converter Microservice auf. Seine Base URL muss dazu in der folgenden GlobalProperty hinterlegt sein.

EDIJSON_CONVERTER_URL = http://<converter_server>:<converter_port>

Der HATEOAS-Wrapper der B2B bei der JSON Convertierung hat die folgende Struktur:

{
  "data": "edi-json",
  "links": []
}

Es können nur nicht archivierte Nachrichten, bei denen das Attribut B3P_BASE_MESSAGE eine Edifact Nachricht enthält abgerufen werden.

Backend -> Markt (JSON -> Edifact)

Die Edifacts werden im definierten JSON Format (gemäß edi-json-model, inklusive Hateoas-Wrapper) mit UTF-8 Encoding per POST an den Endpunkt (tatsächliche Adresse über Swagger einsehbar) gesendet.

POST [b2b]/api/edifactjson/v1/queue/{priority}

Wird keine Priorität angegeben nimmt die B2B als default-Wert LOW an. Dies entspricht dem üblichen Default-Wert. In der B2B muss dazu ein passiver Pseudo-Inbound-Service angelegt werden, der die Nachrichtenverabeitung mit einem bestimmten Channel in Queue leitet.

Die ID des Services kann abweichend vom Defaultwert in der folgenden GlobalProperty definiert werden, welche nach Neustart aktiv wird:

INBOUND_EDIJSON_SERVICE = My_Json_Inbound_Service (Default: EdiJsonInbound)

Noch vor der Queue durchläuft das JSON die Formaterkennung, welche aus den unterstützten JSON Formate in der HATEOAS-Wrapper Struktur die entsprechenden Daten auslesen kann. (Im Formatobjekt ist das Attribut UtilRef nicht befüllt.) Nachdem die Nachricht in der Queue abgelegt wurde wird der Request beendet und die Id der neuen Nachricht im ResponseBody zurück geschickt. Die Verarbeitung der Nachricht hat zu diesem Zeitpunkt noch nicht begonnen. Die zurückgegebene ID hat die folgende Form:

b2bMsgId_b2bQueueId

Die Konvertierung findet hier innerhalb eines Outbound-Channels statt, in welchem die Action EdiJson2EdifactMappingAction konfiguriert werden muss.