Symptom

You are experiencing problems with the SAP XI 3.0 SOAP Adapter and/or need further detailed information about its operation and configuration.

Other terms

XI30, Adapter Framework, Frequently Asked Questions, HOWTO

Reason and Prerequisites

This note serves as FAQ document for the SAP XI 3.0 File Adapter and contains answers to the most commonly asked questions about the adapter's operation and configuration. It will be updated with new information from time to time as the need arises.

Solution

1. Sender Connection

• Q: To which URL can I send my SOAP message?

           A: The URL for your SOAP sender channel is

           http://host:port /XISOAPAdapter/MessageServlet?channel=p:s:c

           wherehost is the host name, port is the port number, p is the optional party name, s the service name, and c is the channel name, respectively.

• Q: My client gets no connection to the adapter's URL.

           A: Make sure that the adapter is running at the specified URL. Use your browser to open the URL for your SOAP sender channel. The page should show a status page with status "OK".

• Q: I get an authorization error "401 Unauthorized" from the adapter's servlet. What went wrong?

           A: The adapter's servlet is protected by default. You must use one of the user names assigned in security role xi_adapter_soap_message for component XISOAPAdapter. Please consult the documentation for Visual Administrator to view and change the security setting.

            The user authentication of the SOAP adapter is not part of the SOAP adapter but of the web container of the J2EE engine. The default authentication setting is defined in the web.xml descriptor file of the SOAP dapter web application. This setting may be modified from Visual Administrator with some restriction. Please refer to the security documentation for the J2EE engine.

• Q: I get a permission error "403 Forbidden" from the adapter's servlet. What went wrong?

            A: It is likely that the URL is incorrect or the adapter is not correctly deployed.

• Q: I get a server error "500 Internal Servler Error" from the adapter's servlet. What went wrong?

           A: There are several possibilities. It is lilely that the request message arrived at the SOAP adapter but there was some error in the request message or in the channel configuration. In this case, the error message returned should be a SOAP fault message containing the detailed error information. The possible causes can be "No SOAP envelope", "invalid channel", "no receiver agreement", etc. If your SOAP client cannot display this detailed error information, please capture the message using some tool (See question "How can I trace the whole message?").

• Q: I get the invalid channel error even though I have configured the corresponding channel in the directory.

            A: To check if the channel is available, you can open the following URL from your browser.

           http://host:port /XISOAPAdapter/HelperServlet?action=FindChannel& channel=p:s:c

           wherehost is the host name, port is the port number, p is the optional party name, s the service name, and c is the channel name, respectively.

            This will show a page with the channel information if the channel is available. If the channel is not available, please make sure that your channel name is correct and the adapter engine's CPA cache is valid.

• Q: Can I use SSL for my sender adapter?

           A: Yes. Normally, the SOAP adapter servlet runs on the engines HTTP port. But you can activate the engine's HTTPS port so that this servlet can receive messages sent to the HTTPS port. See the documentation about the J2EE engine's security configuration.

• Q: Can I increase the default timeout value for the sender adapter?

           A: Yes. The default timeout value for synchronous calls is 5 minutes. You can increase this value by setting parameter XI.Timeout in the module parameter table of the SOAP adapter. The value must be given in milliseconds. For example, value 600000 represents the timeout value of 10 minutes. This parameter is not recognized in systems prior to SP13.

• Q: Can I set the interface name dynamically from the client?

           Yes. You can overwrite these XI parameters from the client. To activate this overwriting mode, you need to turn on option "Use Encoded Header" and "Use Query String" in the channel. Then your client can append the interface name using parameter Interface.

           For example, interface namespace http://sap. com/test and interface Test can be represented by the url-encoded form of http://sap.com/test^Test as in

           #&version=3.0&Interface=http%3A%2F%2Fsap. com%2Ftest%5ETest

• Q: My SOAP client sends a SOAP with multiple elements in the SOAP body but I can see only the first element in the XI main payload. How can I get all the elements into the XI message?

            A: The default behavior of the SOAP adapter is to place the first element of the SOAP body into the XI application payload. If the SOAP message contains more than one elements in its SOAP body, you can configure the channel to run in the nosoap mode.

            In this mode, the original request message is inserted entirely into the application payload.

            Related Questions: How does the nosoap mode work for the SOAP sender adapter?

2. Sender Asynchronous Calls

