AS4 B2B Customizing Fahrplan

Diese Seite beschreibt das B2B-Customizing eines AEP-AS4-Fahrplan-Systems. Die Dokumentation gliedert sich in folgende Abschnitte:

  • Vorbedingungen
  • Outbound
  • Inbound
  • Frontend

(Tip für den Support: Link zum Fahrplan-Standard-Customizing)

Architektur: as4_c_schedule_architecture.png

(Tip für den Support: Fahrplan-Architektur)

Vorbedingungen

Folgende Systemlandschaft wird vorausgesetzt:

Der B2B-Message-Service sollte bereits per AMQP mit dem Message-Broker verbunden sein, um Nachrichten mit dem AEP-AS4-System austauschen zu können.

Ein grundlegendes B2B-Customizing sollte bereits vorhanden sein, insbesondere muss der Queue-Service laufen.

Im AEP-AS4-System müssen die benötigten AS4-Beziehungen aktiviert sein. Im Kontext von AS4 werden Beziehungen immer über Paare von MPIDs repräsentiert.

Weiterhin müssen die zugehörigen Zertifikate für Sender & Empfänger MPIDs sowie deren Aussteller-Zertifikate im FSS gepflegt sein.

Outbound

Um eine Fahrplan-Nachricht zu versenden, müssen verschiedene Anpassungen vorgenommen werden. Folgende Themen werden behandelt:

  • B2B-Inbound-Service & ChannelDistribution
  • Format Recognition
  • EIC-MPID-Mapping
  • Outbound-Channel
  • Outbound AMQP Routing
  • Outbound-Priorisierung

as4_c_schedule_outbound.png

as4_c_schedule_outbound_details.png

(Tip für den Support: Outbound-Architektur)

B2B-Inbound-Service & Channel Distribution

Der Outbound-Fahrplan-Channel kann z.B. angesteuert werden, indem er direkt am B2B-Inbound-Service konfiguriert wird.

Der B2B-Eingangsservice ist abhängig von der Schnittstelle des Backends zu wählen. Arvato kann Sie bei der Wahl einer geeigneten Backend-Schnittstelle unterstützen. Ein Beispiel wäre die Übertragung einer Fahrplan-XML via FTP.

Format Recognition

Die Fahrplan-Format-Recognition erfolgt über die Extension DIALECT.

Es müssen Anpassungen in der DIALECT Extension vorgenommen werden. Kontaktieren Sie hierfür den Support. (Hinweis an den Support: die DIALECT findet sich hier).

EIC-MPID-Mapping

Des Weiteren müssen in der Extension EIC_MPID_MAPPING die EIC-Codes auf die passende MPID gemappt werden. Dies wird im Outbound-Fahrplan-Channel verwendet, um die Werte Partner, Partner-Code und System, System-Code zu ermitteln. Diese Werte werden benötigt, um die AS4-Adresse und die Zertifikate zu ermitteln. Gehen Sie dabei wie im folgenden Beispiel vor:

11X0-0000-0544-U=<ILN>
10XDE-VE-TRANSMK=<ILN>
11XRWEINTRADAY-O=<ILN>

Outbound-Channel

Im Standard nutzen wir den neuen Channel OUT_SCHEDULE.

Die nachfolgenden Actions müssen in derselben Reihenfolge in einem Channel aktiviert sein. Zusammen erstellen und verschicken sie eine Nachricht an das AS4-System. Diese Nachricht enthält alle Informationen, die das AEP-AS4-System benötigt, um die Fahrplan-Nachricht per AS4 zu verschicken.

Actions:

  • XmlXsdValidatorAction
  • AS4-Protocol-Action
  • SetMessageAction
  • SetFormatAction
  • As4 Outbound Payload Json Creator Action
  • Outbox Action
  • ErrorMailHandler-Action

Ggf. erfordert Ihr System weitere Actions, z.B. eine IndexAction für die Volltextindizierung. Vergleichen Sie hierfür ihre anderen Outbound-Channels.

