REST Connector

Verwendung

Der REST Connector bietet eine Schnittstelle, um Daten via HTTP zu übertragen, ohne dass es dabei eine zusätzliche Transportschicht wie z.B. SOAP gibt. Der REST Connector wird genutzt, um REST-konforme Web Services über eine URL aufzurufen oder anzubieten.

Konnektortypen

Die Funktionen des REST Connectors hängen von der konkreten Konfiguration ab:

Input Listener Connector

Stellt eine Ressource unter einer angegebenen URL zur Verfügung, die von einem Client per Request angefragt werden kann. Die angebotene Ressource stellt dabei das Ergebnis einer Workflow-Ausführung dar.

Alle Parameter und Header, die mit dem Request übergeben wurden, stehen während der Workflow-Ausführung als Modulvariablen zur Verfügung.
Medium/Output Connector

Sendet als Client HTTP-Requests an einen HTTP-Server und gibt - im Fall des Medium Connectors - die zurückgelieferte Antwort (falls vorhanden) an den Workflow weiter.

Modulvariablen

Bei der Ausführung eines REST Connectors werden abhängig vom Konnektor-Typ folgende Variablen gesetzt und stehen im weiteren Verlauf der Workflow-Ausführung zur Verfügung:

Input Listener Connector

Für die Daten der empfangenen Anfrage werden folgende Variablen gesetzt:

restConnector.requestMethod

Enthält den Namen der HTTP-Methode der Anfrage.
restConnector.requestHeaders

Enthält die Header-Daten der Anfrage-Nachricht.
restConnector.requestQueryParams

Enthält die Werte der Query-Parameter aus der Anfrage-URL. Diese werden in eine XML-Struktur überführt und jeder Parameter wird in ein XML-Element umgesetzt.
restConnector.requestResourcePath

Enthält den Pfad der angeforderten Ressource. Die Variable enthält z.B. bei der Anfrage-URL https://<server>:<port>/ibis/rest/rc/orders/123 den Wert /orders/123.
restConnector.requestURITemplateParam.x

Enthält die Inhalte von dynamischen Pfadbestandteilen der Anfrage-URL. x steht dabei jeweils für den in geschweiften Klammern stehenden Namen des Pfadbestandteils innerhalb der am Connector konfigurierten Ressourcen-URL. So werden z.B. bei der Ressourcen-URL users/{userName}/auftraege/{auftragsNr} die Variablen restConnector.requestURITemplateParam.userName und restConnector.requestURITemplateParam.auftragsNr mit den konkreten Werten aus der Anfrage-URL gesetzt.
restConnector.clientAddress

Enthält die IP-Adresse des aufrufenden Clients.
restConnector.requestAuthUser

Enthält den Namen des authentifizierten Benutzers, falls bei den Authentifizierungs-Optionen Portal-Benutzerdaten verwenden ausgewählt wurde.

Die Status- und Header-Daten der zu versendenden Antwort werden in folgende Variablen geschrieben:

restConnector.responseStatusCode

Enthält Antwortcode für das Ergebnis der gesendeten Antwort.
restConnector.responseStatusDescription

Enthält die Beschreibung des Antwortcodes.

restConnector.responseHeaders

Enthält die Header-Daten der gesendeten Antwort-Nachricht.

Der Inhalt der Variablen entspricht den im Konnektor konfigurierten Standardwerten. Die Variablen dienen dazu, im Workflow dynamisch überschrieben zu werden. Der Wert der Variable, der am Ende des Workflows zur Verfügung steht, wird für den Versand der Antwort verwendet.

Medium/Output Connector

Die Status- und Header-Daten der empfangenen Antwort werden in folgende Variablen geschrieben:

restConnector.responseStatusCode

Liefert den Antwortcode, der das Ergebnis der Abfrage angibt.
restConnector.responseStatusDescription

Liefert die Beschreibung des Antwortcodes, z.B. Internal Server Error.
restConnector.responseHeaders

Liefert die Header-Daten der Antwort-Nachricht.

Siehe Workflow-Variablen und Mappings

REST-Funktionsprinzip

HTTP - Ressourcen - URLs

REST (Representational State Transfer) ist ein Architektur-Konzept für Web Services, das beschreibt, wie Web-Standards in einer Web-gerechten Weise einsetzt werden können. REST-basierte Web Services nutzen das HTTP-Protokoll und die HTTP-Methoden wie GET oder POST.

Ein Grundprinzip dieses Modells ist, dass die Funktionalität eines Web Service nicht in dessen Eigenschaften abgebildet wird, sondern in Ressourcen des Service. Die einzelnen Funktionen eines Dienstes werden dabei in einzeln über URLs adressierbare Ressourcen zerlegt.

REST bietet damit die Möglichkeit, Applikationen wie z.B. einen Online-Shop über eine URL zu adressieren. Dabei stellt jedes einzelne Objekt der Anwendung wie Artikel oder Kunde eine Ressource dar, die über eine eigene URL angesprochen wird.

Jede REST-Ressource besitzt über die verschiedenen HTTP-Methoden eine generische Schnittstelle.

Für das Beispiel eines Online-Shops als REST-Service gibt es bei der Auftragsverwaltung z.B. eine URL für die Menge der Bestellungen jedes Kunden und eine URL für jede Bestellung.

Die Kommunikation erfolgt nur bei Bedarf auf Abruf. Der Client bzw. Konnektor wird aktiv und fordert vom Server eine Repräsentation einer Ressource an bzw. modifiziert eine Ressource.

Ressourcen

