Inhaltsverzeichnis WsPortal Nachrichten Einführung Was ist das WsPortal? Was sind WsPortal-Nachrichten? Wie sieht der Nachrichtenrahmen aus? Wie wird eine Nachricht in einen SOAP-Request verpackt? Nachrichten verschicken Wohin werden Nachrichten verschickt? Test-System Produktions-System URL Wie wird eine Nachricht an DSB verschickt? Was ist beim Erstellen der Nachrichten zu beachten? Welche Codierung muss verwendet werden? Datentypen Durchgängiges Beispiel Beschreibung Voraussetzungen User Account für das WS-Portal Freischaltung WSDL-Datei des Gateway Dienstes Nachrichten Anfrage Antwort HTTP HTTP Trace der Anfrage HTTP Trace der Antwort Der Fehlerfall: SOAP Faults Was passiert, wenn ein Fehler auftritt? Beispiel HTTP Trace Offline Zugang Anhang Übersicht der Standardelemente message header body client service-provider avs3-sales-organization avs3-service-provider Referenz der SOAP-Header Elemente service-object service-method service-version WSDL-Datei des WsPortal Gateways WsPortal Nachrichten Einführung Was ist das WsPortal? Eine der zentralen Herausforderungen der IT-Technologie im 21. Jahrhundert ist die Integration von unterschiedlichsten Anwendungen (EAI). Beschränkte sich diese Integration in der Vergangenheit hauptsächlich auf heterogene Anwendungen innerhalb eines Unternehmens, erweiterte sich mit der Verbreitung des Internet diese Integration auch auf Anwendungen der Geschäftspartner eines Unternehmens. Anwendungen, die Prozesse mit Kunden und Lieferanten unterstützen müssen ebenfalls nahtlos in eigenen Anwendungen integriert werden. Um die Integration von Anwendungen sprach-, plattform- und systemübergreifend durchführen zu können, hat sich in den vergangenen Jahren das Konzept der Web-Services durchgesetzt. Viel wurde bereits über Web-Services geschrieben und es soll nicht Aufgabe dieses Dokumentes sein zu erklären wie Web-Services funktionieren. Es sei lediglich erwähnt, dass Web-Services im Grunde nur Dienste darstellen, um ein System aus lose gekoppelten Komponenten zu erstellen. Auch die dsb ccb solutions GmbH nutzt diese Technologie um IT-Systeme ihrer Geschäftspartner online an die Systeme im Rechenzentrum der dsb anzubinden. Die verschiedenen Dienste, die von dem Back-Office-System zur Verfügung gestellt werden, sind nicht direkt über das Internet verfügbar. Vielmehr gibt es ein Portal für Web-Services, das WsPortal. Über dieses Gateway werden alle Anfragen von Geschäftspartnern entgegengenommen, authentifiziert und an die entsprechenden Zielsysteme weitergeleitet. Wie nun mit dem Gateway kommuniziert wird und wie die Nachrichten, die an dieses Gateway geschickt werden aufgebaut sein müssen, wird im folgenden Dokument erläutert. Was sind WsPortal-Nachrichten? Bei der Bereitstellung von Web-Services haben sich in der Hauptsache zwei Nutzungsarten etabliert. Diese sind: Einfache RPC Dienste Dokumenten-zentrische Dienste Bei den einfachen RPC Diensten werden lediglich die Methoden von Objekten per Web-Service zur Verfügung gestellt. Bei den dokumenten-zentrischen Diensten werden XML-Dokumente innerhalb eines SOAP-Bodys versendet. Diese Dokumente werden lediglich vom Empfänger einer Nachricht verarbeitet und nicht von evtl. im Nachrichtenpfad eingeklinkten sogenannten SOAP-Intermediaries. Bei der dsb ccb solutions GmbH & Co.KG wird das Beste aus beiden Welten kombiniert. Im Grunde sind alle Dienste der dsb einfache RPC Dienste. Über diese Dienste werden aber ausschließlich XML-Dokumente versendet und keine primitiven Datentypen. Dies hat verschiedene Vorteile: Da in der Regel umfangreiche Daten gesendet werden, wie zum Beispiel Bestellungen, Kundenstammblätter usw., können mit diesem Ansatz sehr komplexe Strukturen abgebildet werden. Bestehende Strukturen können flexibel erweitert werden. Es können standardisierte Verfahren zum Test der XML-Dokumente (wohlgeformt, gültig) eingesetzt werden. Einfach zu implementieren. Die versendeten XML-Dokumente haben alle ein standardisiertes Rahmenwerk und tragen die eigentliche Nutzlast innerhalb eines speziellen Bereiches dieses Nachrichtenrahmens. Der zusätzliche Nachrichtenrahmen bietet den Vorteil, auch Metadaten zur eigentlichen Nutzlast versenden zu können. Damit bleiben Spezifikationen für allgemeine Typen (z. B. Bestellungen, Rechnung, …) unabhängig von bestimmten Back-Office Systemen. Wie sieht der Nachrichtenrahmen aus? Der Nachrichtenrahmen ist die Basis einer jeden Anfrage, die an einen Web-Service gesendet wird. Er ist ähnlich wie eine SOAP-Nachricht aufgebaut. Der folgende Auszug zeigt einen leeren Rahmen. Message für VHS-Service <message version="1.0" system="vhs/3"> <header> <client></client> <!-- Pflichtfeld --> <service-provider></service-provider> <!-- Pflichtfeld --> <service-object></service-object> <service-method></service-method> <service-version></service-version> ... Weitere Header Felder ... </header> <body> ... Eigentliche Nutzlast ... </body> </message> Message für AVS-Service <message version="1.0" system="avs/3"> <header> <client></client>// Pflichtfeld <avs3-sales-organization></avs3-sales-organization> <!-- Pflichtfeld 1 ... n --> <avs3-service-provider></avs3-service-provider> <!-- Pflichtfeld --> <service-object></service-object> <service-method></service-method> <service-version></service-version> ... Weitere Header Felder ... </header> <body> ... Eigentliche Nutzlast ... </body> </message> Eine Referenz auf eine Schema-Dateien braucht nicht mitgegeben werden. Das Root-Element einer jeden Nachricht ist das Element “message”. Dieses verfügt über die zwei Attribute „version“ und „system“. Die Version kennzeichnet die Version der Spezifikation dieser Nachricht und „system“ gibt an, für welches System die Nachricht bestimmt ist, bzw. welches System die Antwort generiert hat. Der Header ist für Metainfomationen bestimmt, die zwar das Zielsystem benötigt, aber unabhängig von der versendeten Nutzlast ist. Im Header müssen immer die Elemente Mandant (client) und Dienstleister-Kennung (service-provider) gefüllt werden, welche den Zielmandanten und den Dienstleister im Zielsystem kennzeichnen. Weitere Elemente können optional und je nach Anwendungsfall ergänzt werden. Die eigentliche Nutzlast wird innerhalb der body Elemente verpackt. Hier können beliebig viele Elemente in beliebiger Schachtelung abgelegt werden. Es müssen sich lediglich Quell- und Zielsystem über den Aufbau einig sein. Nachrichten werden sowohl bei Anfragen als auch bei den entsprechenden Anworten verwendet. Einzige Ausnahme ist, wenn ein Fehler auftritt. In diesem Fall werden die Fehlerinformationen über die SOAP-Faults zurückgeliefert. Wie wird eine Nachricht in einen SOAP-Request verpackt? Das im vorigen Abschnitt beschriebene Nachrichten-Dokument wird nun über einen SOAP-RPC versendet. Hierbei ist das Dokument der einzige String-Parameter einer Methode des Zielobjektes. Ein SOAP Request an eine Ping Methode hätte dann den folgenden Aufbau: ... <soap:Body> <n:forwardMessage xmlns:n='http://tempuri.org/net.dsb.wsportal.router.RequestHandler'> <dsbMessage xsi:type='xsd:string'> <?xml version="1.0" encoding="ISO-8859-1"?> <message version="1.0" system="vhs/3"><header><client> 4711</client></header><body><echo>The String to echo!</echo></body></message> </dsbMessage> </n:forwardMessage> </soap:Body> ... Hier sieht man sehr deutlich, wie die Nachricht innerhalb der SOAP-Nachricht im Body verpackt wird. Wichtiger Hinweis: Das Escaping der zu versendenden XML-Nachricht (im o. a. Fall der Ping Request) muss im Normalfall nicht manuell durchgeführt werden. Es ist vielmehr so, dass im Grunde jedes SOAP-Framework, das wir kennen dieses automatisch beim Versenden einer Nachricht durchführt. Daher ist darauf zu achten, dass kein doppeltes Escaping stattfindet. Nachrichten verschicken Wohin werden Nachrichten verschickt? Alle Nachrichten von extern werden an das WsPortal-Gateway der dsb ccb solutions GmbH & Co. KG geschickt. Dieses steht sowohl als Test- als auch als Produktions-System zur Verfügung. Technisch gesehen lauscht auf beiden Systemen ein Gateway, das die Anfragen entgegen nimmt und intern weiterleitet. Die URL unterscheidet sich, je nach Art der Client Authentifizierung. Test-System Basis-URL (IP Whitelisting): https://wsportal-tst.dsb.net Basis-URL (Client-Zertifikat): https://wsportal-cca-tst.dsb.net Produktions-System Basis-URL (IP Whitelisting): https://wsportal-prd.dsb.net Basis-URL (Client-Zertifikat): https://wsportal-cca.dsb.net URL URL der Gateway WSDL: /net/dsb/wsportal/router/RequestHandler.wsdl SOAP-Service Endpoint: /net/dsb/wsportal/router/RequestHandler REST-Service Endpoint: /rest Das Gateway authentifiziert alle Anfragen mittels der HTTP-BASIC Methode. Diese Informationen müssen also im HTTP-Header bei der Anfrage mitgeliefert werden. Wie wird eine Nachricht an DSB verschickt? Das Service-Objekt RequestHandler hat eine Methode mit dem Namen „forwardMessage“. Der einzige Parameter dieser Methode ist die XML-Nachricht als String. Die XML-Nachricht muss den dsb Spezifikationen, die ebenfalls in diesem Dokument beschrieben sind, entsprechen. Am einfachsten ist es, sich ein Proxy-Objekt mit Hilfe der oben genannten WSDL-Datei zu generieren und dieses dann zu verwenden. Der Aufbau und der Inhalt einer XML-Nachricht kann der eigentlichen Schnittstellenbeschreibung für einen bestimmten Web-Service entnommen werden. Was ist beim Erstellen der Nachrichten zu beachten? Da das WsPortal-Gateway als sogenannter Intermediary fungiert, müssen ihm Informationen vom Web-Service Client zur Verfügung gestellt werden, an welchen Dienst der Client seine Anfrage senden möchte. Dies erledigt ein Client, indem er diese Informationen in den Header der SOAP-Nachricht packt. In den Header der SOAP-Nachricht (nicht zu verwechseln mit dem Header der dsb spezifischen Nachricht) müssen die entsprechenden Elemente zur Spezifikation des „service-object“, „service-method“ und „service-version“ aufgenommen werden. Wie diese für einen bestimmten Dienst lauten, kann der eigentlichen Schnittstellenbeschreibung für einen bestimmten Web-Service entnommen werden. Alternativ dazu können die Routing-Informationen auch im Header der eigentlichen Nachricht übergeben werden. Diese Möglichkeit ist dann vorzuziehen, wenn das verwendete Client-Framework nur eine unzureichende Unterstützung für das Handling von SOAP-Headern bietet. Bitte beachten Sie aber, dass diese Alternative eine schlechtere Performance besitzt, da die eigentliche Nachricht vor dem Routing komplett analysiert werden muss. Der Header der Nachrichtenrahmen sieht in diese Fall folgendermaßen aus (vgl. hierzu auch Abschnitt 2.3) <?xml version="1.0" encoding="ISO-8859-1"?> <message version="1.0" system="vhs/3"> <header> <client></client> <service-provider></service-provider> <service-object></service-object> <service-method></service-method> <service-version></service-version> </header> <body> ... Eigentliche Nutzlast ... </body> </message> Welche Codierung muss verwendet werden? Für alle XML-Dokumente (Nachrichten) sollte das Encoding ISO-8859-1 oder UTF-8 verwendet werden. Standard ist UTF-8. Soll eine andere Zeichenkodierung verwendet werden, so ist das am Beginn der XML-Nachricht anzugeben: <?xml version=„1.0“ encoding=„UTF-8“?> Da nun aber SOAP selbst ebenfalls auf XML-basiert, müssen Zeichen, die in XML eine besondere Bedeutung besitzen, entsprechend escaped werden. Laut XML-Spezifikation sind die „Sonderzeichen“ <, > und & zu escapen. Dies kann sowohl mit den numerischen als mit den alphanumerischen Entities geschehen. ZeichenEntitynumerisch <<< >&gz;> &&& Weitere Informationen hierzu findet man unter http://www.w3.org/TR/1998/REC-xml-19980210.html Datentypen TypBeispiel Dezimalzahl 34.2 Boolean true Datum 2021-10-14 Zeitpunkt 2021-10-14T12:34:27+02:00 Durchgängiges Beispiel Beschreibung Die folgenden Abschnitte zeigen anhand eines durchgängigen Beispiels wie mit den Web-Services der dsb ccb solutions GmbH & Co. KG Daten ausgetauscht werden. Das Beispiel zeigt die Anbindung des Ping-Service. Dieser Dienst macht nichts anderes als einen gesendeten String unverändert wieder an den Aufrufer zurückzusenden. Mit Hilfe dieser einfachen Methode kann die komplette Kommunikationskette sehr einfach getestet werden. Voraussetzungen Um den Ping-Service ansprechen zu können, müssen verschiedene Voraussetzungen erfüllt sein. User Account für das WS-Portal Sie müssen über einen gültigen Account zum WsPortal der dsb verfügen. Bitte wenden Sie sich hierzu an Ihren zuständigen Ansprechpartner aus der Kundenbetreuung. Er wird Ihnen dann die gewünschten Informationen beschaffen. Freischaltung Der Account muss für den Zugriff auf die Services freigeschaltet werden. Dies kann auf zwei Arten erfolgen. Eintrag in der WS-Portal IP-ACL Die IP-Adressen, von denen die Request abgesendet werden, werden in die IP - Access Control List (ACL) bei DSB aufgenommen werden. Bitte teilen Sie die von Ihnen verwendeten IP Adressen Ihrem Ansprechpartner bei dsb mit. Verwendung eines Client-Zertifikats Beim Zugriff wird ein Client-Zertifikat mitgegeben. Dies ist insbesonders dann sinnvoll und notwendig, wenn die verwendete IP Adresse des Clients nicht fix ist. Soll dieser Weg genutzt werden, fordern Sie ein Client-Zertifikat bei Ihrem dsb Ansprechpartner an. WSDL-Datei des Gateway Dienstes Alle Informationen zum Aufruf des Dienstes finden Sie in der beschreibenden WSDL Datei. Diese finden Sie unter https://wsportal-prd.dsb.net/net/dsb/wsportal/router/RequestHandler.wsdl. Viele Bibliotheken bieten Tools an, um aus dieser Beschreibung Proxy-Klassen zu bilden, die dann einen einfachen Aufruf gestatten. Nachrichten Daten werden wie bereits beschrieben über Nachrichten ausgetauscht. Die folgenden beiden Abschnitte zeigen, wie diese Nachrichten für den Ping-Service aussehen. Anfrage Dies ist eine beispielhafte Nachricht, die an den Ping-Service gesendet werden kann. Die Werte für die Mandanten-Nr. (client) und die Dienstleister-Kennung müssen natürlich durch Ihre eigenen Werte ersetzt werden. Bitte beachten Sie, dass in dem folgenden Beispiel die Routing-Informationen im Nachrichten Header (message) und nicht im SOAP-Header übergeben werden. <message version="1.0" system="vhs/3"> <header> <client>4711</client> <service-provider>123</service-provider> <service-object>/net/dsb/vhs3/ServiceInfo</service-object> <service-method>ping</service-method> <service-version>1.0.0</service-version> </header> <body> <echo>Please echo me!</echo> </body> </message> Antwort Dies ist die Antwort, die der Ping-Service auf die obige Anfrage zurücksendet. <message version="1.0" system="vhs/3"> <header> <client>4711</client> <service-provider>123</service-provider> </header> <body> <echo>Please echo me!</echo> </body> </message> HTTP Wie das ganze im Kontext einer HTTP-Nachricht aussieht und was dabei über die Leitung gesendet wird, zeigen die folgenden beiden Traces. Beide sind optisch ein wenig aufbereitet, um die einzelnen Bestandteile besser erkennen zu können. In der Anfrage ist zu erkennen, wie der Client über den SOAP-Header das gewünschte Zielsystem adressiert. In der Antwort ist diese Information natürlich nicht mehr vorhanden. Der Body der SOAP-Nachricht trägt die eigentliche Nutzlast in Form einer dsb spezifischen Nachricht. Diese Nachricht, die ja ebenfalls ein XML-Dokument darstellt, muss entsprechend kodiert werden. Dies geschieht ganz einfach durch escapen der entsprechenden XML-spezifischen Zeichen (>,< und &). Die im XML verwendete Zeichenkodierung muss am Beginn des Dokuments angegeben werden: <?xml version='1.0' encoding='UTF-8'?> oder <?xml version='1.0' encoding='ISO-8859-1'?> UTF-8 ist der Default. Bei Verwendung von UTF-8 kann die Zeile entfallen. Es wird jedoch empfohlen, die Kodierung immer mit anzugeben. Die Angabe der Kodierung im HTTP-Header Content-Type spielt hierfür keine Rolle. Im Response ist der HTTP-Header X-Request-Id enthalten. Dieser identifiziert den Request in den dsb Logs. Daher sollte diese ID vom Client geloggt werden, um bei Problemen die Nachforschung zu erleichtern. HTTP Trace der Anfrage POST /net/dsb/wsportal/router/RequestHandler HTTP/1.1 Host: wsportal.dsb.net:443 User-Agent: WsPortal-Client Connection: Keep-Alive SOAPAction: "forwardMessage" Content-Type: text/xml; charset=UTF-8 Content-Length: 994 Authorization: Basic ZHNvbmspbemU6Y2hhbmdlbWUj <?xml version='1.0' encoding='UTF-8'?> <soap:Envelope xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns:soapenc='http://schemas.xmlsoap.org/soap/encoding/' soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <soap:Header> <service-object soap:actor="/net/dsb/wsportal/router/RequestHandler" soap:mustUnderstand="1">/net/dsb/vhs3/ServiceInfo</service-object> <service-method soap:actor="/net/dsb/wsportal/router/RequestHandler" soap:mustUnderstand="1">ping</service-method> </soap:Header> <soap:Body> <n:forwardMessage xmlns:n='http://tempuri.org/net.dsb.wsportal.router.RequestHandler'> <dsbMessage xsi:type='xsd:string'> <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE message SYSTEM "service-info-ping.dtd"> <message version="1.0" system="vhs/3"><header><client> 4711</client></header><body><echo>The String to echo!</echo></body></message> </dsbMessage> </n:forwardMessage> </soap:Body> </soap:Envelope> HTTP Trace der Antwort HTTP/1.0 200 OK Optimizable: true Date: Tue, 03 Sep 2002 09:14:17 GMT Content-Type: text/xml; charset=UTF-8 Server: WsPortal-Gateway Content-Length: 838 X-Request-Id: f5fd6424784d16fca377cf93ccdef54a <?xml version='1.0' encoding='UTF-8'?> <soap:Envelope xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns:soapenc='http://schemas.xmlsoap.org/soap/encoding/' soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <soap:Body> <n:forwardMessageResponse xmlns:n='http://tempuri.org/net.dsb.wsportal.router.RequestHandler'> <Result xsi:type='xsd:string'> <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE message> <message version="1.0" system="vhs3"><header><client> 4711</client></header><body><echo>The String to echo!</echo></body></message> </Result> </n:forwardMessageResponse> </soap:Body> </soap:Envelope> Der Fehlerfall: SOAP Faults Was passiert, wenn ein Fehler auftritt? Falls bei der Bearbeitung einer Anfrage ein Fehler auftritt, wird entsprechend dem SOAP Standard ein SOAP-Fault erzeugt. Dies geschieht aber nur unter den Bedingungen, dass es sich tatsächlich um einen „richtigen“ Fehler handelt. Falls Sie beispielsweise die Daten eines Geschäftspartner abfragen möchten und der gesuchte Geschäftspartner nicht existiert, wird lediglich eine leere Antwort zurückgeliefert, aber es tritt kein Fehler auf und somit wird auch kein SOAP-Fault generiert. Ein SOAP-Fault besteht aus verschiedenen Attributen, die Rückschlüsse auf das aufgetretene Problem erlauben. Bei der dsb GmbH & Co.KG werden die einzelnen Bestandteile folgendermaßen gefüllt. Faultcode Enthält „Server“ oder „Client“, je nachdem wer für den Fehler verantwortlich ist. Faultstring Enthält einen Fehlertext welcher den aufgetretenen Fehler beschreibt. Der Text hat dabei folgenden Aufbau: [<Fehler ID>] <Fehler Text> Faultactor Der Faultactor kennzeichnet das Modul bzw. das System, in dem der Fehler bemerkt wurde bzw. aufgetreten ist. Faultdetail Hierunter befindet sich eine XML-Struktur, die Details zum aufgetretenen Fehler enthält. Beispiel Das folgende Beispiel zeigt was passiert, wenn eine Anfrage an die Methode „getBpData“ des Objekts „Bp“ gestellt wird, die eine Prüfung durch die entsprechende Schema Datei nicht besteht. Faultcode Client Da die Anfrage fehlerhaft war, ist der Client für diesen Fehler verantwortlich. Faultstring [10000] Error on line 2 of document : Element type „bp-numbe“ must be declared. Fehlertext bestehend aus Error-ID und Error Text. Faultactor /net/dsb/vhs3/Bp Der Fehler ist im Modul Bp (Geschäftspartner) aufgetreten bzw. bemerkt worden. Faultdetail <detail> <message version='1.0' system='vhs/3'> <header> <client/> </header> <body> <timestamp>2003-06-16 17:13:08</timestamp> <code>10000<//code> <description>Error on line 2 of document : Element type "bp-numbe" must be declared.</description> <extension></extension> </body> </message> </detail> Das Root Element muss laut SOAP-Standard den Namen „detail“ haben. Hierunter befindet sich eine „normale“ dsb Message, die je nach aufgetretenem Fehler weitere Informationen enthält. HTTP Trace Die folgenden Zeilen enthalten einen HTTP Trace eine SOAP Faults. <?xml version='1.0' encoding='UTF-8'?> <soap:Envelope\ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns:soapenc='http://schemas.xmlsoap.org/soap/encoding/' soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <soap:Body> <soap:Fault> <faultcode>soap:Client</faultcode> <faultstring>[10000] Error on line 2 of document : Element type "bp-numbe" must be declared.</faultstring> <faultactor>/net/dsb/vhs3/Bp</faultactor> <detail> <message version='1.0' system='vhs/3'> <header> <client></client> </header> <body> <timestamp>2003-06-16 17:37:03</timestamp> <code>10000<//code> <description>Error on line 2 of document : Element type "bp-numbe" must be declared.</description> </body> </message> </detail> </soap:Fault> </soap:Body> </soap:Envelope> Offline Zugang Normalerweise ist der Online Zugang über Web Services der bevorzugte Weg, um Daten mit der dsb GmbH & Co.KG auszutauschen. In Ausnahmefällen ist aber auch ein offline Datenaustausch möglich. Dies ist z. B. dann der Fall, wenn nur neue Bestellungen übertragen werden, aber keine Informationen zurückfließen müssen und die Einspielung der Daten nicht sehr zeitnah erfolgen muss. Diese Art des Datenaustauschs gestaltet sich dann folgendermaßen: Die Daten werden per FTP von Ihnen bereitgestellt. Hierzu wird auf dem FTP Server der dsb ein dedizierter Account eingerichtet. In das Verzeichnis /an_dsb werden die Dateien abgestellt. Auf unserer Seite wird in regelmäßigen Abständen geprüft, ob neue Dateien vorhanden sind. Falls ja, werden diese ausgelesen und in Aufrufe an den online WebService umgewandelt. Im Prinzip so, als wären die Aufrufe direkt online durchgeführt worden. Nach der Verarbeitung wird ein Verarbeitungsprotokoll an den Sender der Datei per eMail gesendet. Der Aufbau der per FTP übertragenen Dateien entspricht im Grunde einer online Anfrage per WebService. Die Daten müssen ebenfalls als XML vorliegen und in den Nachrichtenrahmen verpackt werden. Näheres finden Sie im Abschnitt Batch Schnittstelle. Anhang Übersicht der Standardelemente message <message> ... </message> Umschließt eine dsb spezifische Nachricht und bildet somit das Wurzelement. Als Kindelemente sind nur „header“ und „body“ zugelassen. Attribute version Kennzeichnet die Version der Nachrichtenspezifikation system Gibt das Backoffice-System an, für das diese Nachricht bestimmt ist, bzw. von dem die Antwort generiert wurde. Derzeit gibt es die Werte avs/3, vhs/3 und zhs/3. header <header> ... </header> Bildet den Header einer dsb spezifischen Nachricht und umschließt alle Element mit Metainformationen. body <body> ... </body> Bildet den Body einer dsb spezifischen Nachricht und umschließt die eigentliche Nutzlast. Alle Elemente, die Nutzlast tragen, sind Kindelement des Bodys, wobei natürlich geschachtelt werden kann. client <client> ... </client> Identifiziert den Mandanten einer Nachricht. Dieses Element ist eine Metainformation des Headers, die immer gesendet werden muss. service-provider <service-provider> ... </service-provider> Identifiziert den VHS/3 - Dienstleister eines Mandanten. Dieses Element ist eine Metainformation des Headers, die immer gesendet werden muss, wenn das Ziel der Nachricht das VHS/3 ist und der Account mehrere Service Provider nutzen darf. Wenn der Service-Provider für den Account eindeutig ist, braucht das Element nicht übertragen werden. avs3-sales-organization <!-- 1 ... n --> <avs3-sales-organization> ... </avs3-sales-organization> Identifiziert die AVS/3 - Verkaufsorganisation innerhalb eines AVS/3 Mandanten. Dieses Element ist eine Metainformation des Headers, die bei AVS/3 Mandanten mit VkOrg Berechtigungsprüfung immer gesendet werden muss. Es muss die Vkorg eingetragen werden, zu der die Daten abgerufen werden sollen, bzw. für die die Daten bestimmt sind. Wenn die Vkorg nicht bekannt ist, können 1 … n zugelassene avs3-sales-organization Elemente angegeben werden. avs3-service-provider <avs3-service-provider> ... </avs3-service-provider> Identifiziert den AVS/3 - Dienstleister eines AVS/3 Mandanten. Dieses Element ist eine Metainformation des Headers, die bei AVS/3 Mandanten immer gesendet werden muss, wenn der Account mehrere Service Provider nutzen darf. Wenn der Service-Provider für den Account eindeutig ist, braucht das Element nicht übertragen werden. Referenz der SOAP-Header Elemente service-object <service-object> ... </service-object> Identifiziert das Zielobjekt einer SOAP-Nachricht. Attribute <namespace>:actor Identifiziert den SOAP-Intermediary anhand einer URI. <namespace>:mustUnderstand Legt fest ob der adressiert SOAP-Intermediary den Header verarbeiten muss oder ob ihm dies freigestellt ist. 1, true = Verarbeitung ist vorgeschrieben 0, false = Verarbeitung ist freigestellt Beispiel <service-object soap:actor="/net/dsb/wsportal/router/RequestHandler" soap:mustUnderstand="1"> /net/dsb/vhs3/stockinfo </service-object> service-method <service-method> ... </service-method> Identifiziert die Zielmethode einer SOAP-Nachricht. Die Methode muss innerhalb des unter service-object spezifizierten Objektes existieren. Attribute <namespace>:actor Identifiziert den SOAP-Intermediary anhand einer URI. <namespace>:mustUnderstand Legt fest ob der adressiert SOAP-Intermediary den Header verarbeiten muss oder ob ihm dies freigestellt ist. 1, true = Verarbeitung ist vorgeschrieben 0, false = Verarbeitung ist freigestellt Beispiel <service-method soap:actor="/net/dsb/wsportal/router/RequestHandler" soap:mustUnderstand="1"> getStockInfo </service-method> service-version <service-version> ... </service-version> Identifiziert die Version der Zielmethode einer SOAP-Nachricht. Die Methode und die Version der Methode müssen innerhalb des unter service-object spezifizierten Objektes existieren. Attribute <namespace>:actor Identifiziert den SOAP-Intermediary anhand einer URI. <namespace>:mustUnderstand Legt fest ob der adressiert SOAP-Intermediary den Header verarbeiten muss oder ob ihm dies freigestellt ist. 1, true = Verarbeitung ist vorgeschrieben 0, false = Verarbeitung ist freigestellt Beispiel <service-version soap:actor="/net/dsb/wsportal/router/RequestHandler" soap:mustUnderstand="1"> 2.0.0 </service-version> WSDL-Datei des WsPortal Gateways Dies ist die WSDL des WS-Portals. Hier am Beispiel der TEST-Instanz. Bitte betrachten Sie dies lediglich als Information und verwenden Sie zur Entwicklung immer die online verfügbare Version. <?xml version="1.0" encoding="UTF-8"?> <wsdl:definitions name="RequestHandler" targetNamespace="http://dsb.net/net/dsb/wsportal/router/RequestHandler" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://dsb.net/net/dsb/wsportal/router/RequestHandler" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"> <wsdl:message name="forwardMessage0In"> <wsdl:part name="dsbMessage" type="xsd:string"/> </wsdl:message> <wsdl:message name="forwardMessage0Out"> <wsdl:part name="Result" type="xsd:string"/> </wsdl:message> <wsdl:portType name="IRequestHandler"> <wsdl:operation name="forwardMessage" parameterOrder="dsbMessage"> <wsdl:input name="forwardMessage0In" message="tns:forwardMessage0In"/> <wsdl:output name="forwardMessage0Out" message="tns:forwardMessage0Out"/> </wsdl:operation> </wsdl:portType> <wsdl:binding name="IRequestHandler" type="tns:IRequestHandler"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="forwardMessage"> <soap:operation soapAction="forwardMessage" style="rpc"/> <wsdl:input name="forwardMessage0In"> <soap:body use="encoded" namespace="http://tempuri.org/net.dsb.wsportal.router.RequestHandler" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </wsdl:input> <wsdl:output name="forwardMessage0Out"> <soap:body use="encoded" namespace="http://tempuri.org/net.dsb.wsportal.router.RequestHandler" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="RequestHandler"> <wsdl:documentation> Request Handler of the WebService Portal Router </wsdl:documentation> <wsdl:port name="IRequestHandler" binding="tns:IRequestHandler"> <soap:address location="https://wsportal-tst.dsb.net:443/net/dsb/wsportal/router/RequestHandler"/> </wsdl:port> </wsdl:service> </wsdl:definitions> Cookies helfen bei der Bereitstellung von Inhalten. Durch die Nutzung dieser Seiten erklären Sie sich damit einverstanden, dass Cookies auf Ihrem Rechner gespeichert werden. OK Weitere Information