Profil als SOAP-Webservice (dynamische Response)

Dieser Abschnitt erklärt, wie Sie ein Profil erstellen, das als SOAP-Webservice fungiert und eine dynamische Rückmeldung an den Client sendet, der den Webservice aufgerufen hat.

Importieren Sie bitte folgendes Profil und setzen Sie es auf aktiv: Profile-Profile_as_web_service_dynamic_response.pak

Phase 1


Öffnen Sie das Profil und wechseln Sie zu Phase 1. Dort sehen Sie den event-gesteuerten Eingangsagenten des Typs "HTTP".


images/download/attachments/159865835/1882-version-2-modificationdate-1718007680549-api-v2.png images/download/attachments/159865835/1885-version-3-modificationdate-1718007697593-api-v2.png


(1) Gibt an, unter welcher URL Ihr Webservice erreichbar ist. Hier also https://<URL/IP Integration Server>/dw/Request/addition_web_service

(2) Verwenden Sie die Option POST.

(3) Muss gesetzt sein.

(4) Verwenden Sie diesen Wert. Dies hat den Effekt, dass die WSDL-Datei auf Basis der Quell- und Zielstruktur erzeugt wird. Zudem wird die Response dann dynamisch erzeugt, aufgrund der Daten des Zielbaum (mehr dazu später) . Mehr Details im Abschnitt WSDL-Datei.

(5) Dieser Option muss gesetzt werden, damit wir aus dem Zielbaum die Response für den Webservice erzeugen können (mehr dazu später).

Phase 2


Die Dokumentenart muss hier XML sein (wird gesetzt in den Basis-Daten), da wir ja eingehende SOAP-XML Nachrichten verarbeiten wollen.


images/download/attachments/159865835/1883-version-3-modificationdate-1718007720222-api-v2.png


(6) Setzen Sie diese Checkbox.

(7) Notwendig für das Parsen der empfangenen XML-Datei in die Quellstruktur. Siehe Abschnitt "Phase 3" unten.

(8) Verwenden Sie den Wert V3. Hinweis: Es kann auch der XML-Parser V4 verwendet werden, aber das ist nicht notwendig.

Phase 3


Wechseln Sie nun zu Phase 3. Wir möchten einen einfachen Taschenrechner-Webservice erstellen, der uns zwei Zahlen addiert und in der Response das Ergebnis liefert.

Dazu benötigen wir zuerst eine XML-Quellstruktur, die im Knoten Add, siehe auch (7), die zwei zu addierenden Zahlen aufnimmt in den Feldern intA und intB. Hinweis: Beachten Sie die Satzarterkennungen der Felder und Knoten, die für XML-Quellstrukturen benötigt werden.


images/download/attachments/159865835/1884-version-3-modificationdate-1701161442510-api-v2.png


In der Zielstruktur legen wir lediglich den Knoten AddResult an mit dem Feld result, auf dem wir mit einer Funktion die Addition der Werte der Quellstruktur-Felder intA und intB durchführen.

Integration Unit



Wählen Sie die XMLNoTemplateUnit aus und tragen Sie bitte beim Parameter " Root node name" den Wert AddResult ein. Alle anderen Parameter können Sie ignorieren.


Antwortweg


Fügen Sie einen Antwortweg des Typs "Eigene Klasse" mit Klasse "DefaultWebServiceResponse" ein, stellen Sie den Inhalt auf "Ausgabe von IU".

Dieser Antwortweg liefert die XML-Response des Webservices. Siehe Punkte (4) und (5), Zielstruktur und Integration Unit.

Hinweis: Die Response hat das Encoding "UTF-8".

WSDL-Datei


Nun können wir uns die WSDL-Datei des Webservices anzeigen lassen. Die WSDL-Datei wird automatisch erstellt.

Geben Sie dazu im Browser die folgende URL ein. Das ist die selbe URL, die für den Aufruf des Webservices verwendet wird (1), aber am Ende wird noch das Suffix "?wsdl" angehängt.


https://<URL/IP Integration Server>/dw/Request/addition_web_service?wsdl


Folgend finden Sie weitere Informationen zur WSDL-Datei, die Sie aber vorerst ignorieren können.

Knoten und Felder bei WSDL-Erzeugung aus Quellstruktur ignorieren

Wenn bestimmte Knoten oder Felder bei der automatischen Erzeugung der WSDL-Datei aus der Quellstruktur ignoriert werden sollen, können Sie das erreichen indem Sie den Wert _exclude_ in der Knoten bzw. Feld-Eigenschaft "DataCockpit/Portal Steuerung" angeben.

Service-Namen in der WSDL-Datei vorgeben


images/download/attachments/159865835/832-version-1-modificationdate-1701226761075-api-v2.png