• Q: What are the correct sender options for asynchronous calls?

            A: The setting in the channel configuration determines how the message is passed to the XI infrastructure. Setting the channel's quality of service to ExactlyOnce guarantees the delivery of the message exactly once between the adapter and the back end. This will not automatically guarantee the delivery with exactly once between the client and the back end. The behavior of the client determines the level of quality of service achieved.

            When the client sends a SOAP message and ignores the response completely as in "fire-and-forget", the quality of service with AtMostOnce may be realized.

            When the client sends a SOAP message and checks if the response is an HTTP 200 response message, the quality of service with AtLeastOnce can be realized. In this case, the client must resend the message until such a successful response is returned. When the message successfully accepted by the adapter, an HTTP 200 response with an empty SOAP envelope is returned.

            When the client resends the message, there is a possibility that the message may arrive more than once. However, this possible duplicate only happens, when the client previously received no response message at all or an HTTP 500 with duplicate message ID error. For all other cases, the client can resend the message without resulting any duplicate. In order to eliminate duplicates for all cases, the client may send the message with a unique message ID. This message ID will be used to create an XI message so that the identity of the created XI message and that of the original SOAP message are coupled. The client must resend the message with the same message ID until an HTTP 200 reponse is returned or an HTTP 500 response with SOAP fault DuplicateMessageException. In either case, the client can assume that the message is delivered exactly once (theoretically the message ID could be identical to another message ID used previously but the probability of this is extremely low).

            Related Questions "How to set the message ID from SOAP client?"

• Q: How to set the message ID from my SOAP client?

           A: You can set the message ID in the request URL as

           http://host:port /XISOAPAdapter/MessageServlet?channel=p:s:c& version=3.0&...&MessageId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

           where xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is a GUID string.

            Related Questions "What are the options for asynchronous calls?"

• Q: How to set the queue ID from my SOAP client?

           A: You can set the message ID in the request URL as

           http://host:port /XISOAPAdapter/MessageServlet?channel=p:s:c& version=3.0&...&QueueId=xxxxxxxxxxxxxxxx

           where xxxxxxxxxxxxxxxx is an ABAP queue ID.

            Related Questions "What are the options for asynchronous calls?"

3. Other Sender related Questions

• Q: My SOAP client throws an error. What can I do?

           A: You need to find out what exaclty this error is. It could be a connection error, authorization error, parsing error, etc. If your client itself does not provide detailed information, you need to set up a TCP gateway between your client and the sender adapter. See question "How can I trace the whole message?".

• Q: Where can I see messages I sent from my soap client?

            A: The adapter's message monitoring tool should display all the messages that entered the adapter engine. Those messages that arrived at the SOAP adapter but resulted in some error are shown in the error message box of the message monitor. Finally, those messages that didn't even reach the SOAP adapter will not be displayed anywhere. If you don't see your messages in the monitor, you should inspect the response message that your client received. The response message should contain information about the cause of the error.

           Related Questions "How can I trace the whole message?"

• Q: What character encoding is supported by the SOAP sender adapter?

            A: The SOAP sender adapter can accept any character encoding supported by the local JDK. When you are using a particular character encoding with content type text/xml, you must make sure that the encoding name given in the content type and in the XML declaration must be consistent. What makes this more complex is that the default values. The default encoding for "text/xml" is US-ASCII, whereas the default encoding for the XML declaration is UTF-8 or UTF-16. The following examples show several valid combinations of content-type and XML declartion:

           text/xml

           <?xml version='1.0' encoding='us-ascii'?>

           text/xml; charset='utf-8'

           <?xml version='1.0' encoding='utf-8'?>

           text/xml; charset='utf-8'

           no declaration

           text/xml; charset='iso-8859-1'

           <?xml version='1.0' encoding='iso-8859-1'?>

           application/xml

           <?xml version='1.0' encoding='iso-8859-1'?>

            The response message from the SOAP sender is normally encoded in UTF-8. If you want to change this encoding, for instance to iso-8859-1, you can supply the encoding information with the xmlenc variable in the request URL as in:

           http://host:port /XISOAPAdapter/MessageServlet?channel=p:s:c&xmlenc=iso-8859-1

            Related Questions "What character encoding is supported by the SOAP receiver adapter?"

• How does the nosoap mode work for the SOAP sender adapter?

            A: The nosoap mode makes the adapter to treat the external message as one or more XI payloads without wrapping or unwrapping the payloads with the SOAP envelope. For example, you can send a simple text content to the SOAP adapter, and this content will be placed in the XI payload. If you are sending a multipart MIME message, depending on the attachment setting in the channel, one or all parts will be placed in the XI payloads. Although the main use of this mode is to send some XML content directly to the XI, one can use this mode to access the entire SOAP message when it is used along with the SOAP message.

            This option can be activated in the sender channel configuration. Additionally, the adapter servlet URL must carry parameter nosoap=true. Using the previous example, the URL must look like

           http://host:port /XISOAPAdapter/MessageServlet?channel=p:s:c&nosoap=true