Im Beispiel des Online-Shops stellt dieser eine Ansammlung von Ressourcen dar, an die per HTTP Nachrichten gesendet werden können, z.B. zum Aufruf eines Kunden zu einer Bestellung in einem Warenkorb. Die Ressource wird dabei nicht direkt manipuliert, denn der Zugriff erfolgt indirekt über die der Ressource zugeordnete URL.

Beispiele für Ressourcen

Online-Shop als Web Service:

https://<server>:<port>/ibis/rest/sqlshop

Auflistung aller Aufträge:

https://<server>:<port>/ibis/rest/sqlshop/orders

Auftrag mit der Nr. 1234:

https://<server>:<port>/ibis/rest/sqlshop/orders/1234

Repräsentationen

Jede Ressource kann verschiedene Repräsentationen haben, d.h. der Kunde kann z.B. durch eine XML-Struktur mit den Kundenstammdaten oder durch eine Visitenkarte im vcard-Format repräsentiert sein. Zwischen Client und Server muss ein gemeinsames Verständnis über die Bedeutung der Repräsentation durch die Verwendung von XML vorhanden sein.

Repräsentationen können auf weitere Ressourcen verweisen, die ihrerseits wieder Repräsentationen liefern, die wiederum auf Ressourcen verweisen können. Wenn ein Client einem Link in einer Repräsentation folgt, gelangt er zu einer anderen Ressource.

Beispiele für Repräsentationen

Repräsentation eines Kunden durch seine Stammdaten:

<CUSTOMER>
    <ID>4</ID>
    <FIRSTNAME>Heinz</FIRSTNAME>
    <LASTNAME>Mustermann</LASTNAME>
    <STREET>Musterstraße. 13</STREET>
    <CITY>Musterstadt</CITY>
</CUSTOMER>

Repräsentation einer Kundenliste mit Verlinkungen auf die einzelnen Kunden als weitere Ressourcen:

<CUSTOMERList>
    <CUSTOMER xlink:href="https://www.inubit.com/sqlrest/CUSTOMER/1/">1</CUSTOMER>
    <CUSTOMER xlink:href="https://www.inubit.com/sqlrest/CUSTOMER/2/">2</CUSTOMER>
    <CUSTOMER xlink:href="https://www.inubit.com/sqlrest/CUSTOMER/3/">3</CUSTOMER>
    <CUSTOMER xlink:href="https://www.inubit.com/sqlrest/CUSTOMER/4/">4</CUSTOMER>
    <CUSTOMER xlink:href="https://www.inubit.com/sqlrest/CUSTOMER/29/">29</CUSTOMER>
</CUSTOMERList>

Methoden

Das REST-Prinzip sieht vor, dass auf Ressourcen mit den Standard-HTTP-Methoden GET, POST, PUT und DELETE zugegriffen wird. Dadurch müssen keine Protokoll-Konventionen bekannt sein, damit Client und Server kommunizieren können. Eine Anfrage (Request), z.B. nach einer bestimmten Bestellung, besteht immer aus einer URL und einer HTTP-Methode. Die HTTP-Methoden bilden dabei die grundlegenden Aktionen auf den Ressourcen ab.

Siehe Parameter im HTTP Connector setzen und anzeigen

HTTP-Methoden im REST Connector verwenden

Die in den REST Connectoren konfigurierbaren HTTP-Methoden decken die Anwendungsfälle von REST-Anwendungen ab.

HTTP-Methode Bedeutung

HTTP-Methode	Bedeutung
`GET`	GET fragt die Repräsentation einer Ressource ab. GET-Requests können beliebig oft abgeschickt werden.
`POST`	Mit POST kann einer Ressource etwas hinzugefügt werden. Beispielsweise könnte eine Ware zu einem Warenkorb hinzugefügt werden.
`PUT`	Neue Ressourcen können mit PUT erzeugt oder der Inhalt bestehender Ressourcen ersetzt werden.
`PATCH`	Mit PATCH können einzelne Attribute einer Ressource geändert werden. PATCH spart Bandbreite, da es partielle Aktualisierungen ermöglicht. Außerdem lässt sich mit PATCH (gegenüber PUT) präziser steuern, welche Attribute einer Resource geändert werden dürfen und welche nicht.
`DELETE`	Ressourcen können mit DELETE gelöscht werden.
`OPTIONS`	Liefert eine Liste mit den vom Server unterstützten Methoden.
`HEAD`	Genau wie bei GET wird eine Ressource angefragt, es wird jedoch in der Antwort kein Inhalt (Body) übertragen, sondern nur der Response Header. So kann z.B. vor einer GET-Anfrage die Dateigröße abgefragt werden. Um verschiedene Methoden auf eine Ressource anzuwenden, wird immer die gleiche URL verwendet, denn die URL ist unabhängig von der durchgeführten Aktion.

GET

GET fragt die Repräsentation einer Ressource ab. GET-Requests können beliebig oft abgeschickt werden.

POST

Mit POST kann einer Ressource etwas hinzugefügt werden. Beispielsweise könnte eine Ware zu einem Warenkorb hinzugefügt werden.

PUT

Neue Ressourcen können mit PUT erzeugt oder der Inhalt bestehender Ressourcen ersetzt werden.

PATCH

Mit PATCH können einzelne Attribute einer Ressource geändert werden. PATCH spart Bandbreite, da es partielle Aktualisierungen ermöglicht. Außerdem lässt sich mit PATCH (gegenüber PUT) präziser steuern, welche Attribute einer Resource geändert werden dürfen und welche nicht.

DELETE

Ressourcen können mit DELETE gelöscht werden.

OPTIONS

Liefert eine Liste mit den vom Server unterstützten Methoden.

