Einstellungen

(1) Swagger Import: Die Vorlagen erhalten Sie im Update-Center. Rechts daneben können Sie eine Swagger-Datei (direkt oder per URL) hochladen. Dabei werden diverse Einstellungen im Eingangsagenten gesetzt (HTTP-Methode, URL, Content-Type) und gegebenenfalls auch eine passende Quellstruktur angelegt (und Zielstruktur per 1:1-Mapping). Enthält der Pfad eine URL-Variable, werden passende MSG_CALL_-Variablen im Profil angelegt und in die URL eingefügt (→ Profil per HTTP triggern). Beispiel: "https://petstore.swagger.io/v2/swagger.json und Pfad [GET] /pet/{petId}".

Beispiel: https://petstore3.swagger.io/api/v3/openapi.json

(1.1) Endpoint: Geben Sie die URL an (oder laden Sie eine Datei hoch). Beispiel: "https://petstore3.swagger.io/api/v3/openapi.json".

(1.2) Anfragen: Klicken Sie hier.

(1.3) Path: Wählen Sie den gewünschten Pfad aus.

(1.4) Anwenden: Klicken Sie hier.

Hinweis: Siehe auch Abschnitt Designer (Data Flow) (→ Swagger import).

(2) API Protokoll: Die Option Ist eine SOAP-WS Anfrage ist nur nötig, wenn ein SOAP-Webservice aufgerufen wird. In diesem Fall erscheinen weitere Buttons unter dem Datenfeld. Siehe Abschnitt Mit Profil SOAP-Webservice aufrufen im Eingangsagenten.

(3) HTTP Methode: Die zu verwendende HTTP-Methode (GET, GET (with content), POST, PUT, PATCH, DELETE, DELETE (with content), HEAD).

