Mit TRANSCONNECT® 3.4.0 wird ein neuer regelbasierter Verbindungstyp für den HTTP Adapter eingeführt der zeitgleich zum Standard erhoben wird. Der bisherige Standardverbindungstyp (Mappinggesteuert/Transformationsgesteuert) sowie alle anderen Verbindungstypen funktionieren weiterhin, werden aber nun als „deprecated“ eingestuft.

Beispielhaft soll mithilfe des neuen Verbindungstyps hier eine einfache OpenAPI Spezifikation (service-openapi.yml) mit TRANSCONNECT® umgesetzt werden.

Die Beispiel API bildet die folgenden 3 Use Cases ab:

• Rechnung anlegen (HTTP POST Multi-Part)
• Rechnung abrufen (HTTP GET)
• alle Rechnungen listen (HTTP GET)

Die Persistenz wird über die Nutzung des Dateisystem-Adapters sichergestellt.

1. HTTP Eingangsadapter anlegen

Die Verarbeitung von eingehenden HTTP Requests wird nun über eine Regeldatei (XML Format) gesteuert. Diese muss beim Anlegen eines neuen HTTP Eingangsadapters angegeben werden.

Die Datei gliedert sich prinzipiell in 2 Teile.

Mithilfe der MAPPINGS werden die verfügbaren HTTP Endpoints deklariert und deren Verarbeitungsweise festgelegt. Die Konvertierung von Eingangsrequests zu TRANSCONNECT® Nachrichten kann über RULES feingranular gesteuert werden.

2. Verarbeitungsregeln (Mapping) spezifizieren

Unser Beispiel verfügt über 3 Endpoints (2 x GET + 1 x POST). Damit ergibt sich für jeden Endpoint genau 1 Mapping.

<MAPPINGS>
  <MAPPING MESSAGE_TYPE="AddInvoice" PROCESSING="synchronous" RULE_ID="RuleAddInvoice">
    <URL>invoice</URL>
    <METHOD>POST</METHOD>
  </MAPPING>

  <MAPPING MESSAGE_TYPE="GetInvoice" PROCESSING="synchronous">
    <URL>invoice</URL>
    <METHOD>GET</METHOD>
  </MAPPING>

  <MAPPING MESSAGE_TYPE="ListInvoices" PROCESSING="synchronous">
    <URL>invoices</URL>
    <METHOD>GET</METHOD>
  </MAPPING>
</MAPPINGS>

Jedes Mapping deklariert den Nachrichtentyp MESSAGE_TYPE für neu erzeugte Nachrichten sowie die Verarbeitungsmethode PROCESSING. Für die Verarbeitung von REST Requests bietet sich die synchrone Verarbeitung an, da hier immer eine entsprechende Antwort dem anfragenden System direkt zurückgeliefert werden muss.

Insgesamt gibt es nun 3 verschiedene Arten einen Requests zu mappen.

a) Der hier verwendete Mapping-Typ „URL“ erzeugt für Requests die auf die angegebene URL enden eine neue Nachricht.

b) Alternativ wäre es auch möglich auf das Vorhandensein eines bestimmten HTTP Headers zu Prüfen, z.B.

<HEADER>User-Agent</HEADER>
<TOKEN>MyInvoiceClient</TOKEN>

c) Außerdem gibt es die Möglichkeit den Inhalt der Eingangsnachricht gegen einen einfachen XPath-Ausdruck zu matchen. Diese Methode ist allerdings die langsamste Variante, da alle konfigurierten Regeln dieses Typs bis zu einem Treffer gegen die XML-Dokumente geprüft werden. In Abhängigkeit von der Position des Treffers im XML und der Anzahl dieser Art Mappings, verlängert sich die Zeit zum Bearbeiten einer HTTP-Anfrage entsprechend.

Optional kann jedes Mapping durch das Element METHOD auf die entsprechende HTTP-Methode beschränkt werden. Ohne dieses Element werden alle Methoden akzeptiert. Groß-/Kleinschreibung ist beim HTTP-Methodenname irrelevant.

Wenn für eine eingehende HTTP-Anfrage kein Mapping ermittelt werden kann, wird die eingehende HTTP-Anfrage mit einem HTTP 404 Not Found beantwortet und es erfolgt keine weitere Verarbeitung. Es ist jedoch möglich, ein Standard-Mapping zu definieren, welches in diesem Fall die Verarbeitung steuert.

Ein separates Eingangsmapping (XSLT) ist für diese neue Verbindungsart nicht mehr notwendig.

3. Konvertierungsregeln anlegen

Im Beispiel wird auch eine explizite Konvertierungsregel für den Nachrichtentyp „AddInvoice“ vereinbart.

<RULES>
  <RULE ID="RuleAddInvoice">
    <INCLUDE>
      <CONTENT_TYPE>application/json</CONTENT_TYPE>
      <CONTENT_TYPE>application/pdf</CONTENT_TYPE>
    </INCLUDE>
  </RULE>
</RULES>

Hier werden bei einem Multi-Part Request z.B. nur die Teile in die TRANSCONNECT® Eingangsnachricht übernommen, die den angegebenen Content-Type haben. Die Metadaten der Rechnung erwarten wir im JSON Format während das eigentliche Rechnungsdokument als PDF übermittelt werden muss. Alle anderen HTTP Parts werden verworfen und stehen für eine nachgelagerte Verarbeitung in TRANSCONNECT® somit nicht mehr zur Verfügung.

Für alle anderen Mappings ohne explizite Konvertierungsregel gilt folgende Standardregel:

• alle Parts der HTTP-Anfrage werden übernommen
• XML und JSON-Daten werden in das XML-Dokument der Nachricht
  eingefügt, andere Parts als Anhang gespeichert, JSON wird in XML
  konvertiert

4. Orchestrierung anlegen

Für jeden HTTP Endpoint wird nun in der Orchestrierung eine neue Route + Prozess angelegt.

5. Prozessimplementierung

Die konkreten Prozesse müssen nun die entsprechenden Eingangsnachrichten verarbeiten und am Ende eine Ergebnisnachricht nach folgendem Schema liefern:

<ROOT>
  <STATUS CODE="503" ERRORMESSAGE="Fehler beim Einfügen in die Datenbank" />
  <HEADER NAME="name">wert</HEADER>
  …
  <CONTENT FILENAME="Dateiname" ENCODING="Kodierung" CONTENT-TYPE="Typ" CONTENTID="Anhang">
    payload
  </CONTENT>
</ROOT>

Diese wird dann wiederum in eine synchrone HTTP Response für den Aufrufer konvertiert. Ein separates Ausgangsmapping (XSLT) ist für diese neue Verbindungsart nicht mehr notwendig.

Liefert ein Prozess keine Ergebnisnachricht zurück, so wird standardmäßig der HTTP Code 200 (OK) zurückgegeben.

Weiterführende Details zur Konfiguration und Nutzung des HTTP Eingangsadapters entnehmen Sie auch dem Handbuch in Abschnitt 9.10.2 (Adapterreferenz -> HTTP -> Interaktion RECEIVE).