HEAD

Genau wie bei GET wird eine Ressource angefragt, es wird jedoch in der Antwort kein Inhalt (Body) übertragen, sondern nur der Response Header. So kann z.B. vor einer GET-Anfrage die Dateigröße abgefragt werden.

Um verschiedene Methoden auf eine Ressource anzuwenden, wird immer die gleiche URL verwendet, denn die URL ist unabhängig von der durchgeführten Aktion.

Ressource anbieten

Prinzip

Einen Web Service in Form einer REST-Ressource können Sie durch einen Technical Workflow mit einem REST Input Listener Connector realisieren. Der REST Connector bietet dann nach außen eine Ressource (z.B. eine Auftrags- oder Artikelliste) in Form einer URL an. Einzelne Ressourcen werden jeweils über einen einzelnen REST Input Connector angeboten.

Die Ressourcen sind einzelne Objekte einer Anwendung, die über eine URL erreichbar sein müssen und mit einem Dokument, vorzugsweise in XML, repräsentiert werden können.

So gehen Sie vor

Ressource konfigurieren

Erstellen Sie einen REST Input Listener Connector.
Wählen Sie aus der Liste unter Vorgaben verwenden für, welche Art von Ressource dieser Konnektor anbieten soll.

Siehe Bereitgestellte Ressource

Definieren Sie eine URL, unter der auf die Ressource zugegriffen werden kann.

Für dynamische Pfadbestandteile können geschweifte Klammern verwendet werden, z.B. https://<server>:<port>/ibis/rest/orders/{orderID}. Hier wird der Wert von orderID als Workflow-Variable im Workflow zur Verfügung gestellt und kann benutzt werden, um die Daten des gewünschten Auftrags zu ermitteln, siehe Modulvariablen. Geben Sie * am Ende des Pfades ein, um Pfade zu unterstützen, die mit beliebigen Zeichen enden.

Sichern Sie Ihren Rest-Service vor unzulässigen Zugriffen durch Aktivieren der Option Authentifizierung erforderlich.
Legen Sie die gewünschte Authentifizierungsmethode fest und geben Sie die für einen Request erforderlichen Zugangsdaten an.
Legen Sie fest, welche Operationen auf Ihrer Ressource ausgeführt werden können.

Es sind nicht für jeden Ressourcentyp alle HTTP-Methoden zugelassen. Standardmäßig sind die für eine gewählte Ressource sinnvollen HTTP-Methoden vorausgewählt.
Legen Sie die Kodierung für Daten fest, die als Request im Format multipart/form-data eingehen.

Antwort konfigurieren

Sie definieren für jede zulässige HTTP-Methode, mit der die Ressource angefragt werden kann, die von der Ressource zurückgelieferte Antwort.
1. Konfigurieren Sie für die verfügbaren Anfrage-Typen die Antwortdaten.
  
  Siehe Dialog Konfiguration der Antwort im REST Connector
  
  Die hier konfigurierten Werte können im Workflow dynamisch über das Ändern entsprechender Variablen geändert werden.
  
  Siehe Modulvariablen

Bei Ressourcen mit mehreren unterstützten Methoden ist die Variable restConnector.requestMethod besonders wichtig, da anhand des Wertes dieser Variable im Workflow verzweigt werden kann, um die jeweilige Methode zu implementieren.

Beispiel für Sammel-Ressource

Beispiel für Einzel-Ressource aus Sammlung

Bei eingehenden Requests mit HTML-Form-Daten und dem Content-Type application/x-www-form-urlencoded werden die Form-Daten automatisch in ein XML-Dokument gesetzt. Dieses XML-Dokument wird zur Eingangsnachricht des Workflows.

Verfügbare Input REST Connectoren anzeigen

Sie können sich eine Liste aller in INUBIT Workbench erstellten, verfügbaren, aktiven und inaktiven REST Input-Konnektoren anzeigen lassen.

So gehen Sie vor

Wählen Sie einen REST Input Listener Connector aus und öffnen Sie diesen zum Bearbeiten.
Klicken Sie im Dialog im Bereich Bereitgestellte Ressourcen neben der URL auf .

Siehe Dialog HTTP Connector Eigenschaften
Wählen Sie die Option Alle REST Input-Konnektoren auflisten.

Ein Dialog öffnet sich, das eine Liste aller angelegten Input Connectoren anzeigt. In der Liste wird der Name des Konnektors, der entsprechende Workflow, der Pfad für die Ressource und die für den Konnektor verfügbaren HTTP-Methoden aufgeführt.

Darüber hinaus können Sie sich eine Liste aller angebotenen REST-Services im Web-Browser anzeigen lassen:

https://<server>:<port>/ibis/rest/rc?method=OPTIONS

Publizierte REST-Ressourcen anzeigen

Sie können sich eine Liste mit allen publizierten und aktivierten Ressourcen anzeigen lassen.

So gehen Sie vor

Wählen Sie einen REST Input Listener Connector aus und öffnen Sie diesen zum Bearbeiten.
Klicken Sie im Dialog im Bereich Bereitgestellte Ressourcen neben der URL auf .

Siehe Dialog Konfiguration der Ressource
Wählen Sie die Option Publizierte Ressourcen anzeigen. Im Browser öffnet sich eine Seite, die aufbereitete Liste mit allen aktivierten Ressourcen anzeigt.

Ressourcen, die mit einem REST Input Listener Connector realisiert sind, werden erst als publiziert und aktiviert angezeigt, wenn die entsprechenden Technical Workflows aktiviert sind.

REST-Ressource aufrufen

Prinzip