• Q: My SOAP message contains some additional information in the SOAP Header. How can I access this information in XI?

            A: In default, the SOAP adapter takes only the first SOAP Body child into the XI message. In order to make the other part of the SOAP message available in XI, you need to use the nosoap mode.

            Related Questions "How does the nosoap mode work for the SOAP sender adapter?"

5. Receiver Connection

• Q: Can I use SSL for my receiver adapter?

           A: Yes. You can enter any target URL with "https:..." and the adapter will use the HTTP protocol over an SSL connection.

• Q: I get the SSL handshaking error. I get some error when I call my SSL web service.

            A: First, please make sure that the SSL server is working correctly with another client. If the server is working and you still have the problem, the most likely cause is that your J2EE engine is not configured appropriately to be able to use the unrestricted strong features of the cryptographic library. Please make sure that:

            - The JDK java security lib directory ($JAVAHOME/jre/lib/security) contains the unrestricted strong version of local_policy.jar and US_export_policy.jar, which are about 5KB and not the restricted version that are about 3KB each. If you have the restricted version, please refer to http://java.sun.com/ to obtain the unrestricted version.

            - The full version of IAIK is available in the J2EE engine's Security Provider. To check this, go to Service -> Security Provider -> Cryptography Providers, and select IAIK. The Provider Information field should show the full version (e.g., IAIK Security Provider v3.12) and not the evaludation version (e.g., IAIK Security Provider v3.01, evaluation version). If you have the evaludation version, please refer to the security setting section of the SAP J2EE documentation.

• Q: Can I use SSL with client certificate to authenticate my adapter?

           A: Yes. You can configure your receiver channel to use a client certificate. This feature is available from SP13.

            Related Questions "I cannot call an SSL web service requiring a client certificate."

• Q: I cannot call an SSL web service requiring a client certificate.

            A: If you can call an SSL web service requiring no client certificate, please make sure that your clietn certificate is valid and correctly stored in the key store of the J2EE engine. There have been some problems reported in SP13. Please consult SAP Note 870845 for the correction and/or the workaround.

            If your certificate entry contains more than one certificates, please make sure that they are ordered correctly.

            If you are experiencing some problem, please refer to note 888421 for three different options in using certificates at SSL handshaking.

            To trace security related problems, the logging level of components com.sap.aii.security.lib and com.sap.aii.af.security should be set to DEBUG.

• Q: Can I use several HTTP proxy servers for my channels?

           A: Yes. You can configure your proxy setting per channel.

• Q: Can I configure the timeout value of my receiver adapter?

           A: Yes. The default timeout value for outbound calls is 5 minutes. You can increase this value by setting parameter XMBWS.Timeout in the module parameter table of the SOAP adapter. The value must be given in milliseconds. For example, value 600000 represents the timeout value of 10 minutes. This parameter is not recognized in systems prior to SP13.

            Related Questions "Can I increase the default timeout value for the sender adapter?"

6. Receiver Asynchronous Calls

• Q: What are the correct receiver options for asynchronous calls?

            A: The processing mode of the receiver is determined by the message that reaches the receiver. If you are sending a message with some quality of service, to provide this service of quality to the server, your must make sure two things. First, your receiver channel must be configured to pass the XI message ID to the server. Second, your web service must check duplicates using this message ID.

• Q: What should my web service return to the adapter for asynchronous calls?

            A: Currently, the receiver adapter expects an HTTP 200 with a SOAP envelope with an empty content for successful delivery. Any other response will result in a XI system error and triggers retries of the message. When you want to check duplicates, you should configure your receiver channel to pass the XI message header information to the server.

            Prior to SP11, a SOAP fault resulted in the application or system error, depending on whether the SOAP fault contained a detail child element or not. This behavior contradicted the communication model. Therefore, it has been changed so that the adapter generates the system error for any SOAP fault in asynchronous calls.

            When you want to check duplicates in your web service, you should configure your receiver channel to pass the XI message header information to the server. When your web service indeed find a duplicate, assuming that the previous message was simply lost, your web service should return an HTTP 200 with an empty SOAP envelope.

7. Other Receiver related Questions