Für die Volltextindizierung der Fahrplannachrichten kann nicht die gleiche Action verwendet werden, wie für die Edifact-Volltextindizierung. Es wird eine eigene Action mit folgender Eigenschaft benötigt:

Aktionseigenschaft Wert Beschreibung Kontext Überschreiben
TARGET_INDEX_ENTRY B3P_BASE_MESSAGE Zu indizierendes Attribut Ja

XML Validierung durch XSD-Schemata

Die Action validiert XML-Input anhand eines XSD-Schemas. Sie prüft die XML-Daten auf Konformität mit dem Schema, protokolliert Fehler oder Warnungen und bietet erweiterte Optionen wie Caching und Feature-Konfiguration.

Aktionseigenschaft Wert Kontext überschreiben Optionen
ACTION_DECORATORS EvaluateAfterActionProperties;ExceptionCatcher Nein  
B3P_EVALUATE_WHEN_ERROR true Ja  
B3P_RESULT_KEY VALIDATION_RESULT Nein  
RESULT_ERROR !@${template(&(this.VALIDATION_RESULT))} Nein technisch
SCHEMA_EXTENSION_NAMES ${template(&(this.FORMAT.specificPresentation))}_XSD Nein technisch
SOURCE_FIELD CURRENT_PAYLOAD Nein  
VALIDATION_ERROR !@${anyof(${var(VALIDATION_ERROR_OCCURED)},${var(VALIDATION_FATAL_ERROR_OCCURED)})} Ja technisch
VALIDATION_FATAL_ERROR !@${template(&(this.VALIDATION_FATAL_ERROR_OCCURED))} Ja technisch
VALIDATION_LEVEL ERROR Nein  
VALIDATION_LOG_LEVEL WARN Nein  
VALIDATION_WARN !@${template(&(this.VALIDATION_WARN_OCCURED))} Ja technisch

AS4 Protocol Action

Konfigurieren Sie eine SetPropertyAction, um in der Protokoll-Spalte im Nachrichtenmonitor AS4 anzuzeigen:

Konfigurieren Sie an der Action folgende Property:

  • Key: AS4_ID
  • Value: ${template(not yet available)}

Set Message Action

Das Message-Objekt wird für die Anzeige im Nachrichtenmonitor genutzt, z.B. zur Anzeige der MPIDs. Es wird üblicherweise während der Formaterkennung befüllt. Da Fahrplan-Nachrichten jedoch nicht alle Informationen enthalten, müssen die fehlenden Werte nachträglich ergänzt werden.

Die Set-Message-Action wird benötigt, um Werte des Message-Objekts in der B2B zu überschreiben. Hierfür werden die Werte aus der Extension EIC-MPID-Mapping auf die Werte Partner und System auf die verarbeitende Nachricht gemappt.

Beachten Sie die bestehende Dokumentation zur SetMessageAction und richten sie die Action wie nachfolgend beschrieben ein:

Klasse: org.b2bbp.runtime.actions.internal.SetMessageAction

Der Name der Eingenschaft kann beliebig gewählt werden. Wenn bei der Anlage der Eigenschaft die Option “fachlich” oder “technisch” eingeschaltet ist, wird diese Eigenschaft bei der Nachricht als fachliches Beleg bzw. als technisches Detail angezeigt.

Aktionseigenschaft Wert Beschreibung
PARTNER ${loadExtensionProperty(EIC_MPID_MAPPING,${template(&(this.FORMAT.attributes.receiverEic))},true)} Partner von eic-mpid extension
SYSTEM ${loadExtensionProperty(EIC_MPID_MAPPING,${template(&(this.FORMAT.attributes.senderEic))},true)} SYSTEM von eic-mpid extension

Set Format Mpid

Bei der Übergabe der Nachricht ans AS4-System werden auch Werte aus dem Format-Objekt übermittelt. Das Format-Objekt wird üblicherweise während der Formaterkennung befüllt. Da Fahrplan-Nachrichten jedoch nicht alle Informationen enthalten, müssen die fehlenden Werte nachträglich ergänzt werden.