Sie können mit dem REST Connector eine Ressource, die über eine bestimmte URL zur Verfügung steht, aufrufen. So können Sie z.B. eine Artikelliste anfordern. Sie müssen dazu einen REST Output oder Medium Connector zum Versenden der Anfrage und zum Empfangen der Antwort anlegen und konfigurieren.

Medium Connector

Verwenden Sie den Medium Connector, wenn die aufgerufene Ressource eine Antwort zurücksendet, die im Workflow weiterverarbeitet werden soll.
Output Connector

Verwenden Sie den Output Connector, wenn die Anfrage an eine Ressource ein Aufruf ohne Rückgabe ist.

Voraussetzungen

URL der aufzurufenden Ressource ist verfügbar.
Authentifizierungsdaten sind verfügbar, falls der Server für die Ressource eine Authentifizierung fordert.

So gehen Sie vor

Legen Sie einen neuen REST Medium oder Output Connector.
Geben Sie die URL der aufzurufenden Ressource ein.
Geben Sie ggf. die erforderlichen Authentifizierungsdaten ein.

Siehe Dialog Konfiguration der Anfrage
Wählen Sie je nach Art der Anfrage die gewünschte HTTP-Methode.

Siehe Parameter im HTTP Connector setzen und anzeigen
Falls Sie als Methode PUT oder POST gesetzt haben, wählen Sie jeweils eine Option aus der Liste der Medientypen und des Zeichensatzes aus.

Siehe Dialog Konfiguration der Anfrage

Damit legen Sie die Definition der Daten fest, die verschickt werden. Die Werte der Anfragedaten werden in den Content-Type-Header übernommen.
Optional können Sie Anpassungen im Request-Header vornehmen, z.B. wenn Sie für Ressourcen, die mehrere Repräsentationen unterstützen, die gewünschte Repräsentation der angefragten Ressource festlegen wollen. Dazu nutzen Sie den Accept-Header:
1. Klicken Sie auf den Button Header bearbeiten. Ein Dialog öffnet sich. Standardmäßig wird mit / eine beliebige Repräsentation einer Ressource abgefragt.
2. Doppelklicken Sie den Accept-Header. Ein weiterer Dialog öffnet sich:
3. Wählen Sie einen Medien-Typen aus. Sie können auch mehrere Typen auswählen und es wird dann eine geordnete Liste der gewünschten Repräsentationen zurückgeliefert.
4. Schließen Sie die Dialoge zum Bearbeiten des HTTP-Headers mit OK.
Klicken Sie Fertig stellen.
Publizieren Sie den REST Connector.

Für das Abfragen einer Ressource mit GET benötigen Sie keine Ausgangsnachricht, da die Ressource nur angefragt, jedoch keine Änderung an den Daten vorgenommen werden. Für das Zugreifen auf eine Ressource mit POST oder PUT benötigen Sie eine Ausgangsnachricht. Falls Sie z.B. Daten in eine Artikelliste hinzufügen möchten, können Sie mit einem XSLT Converter im Workflow vor dem REST Connector eine XML-Nachricht erstellen und diese mit versenden, z.B.:

<artikel>
  <beschreibung>Rooibusch-Tee</beschreibung>
  <preis>2,80</preis>
  <einheit>100g</einheit>
</artikel>

Alle Eingangsnachrichten in den REST Output/Medium Connector werden mit der Anfrage versendet.

Sie können die aufzurufende URL der Ressource dynamisch anpassen, indem Sie die Moduleigenschaft Request.URI mithilfe des Variablen-Mappings überschreiben siehe Workflow-Variablen und Mappings.

Header dynamisch setzen und überschreiben

Verwendung

Sie können das Variablenmapping nutzen, um Header zu überschreiben oder um neue Header zu setzen, siehe Workflow-Variablen und Mappings.

So gehen Sie vor

Um Response-Header in einem Workflow mit einem REST Input Listener Connector zu überschreiben, setzen Sie die Workflowvariablen restConnector.ResponseHeader.[headerName] irgendwo im Workflow bevor die Antwort als Ausgangsnachricht zurückgegeben wird.

Die folgenden Response-Header werden vom REST Connector selbst gesetzt und können nicht vom Benutzer überschrieben werden, z.B. über das Variablenmapping.
```
Allow
Connection
Content-Length
Content-Encoding
Content-Type
Content-MD5
Content-Range
Proxy-Authenticate
Server
Via
WWW-Authenticate
```
Um Request-Header für die Anfrage eines REST Medium oder Output Connector-Moduls zu überschreiben, setzen Sie die Moduleigenschaften Request.Header.[headerName] des REST Connector-Moduls.

Die folgenden Request-Header werden vom REST Connector selbst gesetzt und können nicht vom Benutzer überschrieben werden, z.B. über das Variablenmapping.
```
Accept
Accept-Charset
Accept-Encoding
Accept-Language
Cookie
Expect
From
Host
If-Match
If-Modified-Since
If-None-Match
If-Range
If-Unmodified-Since
Max-Forwards
Proxy-Authorization
Range
Referer
User-Agent
```

Dialogbeschreibungen

Dialog Konfiguration der Ressource

(Input Listener Connector)

In diesem Dialog legen Sie den Pfad für die vom Konnektor angebotene Ressource, die Authentifizierung und die HTTP-Methoden fest.

Bereitgestellte Ressource

Vorgaben verwenden für

Wählen Sie aus, welchen Typ von Ressource der Konnektor anbieten soll. Die Wahl des Ressourcen-Typs legt gleichzeitig die Vorauswahl der standardmäßig unterstützten HTTP-Methode(n) fest.