• Q: What should my web service return to the adapter?

           A: The receiver adapter expects a SOAP message as response. For synchrnous calls, a successful response should be returned with HTTP 200. In this case, the content of the SOAP body will be returned to the caller as the response payload. When some error occurs, the SOAP message may contain the SOAP fault element. In this case, when the fault detail element is not empty, its content will be returned as the fault payload in an application error message. For others, a system error message will be returned to the caller.

HTTP/1.1 200 OK

Content-Type: text/xml; charset="utf-8"

<SOAP:Envelope

  xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">

  <SOAP:Body>

    <m:GetLastTradePriceResponse xmlns:m="Some-URI">

      <Price>34.5</Price>

    </m:GetLastTradePriceResponse>

  </SOAP:Body>

</SOAP:Envelope>

            will result in an application response message with response payload

<m:GetLastTradePriceResponse xmlns:m="Some-URI">

  <Price>34.5</Price>

</m:GetLastTradePriceResponse>

HTTP/1.1 500 Internal Server Error

Content-Type: text/xml; charset="utf-8"

<SOAP:Envelope

  xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">

  <SOAP:Body>

    <SOAP:Fault>

      <faultcode>SOAP:MustUnderstand</faultcode>

      <faultstring>SOAP Must Understand Error</faultstring>

    </SOAP:Fault>

  </SOAP:Body>

</SOAP:Envelope>

           will result in a system error message.

HTTP/1.1 500 Internal Server Error

Content-Type: text/xml; charset="utf-8"

<SOAP:Envelope

  xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">

  <SOAP:Body>

    <SOAP:Fault>

      <faultcode>SOAP:Server</faultcode>

      <faultstring>Server Error</faultstring>

      <detail>

        <e:myfaultdetails xmlns:e="Some-URI">

          <message>My application didn't work</message>

          <errorcode>1001</errorcode>

        </e:myfaultdetails>

      </detail>

    </SOAP:Fault>

  </SOAP:Body>

</SOAP:Envelope>

            will result in an application error message with fault payload

<e:myfaultdetails xmlns:e="Some-URI">

  <message>My application didn't work</message>

  <errorcode>1001</errorcode>

</e:myfaultdetails>

            For asynchronous calls, see "What should my web service return to the adapter for asynchronous calls?".

• Q: My receiver adapter received an HTML page instead of a SOAP XML. What happened?

            A: See question "My receiver adapter received something other than the SOAP envelope".

• Q: My receiver adapter received something other than the SOAP envelope. What happened?

           A: The most likely cause is the wrong target URL or invalid authorization given in the channel configuration. Please make sure that these values are correct. If the problem persists, you need to trace the transported messages. See question "How can I trace the whole message?".

• Q: Where can I see messages I want to send to my web service?

            A: The adapter's message monitoring tool should display all the messages that go through the adapter engine. When your scenario is configured correctly, your message should be displayed in the message monitor. If there is no error for your message, the adapter has successfully send your message to your web service.

           Related Questions "How can I trace the whole message?"

• Q: What character encoding is supported by the SOAP receiver adapter?

            A: The SOAP receiver adapter can use any character encoding supported by the local JDK. The request message from the SOAP receiver is normally encoded in UTF-8. If you want to change this encoding, for instance to iso-8859-1, you can set parameter XMBWS.XMLEncoding to iso-8859-1 in the module configuration for the SOAP adapter module. This setting is for the outgoing SOAP message and has no effect on the incoming SOAP message. For the incoming SOAP message, any code page supported by the local JDK is accepted.

            Related Questions "What character encoding is supported by the SOAP sender adapter?"

• Q: My web service expects a SOAP with multiple elements in the SOAP body. How can I create such SOAP message?

            A: The default behavior of the SOAP adapter is to place the application payload into the first element of the SOAP body. If the SOAP message must contain more than one elements in its SOAP body, you can configure the channel to run in the nosoap mode. This option can be activated in the receiver channel configuration. In this mode, the XI application payload of the request message is entirely sent to the web service and its response is returned in the XI application payload. You must make sure that the XI appliaction payload passed to the SOAP receiver adapter represents a SOAP request message accepted by the web service. The SOAP receiver adapter returns the XI response message containing the SOAP response message in its XI application payload. If you are using the noSOAP mode to call some SOAP service, your XI application payload must represent the SOAP envelope. If this is not the case, you need a mapping to map your XI payload between its original format and its SOAP format. If you are using the nosoap mode to call some non SOAP service, this mapping is not neccessary.

            Related Questions: "How does the nosoap mode work for the SOAP receiver adapter?", "How does the nosoap mode work for the SOAP sender adapter?

