Table of Contents WsPortal Messages Introduction What is the WsPortal? What are WsPortal messages? What does the message frame look like? How messages are packed in a SOAP-request? Sending Messages Where are messages being sent? How is a message sent to dsb? What is important when you create a message? Which encoding has to be used? Complete Example Description Requirements User Account for the WsPortal Access Control WSDL-File of the gateway service Messages Request Answer HTTP HTTP Trace of the Question HTTP Trace of the Answer Errors: SOAP Faults What happens if an error occurs? Example HTTP Trace Offline Access Appendix Overview of the standard elements message header body client service-provider avs3-sales-organization avs3-service-provider Reference of the SOAP-Header elements service-object service-method service-version WSDL-File of the WS Portal gateway. WsPortal Messages Introduction What is the WsPortal? One of the challenges of IT Technology in the 21st century is the enterprise application integration (EAI). In the past the integration was done mainly for heterogeneous applications inside the companies. But now with the new possibilities of the internet this integration is extended to applications of business partners. Today applications of our clients and customers have to be integrated seamlessly in our own ones. To accomplish the integration of applications written in any language and running on different platforms, the web-service approach has proved to be the most efficient way. Many books have been published about web-services in the past few years. They explain what web-services are and how they work. So please consult one of these books if you are not familiar with the concept of web-services. The dsb uses web-services to provide different services of their ERP systems. The services cannot be accessed directly. Rather every request has to be sent to the WsPortal Gateway. This gateway routes the request to the target system. Furthermore the gateway provides authentication and authorization services. How you can access this gateway and how you can send messages to this gateway is explained in this document. Furthermore it explains how messages have to be structured according to the dsb specification. What are WsPortal messages? Two main implementations have been established to provide web-services. simple RPC services document centric services In the case of simple RPC services, the methods of the objects are made available merely per web-service. In the case of the document centralized services, XML-documents are sent within SOAP-bodies. These documents are processed only by the receiver. Any possible SOAP-Intermediary which could be linked in the message path will not process the message payload. DSB combines the best of both worlds. Basically all services of dsb are simple RPC services. Via these services only XML documents are sent and no primitive data types. This approach has several advantages: Normally large amount of data is sent, like purchase orders, customer fact sheets etc. Therefore you can map very complex structures with that approach. Existing structures can be extended flexibly. Standardized procedures can be used for testing the XML-documents (well-formed, valid). Very simple to implement. All sent XML documents have a standardized framework and carry the actual payload within a special part of this message frame. The additional message frame may seem needless the first time, but offers the advantage to send meta data with the actual payload. Therefore specifications remain general XML fragments (e. g. purchase-orders, invoices, … ) independent of certain back office systems. What does the message frame look like? The message frame is the basis of each request, that will be sent to a web-service. It is structured similar to a SOAP-message. The following abstract shows an empty frame: Message VHS-Service <message version="1.0" system="vhs/3"> <header> <client></client> <-- mandatory --> <service-provider></service-provider> <-- mandatory --> <service-object></service-object> <service-method></service-method> <service-version></service-version> ... more header fields ... </header> <body> ... payload ... </body> </message> Message AVS-Service <message version="1.0" system="avs/3"> <header> <client></client> <-- mandatory --> <avs3-sales-organization></avs3-sales-organization> <-- mandatory --> <avs3-service-provider></avs3-service-provider> <-- mandatory --> <service-object></service-object> <service-method></service-method> <service-version></service-version> ... more header fields ... </header> <body> ... payload ... </body> </message> You do not have to specify a DTD or schema definition. The root element of each message is the element „message”. This element has two attributes: “version“ and “system“. “Version” indicates the version of the specification of this message and „system“ shows the target- or the source-system of the message. The header is dedicated for meta information, which is needed by the target system but is not part of the payload. In the header, the element “client” and the element “service-provider” must always be filled. They indicate the client and the service-provider in the target system. More elements can be added optionally, depending on the application. The actual payload is packed in the body element. Here an unbounded number of elements can be placed in any possible nesting. Only the source and the target system must understand the structure. Messages are by requests and also by the corresponding replies. The only exception is if an error occurs. In this case the error information is delivered with a normal SOAP-fault. How messages are packed in a SOAP-request? The XML message document as described in the previous chapter will be sent over a SOAP-RPC. Hereby the document is the only string parameter of a method. A call of the ping method would look similar to this: ... <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> ... Here you can see very clearly how the actual messages (here bolded) is packed within the body of a SOAP-message. Important Note: The escaping of the message to be sent (e. g. the ping request) need usually not to be made manually. Rather every SOAP framework we know does this automatically. There you have to ensure that no double escaping takes place. Sending Messages Where are messages being sent? All external messages are sent at the WsPortal gateway of the dsb GmbH & Co. KG. This gateway is provided as Test and Production-System. Technically a web-service runs on this systems, which accepts extern requests and forwards them internally. The URL differs according to the access control you choose. Test-System Basic-URL (IP Whitelist): https://wsportal-tst.dsb.net Basic-URL (Client Certificate): https://wsportal-cca-tst.dsb.net Produktion-System Basic-URL(IP Whitelist): https://wsportal-prd.dsb.net Basic-URL (Client Certificate): https://wsportal-cca.dsb.net URL URL of the gateway WSDL: /net/dsb/wsportal/router/RequestHandler.wsdl SOAP-Service Endpoint: /net/dsb/wsportal/router/RequestHandler REST-Service Endpoint: /rest/ The gateway authenticates all request by the means of the HTTP-BASIC method. The authentication information must be included in the HTTP header of the request. How is a message sent to dsb? The service object RequestHandler has a method that is called “forwardMessage“. The only parameter of this method is the XML message as a string. The XML message must correspond to the dsb specification that is also described in this document. The easiest way to do this is to generate a proxy class with the help of the WSDL file and then to use an instance of it. The structure and the contents of the XML message can be found in the actual interface description of a certain web-service. What is important when you create a message? Because the WsPortal-Gateway acts as a so called “Intermediary“, it needs some additional information from the web-service client. For example you have to specify which service you would like to use. The client does this by adding this information in the header of the SOAP-message. In the header of the SOAP message (not to confuse with the header of dsb specific message) you have to add the elements “service-object“, “service-method“ and “service-version”. With these elements the WsPortal decides to which service this message is routed. How this should look for a certain service, can be checked in the actual interface description for a certain web-service. As an alternative you can pass the routing information in the header of a message. This is the preferred solution, in case the client-framework you use doesn't support the handling of SOAP-headers properly. Please mind the fact, that this alternative has a performance which is worse compared to the first solution. The reason for this is, that the complete message has to be analyzed before it can be routed. In this case the header of the message frame has to be in the following structure (see also section 2.3) <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> ... Payload ... </body> </message> Which encoding has to be used? For all XML documents (messages) the encoding ISO-8859-1 or UTF-8 should be used. Because SOAP itself is also based on XML all characters that have a special meaning have to be replaced by an escape character. According to the XML specification only the characters “<”, “>” and “&” have to be replaced when the encoding ISO-8859-1 is used. This can happen with the numerical as well as with the alphanumeric „entities“. character entity numeric < < < > &gz; > & & & More information is found at http://www.w3.org/TR/1998/REC-xml-19980210.html Complete Example Description The following sections show, based on a complete example, how data will be exchanged with a web-service of the dsb. This example shows the request of the “ping-service“. This service does nothing more than return a sent string unchanged to the sender. With the help of this simple method, the complete communication chain can be tested very simply. Requirements To be able to call the ping-service several requirements must be fulfilled User Account for the WsPortal You need a valid account to the WsPortal of the dsb. Please get in touch with your contact person if you do not have one. He will supply you with further information. Access Control There are two ways to get access to the services. Entry in WS-Portal IP-ACL Before external requests are accepted, all IP-addresses from which requests are sent, have to be added to the IP - access control list of DSB. Please provide information about this addresses to you contact person at dsb. Client Certificate You can use a specific client certificate. Please ask you dsb contact person for a certificate. WSDL-File of the gateway service You find all information about calling this service in the WSDL file. The WSDL file is found in the appendix of this document or at the internet address mentioned above. Many programming libraries offer tools to generate proxy classes out of this description. With an instance of such a proxy it is very simple to perform a call within your own applications. Messages Information is exchanged, as already mentioned, over the dsb message framework. The following sections show how these messages look for the ping-service. Request This is an example of a message that can be sent to the ping service. Please note that the client and the service-provider has to be replaced with your own values. Please keep in mind that in the following examples the routing information is located in the message header and not in the SOAP header. <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> Answer This is the answer that the ping service returns. <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 How this will look in the context of a HTTP message and what is sent over the line is shown in the following traces. Both of them are formatted optically in order to give a better overview of the single components. In the request, it can be seen how the client addresses the target system with elements in the SOAP Header. In the answer this information is no longer available. The body of the SOAP message carries the actual payload in the form of a dsb specific message. This message, which also represents a XML document, must be encoded. The encoding is very simple. Only the characters “>”, “<” and “&” have to be replaced by their respective entities. The character encoding of the XML document must be declared on the first line: <?xml version='1.0' encoding='UTF-8'?> or <?xml version='1.0' encoding='ISO-8859-1'?> UTF-8 is the Default. If UTF-8 is used this line can be omitted. But we recommend to always declare the encoding. The Encoding declared in the HTTP header Content-Type doesn't matter. HTTP Trace of the Question 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"?> <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 of the Answer 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 <?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"?> <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> Errors: SOAP Faults What happens if an error occurs? If an error occurs, while the message is processed, a SOAP-Fault according to the SOAP specification is returned. Please note that this happens only, if a „real“ error occurs. If you search for a business-partner, and the business partner is not found, no error is returned, but an empty result. Therefore no SOAP-Fault is created. A SOAP-Fault consists of different attributes, which allow to describe the problem that has occurred. dsb fills this attributes with the following content: Faultcode Contains „Server“ or „Client“, according to the source of the error. Faultstring Contains a error message that describes the error in plain English. The message is build according to the following structure. [<error id>] <error text> Faultactor The faultfactor indicates the module or the system which has noticed the error. Faultdetail Here you find an XML-structure, which contains further details to the error. Example The following example shows a common error. It occurs if an request is sent to the object “Bp” and the XML-schema check fails. Faultcode Client Because there was an error in the request, the client is responsible for that. Faultstring [10000] Error on line 2 of document : Element type “bp-numbe” must be declared. Error message consisting of error-ID and error text. Faultactor /net/dsb/vhs3/Bp The error that occurred or was noticed in the module Bp (business-partner) . 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> The root element must have the name „detail“ according to the SOAP specification. The detail element contains a „normal“ dsb Message, which in turn contains further details about the error. HTTP Trace The following lines show the HTTP-Trace of a SOAP-Fault: <?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 Access The preferred way to exchange data between dsb and business partners is online web services. But it is also possible to transfer the data asymchronously. This can only be used when transferring data to the dsb without the need of an an immediate feedback. The offline data exchange works in the following way: All data is sent via FTP. For this the dsb sets up a dedicated account on dsb's ftp or webdav server. There is a directory /to_dsb. All transferred files have to be put into this directory. At regular intervals dsb checks the availability of new files. The data is read and transformed into web service calls, just like the calls had been done directly to the web service. After the processing a protocol is sent to the sender of the file by eMail. The structure of the files, which can be sent by FTP, corresponds to the structure of requests made online. The data has to be in XML and wrapped by the well-known dsb message-frame. You can find further information in Batch. Appendix Overview of the standard elements message <message> ... </message> Encloses a dsb specific message and is therefore the root element. As child elements only “header” and “body“ are allowed. Attributes version Indicates the version of the message specification. system Indicates the back office system, which has sent or should receive the message. Currently there are two possible values “vhs/3” and “avs/3”. header <header> ... </header> Builds the header of a dsb specific message and encloses all elements which carry meta data. body <body> ... </body> Builds the body of a dsb specific message and encloses the actual payload. All elements which represent payload are child elements of the body. Furthermore, nesting is possible too. client <client> ... </client> Identifies the client of a message. This element represents a meta information of the header that must always be sent. service-provider <service-provider> ... </service-provider> Identifies the VHS/3 service-provider of a client of a message. This element represents a meta information of the header that must always be sent, if the message destination is the VHS/3. avs3-sales-organization <avs3-sales-organization> ... </avs3-sales-organization> Identifies the AVS/3 sales organization which belongs to a AVS/3 client. This element represents a meta information of the header that must always be sent, if the destination of the message is the AVS/3 and the AVS/3 client is run with “sales-organization”-authorization. avs3-service-provider <avs3-service-provider> ... </avs3-service-provider> Identifies the AVS/3 service-provider which belongs to a AVS/3 client. This element represents a meta information of the header that must always be sent. Reference of the SOAP-Header elements service-object <service-object> ... </service-object> Identifies the target object of a SOAP message. Attributes <namespace>:actor Identifies the SOAP-Intermediary based on an URI. <namespace>:mustUnderstand Determines if the addressed SOAP-Intermediary has to process the header or if it is optional. 1, true = processing is mandatory. 0, false = processing is optional Example: <service-object soap:actor="/net/dsb/wsportal/router/RequestHandler" soap:mustUnderstand="1"> /net/dsb/vhs3/stockinfo </service-object> service-method <service-method> ... </service-method> Identifies the target method of a SOAP message. You have to ensure, that this method is part of the target-object which is specified in the “service-object” element. Attributes <namespace>:actor Identifies the SOAP-Intermediary based on an URI. <namespace>:mustUnderstand Determines if the addressed SOAP-Intermediary has to process the header or if it is optional. 1, true = processing is mandatory 0, false = processing is optional Example: <service-method soap:actor="/net/dsb/wsportal/router/RequestHandler" soap:mustUnderstand="1"> getStockInfo </service-method> service-version <service-version> ... </service-version> Identifies the version of a method of a SOAP message. You have to ensure, that the version of this method is part of the target-object which is specified in the “service-object” element. Attributes <namespace>:actor Identifies the SOAP-Intermediary based on an URI. <namespace>:mustUnderstand Determines if the addressed SOAP-Intermediary has to process the header or if it is optional. 1, true = processing is mandatory 0, false = processing is optional Example: <service-version soap:actor="/net/dsb/wsportal/router/RequestHandler" soap:mustUnderstand="1"> 2.0.0 </service-version> WSDL-File of the WS Portal gateway. This is the WSDL file of the TEST instance of the WS-Protal gateway. It is printed here just for the purpose of information. Please use always the online version for development. <?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> This website uses cookies for visitor traffic analysis. By using the website, you agree with storing the cookies on your computer.OKMore information