Siehe Unterstützte HTTP-Methoden unten
- Einzelne Ressource
  
  Wählen Sie die Option, wenn nur lesend auf eine einzelne Ressource zugegriffen werden soll, z.B. Bestellung anzeigen. Es wird automatisch die HTTP-Methode GET vorausgewählt.
- Sammel-Ressource
  
  Wählen Sie die Option, wenn die Ressource z.B. eine Liste von Aufträgen (/auftraege) umfassen soll und diese Liste abgerufen oder der Liste neue Einträge hinzugefügt werden sollen. Es sind standardmäßig nur die Methoden GET und POST erlaubt.
- Einzel-Ressource aus Sammlung
  
  Wählen Sie diese Option, wenn Sie z.B. einen einzelnen Auftrag aus einer Auftragsliste oder eine Artikelnummer als Ressource anbieten wollen. Unterstützte Methoden sind hier GET (Daten abrufen), PUT (Daten ändern) und DELETE (Daten löschen).
URL

URL des Input Listeners, unter welcher dieser auf Requests wartet und seine Ressource zur Verfügung stellt. Die URL ist standardmäßig nach folgendem Muster vorbelegt:

http(s)://[ServerName]:[Port]/ibis/rest/rc/[NamedesInputListeners]

Passen Sie ggf. den Teil der URL hinter rc beliebig an. Für dynamische Pfad-Bestandteile können geschweifte Klammern verwendet werden, z.B. /users/{userName}/auftraege/{auftragsNr}.

Geben Sie * am Ende des Pfades ein, um Pfade zu unterstützen, die mit beliebigen Zeichen enden.

Authentifizierung erforderlich

Markieren Sie diese Option, wenn für den Zugriff auf die Ressource eine Authentifizierung erforderlich sein soll.

Statische Zugangsdaten verwenden

Definieren Sie hier ein zu verwendendes Verfahren und die für den Zugriff erforderlichen Authentifizierungsdaten.
- Verfahren
  - Basic: Es werden Benutzername und Passwort verlangt und unverschlüsselt übermittelt.
    
    Nur zu verwenden, wenn die Verbindung zwischen Client und Server als sicher betrachtet werden kann!
  - Digest: Verlangt ebenfalls Benutzername und Passwort. Das Passwort wird verschlüsselt übertragen. Für die Verschlüsselung werden mehrere Parameter verwendet, u.a. zufällig erzeugte Werte.
- Benutzername: Benutzername für die Authentifizierung.
- Passwort: Passwort für die Authentifizierung
Aus dem Credentials Manager auswählen

Für die Authentifizierung können Sie auch Zugangsdaten verwenden, die im Credentials Manager verwaltet werden. Siehe Credentials Manager für die Authentifizierung verwenden.
Prozessbenutzer verwenden

Diese Option ist nur bei einem installierten Portal verfügbar.

Wenn die Option aktiviert ist, ist der Zugriff auf die Ressource nur möglich, wenn gültige Portal-Benutzerdaten übergeben werden.

Als Authentifizierungsverfahren wird Basic verwendet.

Der in einem Aufruf verwendete Portal-Benutzername steht bei Workflow-Ausführung in der Variable restConnector.requestAuthUser zur Verfügung.

Siehe Modulvariablen>
Process Engine Benutzer verwenden (Passwort aus Portalkonfiguration)

Verwendung des internen Benutzers (INUBITISPortalUser@@@intern) und des Passworts für die Process Engine; zu finden in der INUBIT Workbench unter dem Register Konfiguration > Verwaltung > Server > Passwort für die Process Engine.