Per Default wird der Servicename in der WSDL-Datei immer ProfileService genannt. Möchten Sie den Namen selbst bestimmen, können Sie hierzu in den Feldern für Strukturnamen (siehe Screenshot) den Namen vorgeben. In diesem Fall muss der Strukturname mit Service: beginnen. Hier also Service:MyServiceIn und Service:MyServiceOut.

Art der WSDL-Erzeugung


Wird in (4) der Wert Nur den Job-Status melden verwendet, wird die WSDL-Datei nur auf Basis der Quellstruktur erstellt. Zudem ist die Response des Webservices dann "statisch", d. h. sie enthält nur die Job-Nummer des durch den Webservice-Aufruf gestarteten Profils und bezieht keine Daten aus dem Zielbaum.

Wird in (4) der Wert WSDL auf Basis des Zielbaums verwendet, wird die WSDL-Datei auf Basis der Quell- und der Ziel-Struktur erstellt. Zudem wird die Response dann dynamisch erzeugt, aufgrund der Daten des Zielbaum. Details dazu finden Sie im Abschnitt Profil als SOAP-Webservice (dynamische Response). Für die Erzeugung der Elementdefinition wird folgendermaßen vorgegangen.

Er wird der Name des Feldes/Knoten in der Zielstruktur (ohne _val oder _attr) oder die Beschreibung des Feldes/Knoten genommen, wenn diese vorhanden ist. Dadurch ist es möglich Elemente mit gleichen Namen innerhalb der Definition zu verwenden, was in der Zielstruktur nicht möglich ist. Steht in der Beschreibung eines Knotens die Zeichenkette _exclude_, dann wird dieser Knoten in der WSDL-Erzeugung übersprungen.

Eindeutige Root-Elementnamen verwenden


Bei der Erzeugung der WSDL-Datei auf Basis der Zielstruktur wird davon ausgegangen, dass die XML-Root-Elemente in der erzeugten Request- und Response-Struktur eindeutig sind. Die XML-Namen werden in der Quellstruktur aus den Satzartkennungen der Knoten/Felder und in der Zielstruktur aus den Namen der Knoten und Felder, bzw. den in der Feldbeschreibung definierten Knotennamen generiert. Deshalb sollten die Root-Knoten von Quell- und Zielstruktur nicht gleich sein. Falls gleiche Namen unvermeidbar sind, kann die dynamische WSDL-Erzeugung nicht verwendet werden. Dann kann nur die Bereitstellung der WSDL-Datei, wie im Abschnitt Statische WSDL-Erzeugung beschrieben, angewendet werden. Diese WSDL-Datei muss in der Regel manuell erzeugt bzw. nachbearbeitet werden.

Statische WSDL-Erzeugung


Alternativ zur dynamischen Erzeugung der WSDL-Datei kann man unter ./conf/wsdl/<URL-Adressen-Suffix>.wsdl die WSDL-Datei hinterlegen. Das Zeichen / muss dann im Dateinamen durch ein _ ersetzt werden. Die Datei wird unter diesem Pfadnamen gesucht und anstelle der dynamischen WSDL-Erzeugung verwendet, wenn die Datei gefunden wird, lesbar ist und nicht leer. In der Datei kann man den Bereich der Rückantwort, der bei WSDL-Anfragen mit eingebettet wird, entsprechend anpassen.

Request-Header


Request-Header können ausgelesen werden mit den System-Variablen MSG_CALL_HEADER_HTTP_<Name des Headers in Großbuchstaben>. Hinweis: Die System-Variable MSG_CALL_HEADER_HTTP_AUTHORIZATION (Header Authorization) wird per Default nicht gesetzt. Mit der System-Property hub.datawizard.http.copy.allHeader=true können Sie ein Setzen dieser Variable aber erzwingen.

Weitere System-Variablen: MSG_CALL_HEADER_HTTP_METHOD, MSG_CALL_HEADER_HTTP_PROTOCOL, MSG_CALL_HEADER_HTTP_REMOTE_HOST, MSG_CALL_HEADER_HTTP_URI, MSG_CALL_HTTP_AUTH_USER.

Response-Header


Sind System-Variablen der Form VAR_RESPONSE_HTTP_HEADER_<Name des Response-Headers> angelegt, dann werden entsprechende Response-Header mit den Werten der Variablen gesetzt. Beispiel: Die Variable VAR_RESPONSE_HTTP_HEADER_Test mit dem Initialwert mytest erzeugt den HTTP-Response-Header Test mit dem Wert mytest. Hinweis: Der Response-Header Content-Length wird ignoriert, d. h. er kann nicht überschrieben werden.

Webservice aufrufen


Wie man einen solchen Webservice aufruft, werden wir zeigen in den Abschnitten Mit Profil SOAP-Webservice aufrufen im Eingangsagenten, Mit Profil SOAP-Webservice aufrufen in Funktion und Mit Profil SOAP-Webservice aufrufen in Antwortweg.