Die Set-Format-Action wird benötigt, um Werte des Format-Objekts in der B2B zu überschreiben, ähnlich wie die Set-Message-Action. Hierfür werden die Werte aus der Extension EIC-MPID-Mapping auf die Werte Partner, Partner-Code und System, System-Code gemappt.

Beachten Sie die bestehende Dokumentation zur SetFormatAction und richten sie die Action wie nachfolgend beschrieben ein:

Klasse: org.b2bbp.runtime.actions.internal.SetFormatAction

Der Name der Eingenschaft kann beliebig gewählt werden. Wenn bei der Anlage der Eigenschaft die Option “fachlich” oder “technisch” eingeschaltet ist, wird diese Eigenschaft bei der Nachricht als fachliches Beleg bzw. als technisches Detail angezeigt.

Aktionseigenschaft Wert Beschreibung
PARTNER ${loadExtensionProperty(EIC_MPID_MAPPING,${template(&(this.FORMAT.attributes.receiverEic))},true)} Partner von eic-mpid extension
PARTNER_CODE ${loadExtensionProperty(EIC_MPID_MAPPING,${template(&(this.FORMAT.attributes.receiverEic))},true)} Partnercode aus der EIC-MPID-Erweiterung.
SYSTEM ${loadExtensionProperty(EIC_MPID_MAPPING,${template(&(this.FORMAT.attributes.senderEic))},true)} SYSTEM von eic-mpid extension
SYSTEM_CODE ${loadExtensionProperty(EIC_MPID_MAPPING,${template(&(this.FORMAT.attributes.senderEic))},true)} SYSTEM code aus der EIC-MPID-Erweiterung.

As4 Outbound Payload Json Creator Action

Die Action erzeugt ein Json basierend auf der API des AS4 Outbound Market Message Service. Diese Nachricht ist im nächsten Schritt an das AS4-System zu übergeben.

Die Action befüllt die benötigten Werte unter anderem mithilfe des Format-Objekts und bringt sie in ein passendes Format. Das erzeugte Json wird unter dem Attribut, welches über die Property OUTPUT_ATTRIBUT_KEY konfiguriert wird, in der Datenbank gespeichert. Das Outbox-Relay lädt dieses Attribut und leitet es an den AS4 Outbound Market Message Service weiter.

Beachten Sie die bestehende Dokumentation zur As4OutboundPayloadJsonCreatorAction. Die Standard-Konfiguration ist für den Einsatz geeignet, es werden keine Properties benötigt.

Klasse: org.b2bbp.runtime.actions.internal.As4OutboundPayloadJsonCreatorAction

Outbox Action

Diese Action wird verwendet, um mit Hilfe des B2B-Message-Service eine Nachricht via AMQP an das AS4-System zu schicken. Konfigurieren Sie außerdem das Outbox-Relay, um die Einträge zu verarbeiten.

Vorbedingung: die Outbox-Tabelle (Support-Link) wurde angelegt.

Beachten Sie die bestehende Dokumentation zur OutboxAction und richten sie die Action wie nachfolgend beschrieben ein:

Klasse: org.b2bbp.runtime.actions.internal.OutboxAction