Weitere Informationen zur Verwendung des internen Benutzers über das FormProxyServlet siehe Zugriff auf einen REST-Input-Listener-Connector und siehe Zugriff auf einen gesicherten HTTP-Input-Listener-Connector.
Keycloak-Autorisierung für den REST Connector verwenden
- REST Listener
  
  Wenn ausgewählt, wird die Authentifizierung gegen den Keycloak-Ressourcenserver im REST Connector-Listener aktiviert. Dadurch kann sich der registrierte Client mit den ihm zugeordneten Benutzern gegen den Keycloak OIDC-Server authentifizieren.
  
  Um die notwendigen Informationen für die Keycloak-Authentifizierung hinzuzufügen, klicken Sie auf Konfigurationsdatei auswählen…, um den Dialog Auswahl der JSON Konfigurationsdatei zu öffnen. Vorausgesetzt, Sie haben diese Informationen in einer keycloak.json-Datei bereitgestellt, die im INUBIT-Repository gespeichert ist, können Sie diese JSON-Datei aus dem INUBIT-Repository laden, indem Sie auf die entsprechende Schaltfläche neben dem Eingabefeld Auswahl aus dem Repository klicken.
  
  Alternativ können Sie den Inhalt der Datei keycloak.json direkt kopieren und in den Textbereich Inhalt der JSON-Datei einfügen.
  
  Sobald der REST Connector-Listener ausgeführt wird, verwendet er die URL des Authentifizierungsservers und authentifiziert sich gegenüber dem Ressourcenserver. Das Textfeld ist für die Well known URL (https://<hostname>:<port>/auth/realms/<keycloak realm name>/.well-known/openid-configuration) vorgesehen, die für die Generierung des Tokens und die Authentifizierung anhand des Tokens verwendet wird. Sie ist für die Authentifizierung mit Anmeldeinformationen und Token erforderlich.
- REST-Aufrufer
  
  Mit dem REST Connector kann man den REST Listener oder REST-Ressourcen aufrufen, die mit Keycloak autorisiert sind. Um diese Aktivität durchzuführen, gibt es zwei Optionen.
  - Benutzername und Passwort verwenden: Um auf den REST Connector-Listener zuzugreifen, verwenden Sie die "Listener-URL", das Authentifizierungsverfahren "Basic" und den Benutzernamen und das Passwort von Keycloak auf der Seite Konfiguration der Anfrage. Auf dem Keycloak-Server würden beispielsweise der Benutzer "Keycloak_admin“ und die Benutzeranmeldeinformationen “test” erstellt. Hier müssen dieselben Anmeldeinformationen bereitgestellt werden (siehe untenstehendes Bild).
  - Autorisierungs-Token verwenden: Um auf den REST Connector-Listener über "Bearer Token" zuzugreifen, bearbeiten Sie die HTTP-Header auf der Seite Konfiguration der Anfrage. In den HTTP-Header geben Sie den Namen "x-openid-token" und den Wert des Zugriffs-Tokens an. (siehe untenstehendes Bild).
    
    Verwenden Sie diesen CURL-Befehl, um ein Token in Keycloak zu erzeugen:
    
    curl --request POST --url https://<keyclok-server>/auth/realms/<realm name>/protocol/openid-connect/token --header 'Content-Type: application/x-www-form-urlencoded' --data 'grant_type=password&client_id=<client-id>&client_secret=<client_secret>&username=<userName>&password=<password>'
    
    Kopieren Sie den Access Token aus der Ausgabe in den Wert des Header-Parameters "x-openid-token".
    
    Benutzername und Passwort sind für den Zugriff auf den REST Connector-Listener mit Autorisierungs-Token nicht erforderlich.

Unterstützte HTTP-Methoden

Hier legen Sie fest, dass der Konnektor nur auf bestimmte HTTP-Operationen reagiert.

Durch die Definition des Ressourcen-Typs haben Sie bereits automatisch zum jeweiligen Ressourcen-Typ passende HTTP-Methoden voreingestellt.

GET (Daten der Ressource abrufen)
POST (neue Ressource anlegen)
PUT (Ressource aktualisieren)
PATCH (Ressource ändern)
DELETE (Ressource löschen)

Siehe HTTP-Methoden im REST Connector verwenden

Aufbereitung empfangener Daten

Legen Sie die Kodierung für Daten fest, die als Request im Format multipart/form-data eingehen.
CORS verwenden

Wählen Sie diese Option, wenn Sie die CORS-Eigenschaften verwenden möchten. Um die Eigenschaften zu konfigurieren, klicken Sie auf Einstellungen… In dem sich öffnenden Dialog CORS Einstellungen können Sie die folgenden Einstellungen konfigurieren:
- Allowed origins (Zulässige Quell-Domänen)
  
  Geben Sie entweder eine einzelne Quelle-Domäne oder mehrere Quell-Domänen an. Damit wird den Browsern mitgeteilt, dass diese Quell-Domäne auf die Ressourcen zugreifen dürfen. Mehrere Quell-Domänen müssen durch Kommas ohne Leerzeichen getrennt werden. Um alle Quell-Domänen zuzulassen, geben Sie "*" an.
- Allowed methods (Zulässige Methoden)
  
  Wählen Sie die beim Zugriff auf die Ressource zulässigen Methoden aus oder heben Sie die Auswahl auf.
- Allowed headers (Zulässige Header)
  
  Geben Sie an, welche HTTP-Header bei der aktuellen Anfrage verwendet werden können.
- Allow credentials (Erlaube Anmeldeinformationen)
  
  Wählen Sie diese Option, um festzulegen, dass die aktuelle Anfrage mit Anmeldeinformationen durchgeführt werden kann.
- MaxAge (Maximales Alter)
  
  Geben Sie an, wie lange die Ergebnisse einer Preflight-Anfrage zwischengespeichert werden können.

Dialog Konfiguration der Antwort im REST Connector

(Input Listener Connector)

In diesem Dialog legen Sie die Einstellungen für die zuvor ausgewählten und von Ihrem Konnektor unterstützten HTTP-Methoden fest, die für eine Antwort genutzt werden.

Einstellungen für GET-Anfragen

Legen Sie hier fest, wie die Repräsentation der Antwort-Daten bei GET-Requests aussehen soll. Die Standard-Einstellungen sind bereits sinnvoll gewählt und können belassen werden.

Medien-Typ

Wählen Sie den gewünschten Medien-Typ aus.

Informationen zu MIME-Typen siehe https://de.wikipedia.org/wiki/Internet_Media_Type und siehe https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types.
Zeichensatz

Wählen Sie den Zeichensatz der Antwort-Daten aus.

Einstellungen für POST und PUT-Anfragen

Workflow asynchron starten

Aktivieren Sie diese Option, wenn der Input Listener nach dem Empfang des Request die HTTP-Statusmeldung direkt an den Client zurückliefern soll. In diesem Fall wird die Antwort vor dem Start des Workflows geschickt. Das Ergebnis des Workflows wird nicht zurückgegeben. Falls die Option nicht aktiviert ist, startet der Workflow synchron und die Antwort wird erst an den Client zurückgeschickt, nachdem das letzte Modul des Workflows ausgeführt wurde.

Antwort-Statuscode

Wählen Sie aus, was als Antwort-Statuscode empfangen werden soll.

Um im Fehlerfall in der Response anzuzeigen, dass die Anfrage-Daten fehlerhaft sind, kann die Variable restConnector.responseStatusCode für den Antwort-Statuscode auf den HTTP-Status-Code 400 (für Bad Request) gesetzt werden.

Allgemeine Einstellungen

Antwort-Daten automatisch kodieren

Aktivieren Sie diese Option, wenn die Antwort-Daten automatisch mit einer dem Server bekannten und vom Client unterstützten Methode kodiert werden sollen.
HTTP-Header bearbeiten

Der Button HTTP-Header bearbeiten öffnet den Dialog zum Bearbeiten der Header-Definition für die verfügbaren HTTP-Methoden.

Siehe Dialog Konfiguration der Anfrage

Dialog Konfiguration der Anfrage

(Medium und Output Connector)

Im Dialog zur Konfiguration der anzufragenden Ressource legen Sie die aufzurufende URL, die HTTP-Methode und evtl. eine Authentifizierung fest.

Basiskonfiguration

Aufzurufende URL

Geben Sie die URL der Ressource ein, an den der Connector seinen Request sendet, zum Beispiel Adresse eines HTTP Input Listeners.
- SSL
  
  Dient zum Konfigurieren der Server- bzw. Client-Authentifizierung.
  
  Siehe Dialog SSL-Konfiguration
Methode

Geben Sie hier die gewünschte HTTP-Methode an, mit der die Aktion, die auf die Ressource angewendet werden soll, definiert wird.

Siehe HTTP-Methoden im REST Connector verwenden
Redirects automatisch weiterverfolgen (nur für die GET-Methode)
- Wenn die Checkbox aktiviert ist, ruft der REST Connector die von der angefragten Applikation für die Weiterleitung bereitgestellte URL auf, wenn der HTTP-Statuscode 302 als Antwort auf einen GET-Request empfangen wurde.
  
  Die für die Weiterleitung konfigurierte URL wird aufgerufen, solange der HTTP-Statuscode 302 empfangen wird.
- Wenn die Checkbox aktiviert ist (Standard), schlägt der GET-Request fehl, wenn der HTTP-Statuscode 302 empfangen wird.

Authentifizierung verwenden

Markieren Sie diese Option, wenn der Server eine Authentifizierung fordert.

Folgende Zugangsdaten verwenden
- Verfahren
  - Basic: Es werden Benutzername und Passwort verlangt und unverschlüsselt übermittelt.
    
    Nur zu verwenden, wenn die Verbindung zwischen Client und Server als sicher betrachtet werden kann!
  - Digest: Verlangt ebenfalls Benutzername und Passwort. Das Passwort wird verschlüsselt übertragen. Für die Verschlüsselung werden mehrere Parameter verwendet, u.a. zufällig erzeugte Werte.
- Statische Zugangsdaten verwenden
  
  Geben Sie dann den Account ein, den der Connector für die Authentifizierung verwenden soll.
  - Benutzername: Benutzername für die Authentifizierung.
  - Passwort: Passwort für die Authentifizierung.
- Aus dem Credentials Manager auswählen
  
  Für die Authentifizierung können Sie auch Zugangsdaten verwenden, die im Credentials Manager verwaltet werden. Siehe Credentials Manager für die Authentifizierung verwenden.
Authentifizierung für Zugriff auf Process Engine verwenden

Verwendung des internen Benutzers (INUBITISPortalUser@@@intern) und des Passworts für die Process Engine, zu finden in der INUBIT Workbench unter dem Register Konfiguration > Verwaltung > Server > Passwort für die Process Engine.

Autorisierung

OAuth2-Autorisierung verwenden

Aktivieren Sie diese Option, um die OAuth2-Autorisierung zu verwenden

Wenn die Option OAuth2-Autorisierung verwenden ausgewählt ist, hat die OAuth2-Autorisierung Vorrang vor den Einstellungen im Bereich Authentifizierung verwenden.
Grant-Typ (Gewährungstyp)
- Client Credentials: Empfohlene Option für INUBIT, da keine Benutzerinteraktion erforderlich ist.
- Password Credentials
- Benutzerdefiniert: Wählen Sie diese Option, um andere Grant-Typen zu konfigurieren (z.B. Refresh Token Flow, Implicit Flow)
URL des Zugriffs-Tokens

Fügen Sie die URL des OAuth Servers ein. Zusätzlich können Sie festlegen, ob der HTTP-Zugriff via GET oder POST erfolgen soll.

Parameter

Jeden Grant-Typ erfordert die Angabe bestimmter Parameter. Welche das sind, entnehmen Sie der Dokumentation des verwendeten OAuth Servers.

Die Parametertabelle kann beliebig viele Einträge aufnehmen.

Alle im Modulassistenten konfigurierten Parameter sind als Moduleigenschaften mit dem Präfix OAUTH_PROPERTY für die Verwendung im Variablen-Mapping verfügbar.

Via Variablen-Mapping können nur Eigenschaften überschrieben werden, die vorher im Assistent gesetzt wurden. Sollen weitere Parameter via Variablen-Mapping gesetzt werden, müssen diese zuvor über den Modulassistenten in der Tabelle eingetragen werden (mit leerem oder Platzhalterwert).

Anfragedaten

Hier legen Sie die gewünschte Repräsentation der Anfragedaten fest.

Eingehenden Datenstrom als HTTP-Payload senden

Aktivieren Sie diese Checkbox, um die Eingangsnachricht als HTTP-Payload zu senden.

Diese Funktionalität kann optional verwendet werden, um anzugeben, ob die Eingangsnachricht als REST-Aufrufer- Nutzdaten für HTTP-Methoden wie GET und DELETE weitergeleitet werden soll.
MIME-Typ

Wählen Sie aus der Liste MIME-Typ einen Inhaltstyp aus oder tragen Sie den Inhaltstyp manuell ein und wählen Sie aus der Liste Kodierung einen Zeichensatz aus.

Für die HTTP-Methoden POST, PUT und PATCH wird der eingehende Datenstrom standardmäßig als HTTP-Payload gesendet.

Für die HTTP-Methoden GET, DELETE, OPTIONS und HEAD müssen Sie dafür die Option Eingehenden Datenstrom als HTTP-Payload senden markieren.

Wenn Sie einen benutzerdefinierten Begrenzungswert angeben (z.B. myownboundaryvalue), wird dieser beim Aufruf der REST-Anfrage berücksichtigt und nicht der automatisch generierte Wert. Verwenden Sie hierfür den MIME-Typ multipart/form-data; boundary=myownboundaryvalue.
Kodierung

Wählen Sie den Zeichensatz, den die Datei verwendet.
Als einzelne multipart/form-data Nachricht versenden

Aktivieren Sie diese Checkbox, um eine Eingangsnachricht als MIME-Daten zu senden und hochzuladen.

Ist diese Checkbox deaktiviert, muss die Eingangsnachricht als gültige MIME-Daten vorliegen.
Parametername für den Dateiinhalt (nur für den MIME-Typ multipart/form-data)

Geben Sie den Parameternamen für den Dateiinhalt an.

Dieser Parameter wird verwendet, um den Wert des Parameters name im Content-Disposition-Header zu setzen.

Der Content-Disposition-Header ist Teil des multipart/form-data-Body. Der Content-Disposition- Header wird verwendet, um Informationen für jeden Subpart der Form bereitzustellen. In erster Linie wird form-data verwendet, und der Header muss auch den Parameter name enthalten, damit das entsprechende Feld auf dem REST-Provider identifiziert/zugeordnet werden kann. Dieses Pflichtfeld muss durch den Benutzer angegeben werden.

Beispielvorlage
```
-----------------------------9051914041544843365972754266
Content-Disposition: form-data; name="file1"; filename="a.txt"
Content-Type: text/plain
Content of a.txt.
-----------------------------9051914041544843365972754266
```
Fälle

Es gibt zwei Fälle, den Wert für das Feld Parametername für den Dateiinhalt konfigurieren in Abhängigkeit davon, ob ein REST Connector-Listener oder ein externer REST-Endpunkt von einem INUBIT REST-Aufruf verwendet wird. Die folgende Beschreibung erläutert, wie das Feld Parametername für den Dateiinhalt in einem REST-Aufrufer konfiguriert werden muss.
- Wenn Sie einen Aufruf an einen INUBIT REST-Listener senden, können Sie im REST-Aufrufer für den Parameter name im Feld Parametername für den Dateiinhalt einen eigenen Wert setzen.
- Wenn der REST-Aufrufer eine Anfrage an einen externen REST-Endpunkt sendet, unterscheidet sich das Verfahren, weil diese Endpunkte durch das Eingeben des Parameters name so eingebunden werden müssen, dass dieser dem Content-Disposition-Body zugeordnet werden kann. Daher müssen Sie als Parametername für den Dateiinhalt denselben Wert eingeben, der vom Anbieter des externen REST-Endpunkts bereitgestellt wurde. Da dies ein allgemeiner Standard des Content-Disposition-Header ist, ist dieser Wert ein Pflichtparameter.
Eingangsnachricht verwenden (nur für den MIME-Typ multipart/form-data, wenn das Feld Parametername für den Dateiinhalt korrekt gesetzt ist)

Wählen Sie diese Option, um eine Datei aus der Eingangsnachricht am REST Connector als zu sendende Datei anzugeben. Geben Sie auch die korrekte Dateierweiterung an.
Datei-URL verwenden (nur für den MIME-Typ multipart/form-data, wenn das Feld Parametername für den Dateiinhalt korrekt gesetzt ist)

Wählen Sie diese Option, um die URL einer Datei im Server-Dateisystem einzugeben, damit diese hochgeladen werden kann.

HTTP-Header

Die Angaben im Request-Header informieren den Server, zum Beispiel über die Art und Konfiguration des Clients und die vom Client erwarteten bzw. unterstützten Dokumentformate. Hier legen Sie, zum Beispiel fest, in welcher Repräsentation man eine Liste mit angefragten Aufträgen erhalten will.

Der Button Header bearbeiten… öffnet einen Dialog. In dem Dialog können Sie den Request-Header durch Doppelklick auf die einzelnen Zeilen der Header-Liste definieren.

Die zulässigen Header sind in der HTTP-Spezifikation festgelegt, siehe https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.3.

Erweitert

Bei Fehlerantwort Fehler werfen

Per Default ist die Option Bei Fehlerantwort Fehler werfen aktiviert. Somit wird bei einer vom REST Connector empfangenen Fehlerantwort (HTTP-Statuscode 4xx oder 5xx) ein Workflow-Fehler ausgelöst.

Deaktivieren Sie die Option, um den Workflow nach einer Fehlerantwort normal fortzusetzen. Die Antwort-Daten erscheinen dann in dem MIME-Typ bzw. in den für den REST-Connector spezifischen Variablen.
Tatsächliche Fehlermeldung als Variable ISErrorString zurückgeben

Aktivieren Sie diese Option, damit die tatsächliche Fehlermeldung als Variable ISErrorString anstelle der INUBIT- eigenen Fehlermeldung zurückgegeben wird.

Test

Button Versand der Anfrage testen

Zum Prüfen, ob die Verbindung mit Ihren Angaben erfolgreich aufgebaut werden kann. Der Button öffnet einen Dialog, in dem die konfigurierte Verbindung getestet werden kann und eine Antwort mit Status-Code, HTTP-Header und Daten angezeigt wird.