(4) URL: Die URL (mit Port) zum Abfragen der Daten vom entfernten HTTP(S)-Server. Hinweis: Es findet keine URL-Kodierung statt. Hinweis: Der Platzhalter <serverurl> wird ersetzt durch den Wert des Kanal-Feldes "Partner Adresse", falls ein Kanal (14) ausgewählt wurde. Hinweis: Sie können in der URL den Platzhalter {--0:s#<template>--} für den Zeitstempel des letzten Laufs des Profils verwenden. Beachten Sie bitte, dass der Zeitstempel nur aktualisiert wird, wenn Sie den Platzhalter auch wirklich in der URL oder in (13) verwenden. Zudem muss der HTTP-Response-Status-Code >= 200 und < 300 sein. Beispiel: http://example.com?time={--0:s#yyyyMMdd--} Hinweis: Siehe auch Abschnitt Paging/Pagination unten. Hinweis: Sie können Variablen (Syntax @MSG_CALL_MYVAR@), System-Konstanten (Syntax %MYCONST%) und permanente Profil-Werte (Syntax %perm:KEYNAME%) verwenden (→ Auswahlmenü).

(5) Via DMZ: Wenn gesetzt, dann wird anstatt vom internen Integration Server vom DMZ-Server aus gesendet (falls vorhanden). Hinweis: Das betrifft auch den OAuth-Token-Refresh, wenn ein Kanal (14) mit konfiguriertem OAuth angegeben wurde.

(6) URL automatisch encoden: Ist die Checkbox gesetzt, wird für den Wert in (4) automatisch ein URL-Encoding durchgeführt.

(7) Timeout: Der Timeout für die HTTP-Verbindung.

(8) HTTP-Header anpassen: Hier können zusätzliche HTTP-Request-Header eingefügt werden. Siehe Abschnitt Request-Header unten. Hinweis: Wird ein Kanal verwendet, können Header auch dort in den Zusatzkennungen definiert werden. Hinweis: Sowohl für den Header-Namen, als auch für den Wert können Variablen ausgewertet werden (Syntax @MSG_CALL_MYVAR@). Beim Wert sind zudem System-Konstanten (Syntax %MYCONST%) und permanente Profil-Werte (Syntax %perm:KEYNAME%) erlaubt (→ Auswahlmenü).

(9) Anfragen & Struktur erzeugen: Führt einen Request aus und öffnet für die Response den Datei-Struktur-Analyse-Dialog, um damit eine passende Quellstruktur zu erzeugen. Hinweis: Kann auch verwendet werden, wenn in (2) SOAP eingestellt ist, für den Fall, dass die Gegenstelle keine WSDL liefert.

(10) Multipart/form-data: Zum Erzeugen eines Multipart-Requests. Es können Parts bzw. Datei-Parts eingefügt werden. Siehe Abschnitt Multipart unten.

(11) MimeType: Der MIME-Type (Header Content-Type). Hinweis: Per Default wird im Content-Type auch das Encoding (aus den "Basis-Daten") angegeben, z. B. application/octet-stream;charset=ISO-8859-1. Möchte man das unterbinden, dann kann man stattdessen im Feld den Wert application/octet-stream;raw angeben, dann wird für den Content-Type lediglich der Wert application/octet-stream verwendet. Wenn Sie den Haken in (12) entfernen, wird das automatisch für Sie eingetragen.

(12) Encoding zum ContentType hinzufügen: Siehe Hinweis in (11).

(13) Daten: Die Body-Daten (nicht vorhanden bei HTTP-Methoden (3) HEAD, GET und DELETE oder wenn (10) benutzt wird). Sie können in (13) System-Konstanten in der Form %MYCONSTANT% verwenden. Hat die System-Konstante als Wert einen Datums-Platzhalter, z. B. <yyyy>-<MM>-<dd>, dann wird das aktuelle Datum ausgegeben in diesem Format. Hinweis: Sie können in den Daten den Platzhalter {--0:s#<template>--} für den Zeitstempel des letzten Laufs des Profils verwenden. Beachten Sie bitte, dass der Zeitstempel nur aktualisiert wird, wenn Sie den Platzhalter auch wirklich in den Daten oder in (4) verwenden. Zudem muss der HTTP-Response-Status-Code >= 200 und < 300 sein. Beispiel: {--0:s#yyyyMMdd--} Hinweis: Es können MSG_CALL_-Variablen verwendet werden.

(14) Kanal-Auswahl: Hier kann ein Kanal des Typs "HTTP" ausgewählt werden. Es werden dann in (16) die Authentifizierungsdaten aus dem Kanal verwendet ("Eigene Kennung" und "Eigenes Kennwort").

(15) Zertifikats-Auswahl: Wenn (4) eine HTTPS-URL ist, kann man optional ein Client-Zertifikat zuordnen. Dazu wählt man eines der eigenen Zertifikate aus.

(16) Benutzer, Kennwort: Optional können hier Authentifizierungsdaten hinterlegt werden. Auch die Verwendung von MSG_CALL_-Variablen ist erlaubt. Alternativ können die Authentifizierungsdaten eines ausgewählten Kanals verwendet werden, siehe (14). MS-IIS mit Authentifizierung durch NTLM-v1 oder NTLM-v2:

Falls der HTTP-Server, zu dem eine Verbindung hergestellt werden soll, ein MS-IIS ist und eine integrierte Windows-Authentifizierung vom Typ NTLM Version 1 oder 2 erwartet, kann dem Usernamen ein Domänen-Name vorangestellt werden. Im Feld für den Benutzernamen wird dann folgende Syntax erwartet (bitte doppelten Backslash beachten).

(17) Auch bei HTTP-Status ungleich 2xx fortfahren: Ist diese Checkbox gesetzt, dann führen HTTP-Status-Codes ungleich 2xx (Erfolg) nicht zu einem Abbruch des Profils. Das erlaubt eine eigene Fehlerbehandlung. Siehe Abschnitt "Response und Response-Header" unten. Hinweis: Beachten Sie aber bitte, dass das nicht funktioniert, wenn der Request nicht funktioniert und gar keine Daten zurück liefert, also z. B. wenn der Server nicht erreichbar ist. Wenn das Profil keine Daten erhält, entsteht kein Job.

(18) Parallelverarbeitung aktivieren: Ist diese Checkbox gesetzt, wird erreicht, dass mehrere Instanzen dieses Profils parallel arbeiten können. Die Checkbox Profil darf nur in einer Instanz laufen darf für dieses Profil nicht gesetzt werden. Hinweis: Ist diese Option gesetzt, werden Jobs dieses Profils in einer Thread Queue abgearbeitet.

(19) Paging aktivieren: Siehe Abschnitt "Paging/Pagination" unten.

Multipart

Request-Header

Zusätzliche Request-Header können über (8) eingefügt werden. Wird ein Kanal (14) verwendet, können dort ebenfalls Request-Header gesetzt werden, siehe Abschnitt Zusatzkennungen (im Kanal). Wird ein gleichnamiger Header gesetzt, hat der im Profil gesetzte Vorrang.

Hinweis: Sie können den Header Set-Cookie verwenden, um Cookies zu schreiben.

Response und Response-Header

Die Ausführung des Profils wird fortgesetzt für alle Response-Status 2xx, ansonsten entsteht ein Fehler. Über Checkbox (17) kann dieses Verhalten aber verändert werden.

Response-Header können ausgelesen werden mit den System-Variablen MSG_CALL_VAR_HTTP_<Name des Headers in Großbuchstaben>. Siehe auch MSG_CALL_VAR_HTTP_STATUS_CODE und MSG_CALL_VAR_HTTP_STATUS_LINE.

Raw Request/Response

Wenn Sie bei Verwendung der HTTP-Methode POST (speziell bei Multipart) den Raw Request und die Raw Response (und die jeweiligen Header) zu Testzwecken sehen möchten, finden Sie diese auf der Seite Allgemeine Meldungen als Base64-kodierten String, wenn Sie die Trace-Meldungen für Phase 1 in der Logging-Konfiguration aktivieren. Dekodieren können Sie diesen mit dem Plugin Enkodierer/Dekodierer. Alternativ können Sie natürlich auch externe Tools wie z. B. https://requestcatcher.com/ verwenden.

Paging/Pagination

Paging (oder Pagination) bezeichnet den Vorgang, sich beim Aufruf einer REST API, die sehr große Datensätze liefert, sich diese durch mehrere Teildatensätze liefern zu lassen.

Das können Sie auf folgende Weise umsetzen. Sie erzeugen ein Profil mit diesem Eingangsagenten und tragen die erste URL ein. Diese URL ist abhängig von der verwendeten REST API, zum Beispiel:

Der erste Aufruf erfolgt, wie Sie das kennen, durch einen normalen Start des zeitgesteuerten Profils.

Um das Paging zu aktivieren, muss die Checkbox "Paging aktivieren" (19) gesetzt sein.

Zudem muss Variable VAR_SYS_HTTP_PAGING_URL angelegt sein.

Die Variable füllen Sie nun im Mapping mit der URL für den nächsten Request (also für den nächsten Teildatensatz). Diese URL müssen Sie entweder selbst aufbauen, oder Sie erhalten Sie in einem Response Header Ihres Requests (auslesbar über Variablen, wie Sie das kennen). Das Profil wird dann automatisch erneut aufgerufen mit dieser URL (was einen weiteren Job erzeugt). Hinweis: Eine gesetzte Checkbox (6) hat hier keinen Effekt.

Dieser Vorgang wird so lange wiederholt, bis die Variable den selben Wert enthält, den sie beim letzten Request hatte oder wenn der letzte Request einen leeren Body geliefert hat. Wird zusätzlich die Checkbox Weitere Seiten beim Paging über gleiche URL abrufbar gesetzt, dann wird der Vorgang auch wiederholt, wenn sich der Wert der Variable nicht ändert. Achtung: Verwenden Sie diese Option bitte mit Vorsicht, da dadurch sehr viele Jobs erzeugt werden können! Nach 1000 Wiederholung erfolgt ein automatischer Abbruch.