Action-Property Expression Erläuterung
HEADERS ${template()}{“direction”: “outbound”, “routingKey”: “https://www.bdew.de/as4/communication/services/FP”} Die Header können für das AMQP Routing genutzt werden.
MESSAGE_STATE_ON_SUCCESS A4P Solange noch keine AS4-Nachricht verschickt worden ist, soll auch noch kein erfolgreicher Verarbeitungsstatus angezeigt werden.
PAYLOAD_ATTRIBUTE ${template(EXCHANGE_AS4_OUTBOUND_PAYLOAD)} Aus diesem Attribut wird der AMQP-Payload später geladen. Dieses Attribut wird von der As4OutboundPayloadJsonCreatorAction geschrieben.

Mail im Fehlerfall

Die ErrorMailHandler-Action ist als letzte Action im Channel zu konfigurieren. Sie verschickt automatisch eine Fehlermail and den Admin bei einem Fehler in der Verarbeitung.

Outbound AMQP Routing

Outbox

Das Outbox-Relay im B2B-Message-Service muss an den AS4-Outbound-Market-Message-Service routen. Konfigurieren Sie hierfür folgende Properties am B2B-Message-Service:

outbox.outbox-relay=true
outbox.outbox-exchange=as4.outbound.request
outbox.outbox-exchange-type=topic

Der Exchange-Type muss ggf. auf Direct gestellt werden. Prüfen Sie (z.B. in der RabbitMQ-UI), welchen Typ die Exchange bei Ihnen hat.

Ergänzen Sie außerdem ein Binding zwischen der Exchange as4.outbound.request und der Queue as4.outbound.request.default mit dem Routing-Key https://www.bdew.de/as4/communication/services/FP. (Nutzen Sie hierfür z.B. die RabbitMQ-UI).

Outbound Receipt

Im Standard werden nur Quittungen von AS4-Edifact-Nachrichten an den B2B-Message-Service geroutet. Damit auch Quittungen von Fahrplan-Nachrichten an den B2B-Message-Service geroutet werden, muss das entsprechende RabbitMQ-Binding zwischen Exchange und Queue ergänzt werden. Dabei enthält das Binding die gewünschten AS4-Service-Ids. Die Bindings können durch den B2B-Message-Service automatisch konfiguriert werden. Hierfür sind folgende Properties am B2B-Message-Service zu setzen:

spring.cloud.stream.rabbit.bindings.outboundAs4ReceiptConsumer-in-0.consumer.bindingRoutingKeyDelimiter=,
outboundAs4ReceiptRoutingKey=https://www.bdew.de/as4/communication/services/MP,https://www.bdew.de/as4/communication/services/FP

Alternativ kann das Binding auch manuell in der RabbitMQ-UI konfiguriert werden.

as4_c_schedule_outbox_receipt_rabbit.png

Outbound-Priorisierung

Es gibt mehrere Ebenen der Outbound-Priorisierung:

  • Priorisierung im B2B-Workflow
  • Priorisierung an der Outbox
  • Priorisierung im AMQP-Routing

Priorisierung im B2B-Workflow

Die Priorisierung des B2B-Workflows erfolgt über die Extension MESSAGE_PRIORITIES.

Sie können z.B. Anhand des Eingangs-Service priorisieren. Konfigurieren Sie hierfür die Extension MESSAGE_PRIORITIES wie folgt (unter der Annahme, dass die Service-Id des Schedule-Eingangsservice SCHEDULE_CRAWLER ist):

equals("B3P_BASE_SERVICE_ID", SCHEDULE_CRAWLER)= high

Priorisierung an der Outbox

Die Priorisierung von Outbox-Einträgen erfolgt durch die Property B2B_OUTBOX_PRIORITY an der Outbox-Action. Diese Form der Priorisierung ist nur nötig, wenn die Outbox nicht nur für Schedule-Nachrichten sondern auch für andere Nachrichten (z.B. Edifact) genutzt wird.

Priorisierung im AMQP-Routing

Grundidee ist eine Priorisierung auf Basis unterschiedlicher Consumer und Queues für unterschiedliche Prioritäten.

Inbound

Die Inbound-Konfiguration gliedert sich in folgende Abschnitte:

  • B2B-Inbound-Service
  • Format Recognition
  • WrongFormatFilterChannelDistribution
  • GENERIC_EDICONDITION_DISTRIBUTION
  • Inbound-Channel
  • Inbound-AMQP-Routing
  • Inbound-Priorisierung

as4_c_schedule_inbound.png

as4_c_schedule_inbound_details.png

(Tip für den Support: Inbound-Architektur)

B2B-Inbound-Service

Die Inbound-Konfiguration basiert auf der grundlegenden AS4-Konfiguration. Bitte beachten Sie daher die entsprechende Dokumentation: AS4 Inbound Customizing.

Dies beinhaltet insbesondere die Konfiguration eines Inbound-Service (Eingang vom AS4-System über AMQP) sowie eines Error-Channels.

Format Recognition

Die Inbound-Format-Recognition entspricht der Outbound-Format-Recognition. Vergleichen Sie bitte die entsprechende Outbound Dokumentation.

WrongFormatFilterChannelDistribution

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

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

org.b2bbp.channels.extension.WrongFormatFilterChannelDistribution.contextParserCondition=${elp(EXCLUDE_FORMAT_CLASSES,${template(EXCLUDE_&(this.FORMAT.attributes.formatClass))},true)}

Dieser Eintrag verweist auf die Extension EXCLUDE_FORMAT_CLASSES. Diese Extension muss folgenden Eintrag enthalten: EXCLUDE_SCHEDULE.

GENERIC_EDICONDITION_DISTRIBUTION

Mit Hilfe dieser Channel Distribution kann ein Routing von Fahrplan-Nachrichten in den Inbound-Fahrplan-Channel erfolgen. Das Routing erfolgt auf Basis des Fahrplan-Formats.

Richten Sie die Channel-Distribution über die Extension EXT_CHANNEL_DIST ein.

registered.classes=\
org.b2bbp.channels.extension.EdiConditionDistributorAllPresentations;\

org.b2bbp.channels.extension.EdiConditionDistributorAllPresentations.registeredServiceIds=*
org.b2bbp.channels.extension.EdiConditionDistributorAllPresentations.executeOnChannelId=IN_ERR

Hierbei wird angenommen, dass der Inbound-Service mit dem Channel IN_ERR beginnt.

Ergänzen Sie dann bitte die folgende Konfiguration in der Extension GENERIC_EDICONDITION_DISTRIBUTION:

"IN_SCHEDULE" <== $messagecontext.FORMAT.type == "SCHEDULE";
"IN_SCHEDULE" <== $messagecontext.FORMAT.type == "ACK";
"IN_SCHEDULE" <== $messagecontext.FORMAT.type == "SRQ";
"IN_SCHEDULE" <== $messagecontext.FORMAT.type == "CNF";
"IN_SCHEDULE" <== $messagecontext.FORMAT.type == "ANO";

Hierbei wird angenommen, dass als Inbound-Fahrplan-Channel IN_SCHEDULE genutzt wird.

Inbound Channel

Für Fahrplan-Nachrichten muss ein separater Channel eingerichtet werden, da der Workflow sich deutlich von einer Edifact Nachricht unterscheidet (so wird z.B. keine Contrl erzeugt). Üblicherweise wird dieser Channel IN_SCHEDULE genannt. Neben der Standard-Fallback-Action (ErrorMailHandler Action) muss dieser Channel mindestens noch eine Action zur Übergabe an das Backend enthalten (z.B. via FTP oder FileWriterService). Arvato kann Sie bei der Wahl einer geeigneten Backend-Schnittstelle unterstützen. Auf das Schedule-Dokument kann über das Attribut B3P_BASE_MESSAGE bzw. das Message-Context Element B3P_OBJ_MESSAGE zugegriffen werden.

Ggf. erfordert Ihr System weitere Actions, z.B. eine IndexAction für die Volltextindizierung. Vergleichen Sie hierfür ihre anderen Inbound-Channels. Für die Volltextindizierung der Fahrplannachrichten kann nicht die gleiche Action verwendet werden, wie für die Edifact-Volltextindizierung. Es wird eine eigene Action mit folgender Eigenschaft benötigt:

Aktionseigenschaft Wert Beschreibung Kontext Überschreiben
TARGET_INDEX_ENTRY B3P_BASE_MESSAGE Zu indizierendes Attribut Ja

Das Routing in den Channel erfolgt über eine ChannelDistribution, z.B. der GENERIC_EDICONDITION_DISTRIBUTION.

Inbound AMQP Routing

Im Standard werden nur AS4-Edifact-Nachrichten an den B2B-Message-Service geroutet. Damit auch Fahrplan-Nachrichten an den B2B-Message-Service geroutet werden, muss das entsprechende RabbitMQ-Binding zwischen Exchange und Queue ergänzt werden. Dabei enthält das Binding die gewünschten AS4-Service-Ids. Die Bindings können durch den B2B-Message-Service automatisch konfiguriert werden. Hierfür sind folgende Properties am B2B-Message-Service zu setzen:

spring.cloud.stream.rabbit.bindings.receivedAs4MessageConsumer-in-0.consumer.bindingRoutingKeyDelimiter=,
inboundEdifactRoutingKey=https://www.bdew.de/as4/communication/services/MP,https://www.bdew.de/as4/communication/services/FP

Inbound-Priorisierung

Es gibt mehrere Ebenen der Inbound-Priorisierung:

  • Priorisierung im B2B-Workflow
  • Priorisierung im AMQP-Routing

Priorisierung im B2B-Workflow

Die Priorität wird über den B2B-Message-Service konfiguriert.

Konfigurieren Sie folgende Properties in der application.yml des B2B-Message-Service:

b2b-queue-priority:
  priority-classes:
    - service-id: "https://www.bdew.de/as4/communication/services/FP"
      level: ultra

Priorisierung im AMQP-Routing

Diese Priorisierung erfolgt analog zur Priorisierung im Outbound-AMQP-Routing.

Frontend

Der Frontend-Abschnitt beinhaltet die folgenden Themen:

  • Filtern im Nachrichtenmonitor
  • AS4_PROTOCOL - Spalte im Nachrichtenmonitor
  • EIC-Codes als Spalten anzeigen

Filtern im Nachrichtenmonitor

Filtern nach den Schedule-Formaten im Nachrichtenmonitor:

Extension B3P_UI_ADDITIONAL_FORMATS

SCHEDULE;ACK;ANO;SRQ;CNF

Anzeige der passenden Referenznummer

Damit die passende Referenznummer im Nachrichtenmonitor für Fahrplannachrichten gesetzt wird, muss die Global Property B3P_CHANNEL_FACTORY_OVERRIDE_CORRELATION_ID_TYPE auf true gesetzt werden.

AS4_PROTOCOL - Spalte im Nachrichtenmonitor

Die Global Property AS4_PROTOCOL = true zeigt die Protokoll-Spalte im Nachrichtenmonitor an.

EIC-Codes als Spalten

Optional können EIC-Codes als Spalten angezeigt werden. Hierfür sind die Additional Columns zu nutzen.

Annahme: Sie nutzen die Additional Columns 1 & 2.

Die Werte können aus dem Format-Objekt mit Hilfe der Extension DISPLAY_EDICONTENT_IN_ADDITIONAL_COLUMN_EXTENDED ausgelesen werden:

additional1=TRUE=${template(&(this.FORMAT.attributes.senderEic))}
additional2=TRUE=${template(&(this.FORMAT.attributes.receiverEic))}

Konfigurieren Sie außerdem wie üblich die Action org.b2bbp.runtime.actions.internal.AdditionalColumnsDataToDBAction in allen Schedule-Channels. Action Property USE_EXTENDED_CONFIG_FORMAT=true.

Konfigurieren Sie die üblichen GlobalProperties wie folgt:

B3P_MON_ADDITIONAL1_KEY = SenderEIC
B3P_MON_ADDITIONAL1_NAME = SenderEIC
B3P_MON_ADDITIONAL1_VALUE = additional1
B3P_MON_ADDITIONAL1_KEY = ReceiverEIC
B3P_MON_ADDITIONAL2_NAME = ReceiverEIC
B3P_MON_ADDITIONAL2_VALUE = additional2
View Me   Edit Me