• Q: How does the nosoap mode work for the SOAP receiver adapter?

            A: The nosoap mode lets the adapter send the XI payload directly without wrapping it in the SOAP envelope. Although the main use of this mode is to send some plain text content directly to some web server, one can use this mode to send their own SOAP message (e.g., with arbitrary headers) to an external web service (See related questions). In this case, the XI payload must be formatted in the SOAP envelope.

            To use the nosoap mode, the channel must be configured to use no SOAP envelope.

            Related Questions: "My web service expects a SOAP with multiple elements in the SOAP body. How can I create such SOAP message?"

8. Other Questions

• Q: My sender adapter is still not working. What can I do?

            A: Please open a problem report, describe the problem and provide the necessary information. See question "Which information must be included in a problem report?".

• Q: My receiver adapter is still not working. What can I do?

            A: Please open a problem report and provide the information given in the answer to question "Which information must be included in a problem report?".

• Q: Does the RPC or Document style in WSDL play a role in the SOAP adapter?

           A: No. These styles are used in WSDL to describe how the message is represented as a SOAP message. And this corresponds to how the XI payload is represented. You must make sure that your XI proxy is generating the valid payload according to the given WSDL in whatever the style. If this is not the case (e.g., your proxy is generated by another WSDL and there is a mismatch in how the payload must look), you need to configure some mapping to match the payload.

            Related Questions "Can I convert an RPC styled WSDL to a document styled WSDL?"

• Q: Can I convert an RPC styled WSDL to a document styled WSDL?

            A: It is difficult to answer yes or no because the answer depends on the WSDL instance and the implementation of the code that binds the XML instance to some native object. The problem comes from the fact that these two styles describe web services in different layers. The document style WSDL describes how one can bind an XML document to the SOAP message format. In contrast, the RPC style WSDL describes how one can bind an object to the SOAP message format. One can imagine that this works in two steps: first representing the object as an XML document and then binding this XML document to the SOAP message format. How this first step works is controlled by the SOAP encoding name. For the standard encoding specified in the SOAP specification, most objects can be easily described in an equivalent XML schema. Some special objects such as references and arrays must be represented by some special rules and some additional meta information in XML. This implies that these additional attributes and elements must also be described in the XML schema and the document style based proxy must set these values in the instance appropriately.

            One must however note that even if one has an equivalent document style WSDL, this does not automatically guarantees the interoperability. Some RPC styled service implementations have significant interoperability problems such as requiring the xsi:type attribute for every element or the SOAP encoding attribute at some particular element. If one has to call such non conformant SOAP service, one must adjust the message accordingly.

           Attachment wsdl_style_samples. zip contains some examples of WSDL documents and sample SOAP messages that illustrate how one can write an equivalent WSDL in another style.

            Related Questions "Does the RPC or Document style in WSDL play a role in the SOAP adapter?"

• Q: Which information must be included in a problem report?

            A: Please refer to Note 854536 for the information necessary for adapter problems.

• Q: How can I trace the whole message?

            A: If you have a third-party web service server or client and if it works with their own test tool but not with the SOAP adapter, you need to analyze the messages that are transported. Typically, this is done by either inseting a TCP gateway between the client and the server or non-invasively using some packet catching utility. You are free to use any tool but make sure that the tool can capture the messages as raw bytes. Some tools are known to store the captured messages as text and corrupt some characters.

            You can find a tool called TCPGateway in the attachment section of this note (stored in tcpgw.zip). Please unpack this zip file and open index.htm for more details.

• Q: Is there any tool available for creating and sending SOAP messages to some web service?

           A:

• Q: Which components must be set to DEBUG while collecting trace?

           A: For SOAP adapter initialization problem, component com.sap. aii.af.mp.soap must be set to DEBUG. For runtime problem, additionally component com.sap.aii.messaging must be set to DEBUG.

• Q: Which information must be included in a problem report?

           A: The following information must be included:

           For receiver problems:

• Screenshots of the SOAP channel configuration.

• The audit log information from the failing message's audit log.

• The SOAP message that the adapter is sending to the web service.

• The SOAP message that is known to work for the web service.

• The WSDL file for the web service if available.

• The vendor information of the web service.

           For sender problems:

• Screenshots of the SOAP channel configuration.

• The audit log information from the failing message's audit log or the error log for non-persisted messages.

• The SOAP message that the client is sending to the adapter.

• The response message that the client is receiving from the adapter.

• The vendor information of the client.