Adapters in Detail

Adapters in DetailA detailed description of the common adapters Table of Contents ADAPTERS IN DETAIL.............................................................................................................................................1 OVERVIEW..................................................................................................................................................................2 ACKNOWLEDGMENTS.......................................................................................................................................................3 XI ADAPTER ARCHITECTURE OVERVIEW.......................................................................................................4 XI COMPONENTS RELATING TO THE ADAPTER.....................................................................................................................4 The Adapter Engine...............................................................................................................................................4 The Adapter Framework.......................................................................................................................................4 Resource Adapters................................................................................................................................................5 Partner Connectivity Kit.......................................................................................................................................5 XI ADAPTERS..............................................................................................................................................................5 IDOC ADAPTER..............................................................................................................................................................5 Implementation Considerations............................................................................................................................5 Integration.............................................................................................................................................................6 RFC ADAPTER..............................................................................................................................................................6 JDBC ADAPTER............................................................................................................................................................6 SOAP ADAPTER............................................................................................................................................................6 FILE / FTP ADAPTER.....................................................................................................................................................6 MAIL ADAPTER..............................................................................................................................................................6 BUSINESS CONNECTOR ADAPTER......................................................................................................................................6 JMS ADAPTER..............................................................................................................................................................6 MAIL ADAPTER..............................................................................................................................................................6 HTTP ADAPTER............................................................................................................................................................6 APENDICES..................................................................................................................................................................6 MAIL ADAPTER FAQ.....................................................................................................................................................6 JMS ADAPTER FAQ...................................................................................................................................................10 SOAP ADAPTER FAQ.................................................................................................................................................10 JDBC ADAPTER FAQ.................................................................................................................................................18 BC ADAPTER FAQ.....................................................................................................................................................22 RFC ADAPTER FAQ...................................................................................................................................................24 Adapters in Detail OVERVIEW Adapters enable the Integration Engine and the Partner Connectivity Kit (PCK) to communicate with different applications. Adapters connect the Integration Engine to SAP legacy systems, as well as to external systems. In this way, adapters integrate existing SAP components with SAP Exchange Infrastructure, for example. In the process, XML and HTTP-based documents are converted to IDocs (IDoc adapter) and RFCs (RFC adapter) and the other way around. This enables you to integrate your existing SAP infrastructure with the new SAP infrastructure, which is based on system integration and the exchange of XML messages. The plain HTTP adapter gives application systems the option of communicating with the Integration Engine and exchanging business data in a simple format, using an HTTP connection. Furthermore, the J2EE-based Adapter Engine provides you with various adapters that you can use to connect external systems to your Integration Engine. You can use these adapters to convert XML and HTTP-based messages to the specific protocols and formats of the respective external systems and the other way around. You can specify generic modules for adapters in the Adapter Engine in the module processor. These modules give the adapters additional functions. In addition to the J2EE-based Adapter Engine, you can also use the plain J2SE-based Adapter Engine. Adapter Type IDoc Transport Protocol Message Protocol IDoc-XML Quality of Service EO, EOIO with qRFC Attachments Acknowledgments Attributes in Message Header Sender Adapter: tRFC File Receiver Adapter: tRFC No System error acknowledgments Application acknowledgements Application error acknowledgements RFC Plain HTTP SAP Business Connector (BC) File/FTP RFC HTTP(S) 1.0 HTTP(S) RFC-XML XI payload in HTTP body RFC XML with envelope IDoc-XML BE, EO, EOIO BE, EO, EOIO BE, EO No No No See below under Acknowledgments. No See below under Acknowledgments. Sender 1. 2. File system (NFS) File transfer protocol/file transfer protocol using SSL/TLS 3. 4. File File with content conversion BE, EO, EOIO Yes (Sender) See below under Acknowledgments. Sender Receiver JDBC JDBC 2.0 Sender Adapter: JDBC 2.0 Receiver Adapter: XML SQL format Native SQL format BE, EO, EOIO No See below under Acknowledgments. Last printed 9/23/2005 9:24:00 a9/p9 Page 2 of 29 1 EO No RNIF 1. receiver) Yes. since they also support scenario-dependent application acknowledgments. EOIO MML BE. Sender adapters of the Adapter Engine do not request any acknowledgments. 17. XI 2.5 12.Adapters in Detail JMS 5. 15. RNIF11 16. IXALL XIPAYLOAD IMAP4 POP3 Receiver Adapter IMAP4 SMTP RNIF20 14. Sender Receiver JMS 1. SOAP Sender Adapter: Sender Adapter: See below under Acknowledgments. receiver) See below under Acknowledgments. See below under Acknowledgments. receiver) See below under Acknowledgments. BE. See below under Acknowledgments. Sender Receiver 8. EO.1 HTTPS 20. Mail HTTP(S) JMS Sonic MQ 3.1 HTTPS HTTP 1.0 EO No See below under Acknowledgments. Acknowledgements are triggered when a message is successfully processed by the adapter or if an error occurs while it is being processed.0 BE. EOIO No See below under Acknowledgments. EO. for XIPAYLOAD (sender. BE.1 HTTP Receiver Adapter: HTTP(S) SMTP(S) Marketplace 10. XI HTTP 1.0 Acknowledgments Receiver adapters that run on the Adapter Engine support system acknowledgments if they are requested by the sender. 6. CIDX 18. 13.0 XI 3. Last printed 9/23/2005 9:24:00 a9/p9 Page 3 of 29 . EO. 7. 21. 11. SonicMQ JMS Provider WebSphereMQ (non-JMS) Access JMS Provider with JNDI (Read) JMS Provider Administered Objects from File Access JMS Provider Generically SOAP 1. 9. EOIO Yes (sender. Sender Receiver HTTP(S) 1. The RNIF and CIDX adapters are exceptions to this rule. EO Yes (sender. EOIO No RNIF 1.1 HTTPS HTTP 1. Receiver adapters do not support application acknowledgments.1 EO No RNIF 2. 19.x EO. and HTTPbased messages to the specific protocol and format required by these systems. The adapter framework supports the JCA standard (JCA: J2EE Connection Architecture) and communicates with Resource Adapters. Last printed 9/23/2005 9:24:00 a9/p9 Page 4 of 29 . and vice versa. queuing. The Adapter Framework A central component of the adapter runtime is the Adapter Framework. which are either a component of SAP XI or are provided by SAP partners. The Adapter Engine is a separate software component that is automatically installed on the Integration Server. apart from the IDoc adapter. and security handling.Adapters in Detail XI ADAPTER ARCHITECTURE OVERVIEW Figure 1: XI Architecture XI Components relating to the Adapter The Adapter Engine The Adapter Engine is used to connect the Integration Engine to SAP and external systems. You use different adapters in the Adapter Engine to convert XML. TIP: See OSS note 821268 for FAQ on the Adapter Framework. You can also install the Adapter Engine separately on another host as a local (non-central) adapter engine. All adapters shipped by SAP are resource adapters. with services for messaging. Adapters in Detail Resource Adapters These are the adapters developed and delivered by SAP as well as the adapters developed by 3rd party providers (e. iWay) Partner Connectivity Kit You use the PCK to connect a business system environment of a smaller business partner to the Integration Server of a system landscape integrated by means of XI. The IDoc adapter is used by SAP systems to connect to a centrally configured Integration Engine using IDocs. The PCK contains the following adapters: • RFC Adapter • File Adapter • JMS Adapter • JDBC Adapter • SOAP Adapter • SAP Business Connector Adapter • Mail Adapter • XI Adapter XI ADAPTERS You only require an adapter to communicate with SAP systems older than Release 6. A direct system connection using proxies and without additional adapters is supported for SAP systems that are based on SAP Web Application Server 6. Seeburger. A system that has an Integration Engine of this type is referred to as the Integration Server.20 and with external systems.g.1x or higher are supported. Last printed 9/23/2005 9:24:00 a9/p9 Page 5 of 29 . The PCK enables messages to be exchanged with the business system landscape of the smaller business partner. and then forwards the message. External systems can also use the IDoc adapter to connect to an Integration Server.20 or higher. For example. or if you want to integrate different components or integration processes that were previously not integrated. Only stop using existing functioning IDoc scenarios after serious consideration. IDoc Adapter The IDoc adapter enables you to process IDocs (Intermediate Documents) using the Integration Engine. The message is forwarded to the Integration Server for further processing. IDocs from SAP systems Release 3. if you want to make IDoc data in the form of XML messages available to additional receivers. converts it into the format required by the receiver system. Implementation Considerations Only use the IDoc adapter to integrate SAP systems with the Integration Server if a scenario of this kind suits your requirements. The PCK of the smaller business partner receives a message from its system landscape and converts the format of the message to XI message protocol. the PCK of the business partner receives the message. To forward XML messages from the Integration Server to a receiver business system in the system landscape of the smaller business partner. The adapter at the inbound channel is located before the Integration Server pipeline and calls this pipeline. JMS Adapter TIP: See OSS note 856346 for FAQ on the Adapter. and can therefore be regarded as part of the pipeline.Adapters in Detail Integration The IDoc adapter is part of the Integration Server. SOAP Adapter TIP: See OSS note 856597 for FAQ on the Adapter. The adapter at the outbound channel. Sender Connection Last printed 9/23/2005 9:24:00 a9/p9 Page 6 of 29 . JDBC Adapter TIP: See OSS note 831162 for FAQ on the Adapter. The connected systems transfer or receive IDocs through their IDoc RFC interface. namely an adapter at the Integration Server inbound channel. File / FTP Adapter TIP: See OSS note 821267 for FAQ on the Adapter. Mail Adapter TIP: See OSS note 856599 for FAQ on the Adapter. HTTP Adapter APENDICES Mail Adapter FAQ 1. is called by the pipeline. RFC Adapter TIP: See OSS note 730870 for FAQ on the Adapter. Mail Adapter Business Connector Adapter TIP: See OSS note 774854 for FAQ on the Adapter. Essentially. the IDoc adapter comprises two parts. The metadata for the IDoc types involved is shared. however. and an adapter at the Integration Server outbound channel. The channel with POP3 fetches all messages from the specified mail box in the order they are stored. Once the messages are read but not processed correctly. You should be able to find your mail sender channel under the Mail adapter. If some error occurs 5. At least there is no message shown in the message monitor. you can look at the status of this channel at the adapter's monitor. you must correct the problem or delete these messages using your mail client program. they remain in the mail box but are not read in the subsequent polling cycle. If this status is OK. 3. This should show any error if the messages are not processed correctly. You must correct the problem and delete these messages using your mail client program or reset them as unread so that they can be resend. Sender with XIPAYLOAD  Q: How can I get the original sender email address and subject. there will be a new mechanism to transport transport specific information for all adapters. Therefore. 2. 4. Receiver Connection  Q: My mail messages does not seem to be sent out. you can look at the status of this channel at the adapter's monitor. please make sure that you have some unread messages in the top of the list (if ordered by most recent on top). Therefore. Once the messages are read but not processed correctly. The detail text of the audit log should describe the problem. 7. A: The mail sender channel with IMAP4 fetches only the unread messages from the specified mail box in the order they are stored. In SP14. After a polling cycle. After a polling cycle. This should show any error if the messages are not processed correctly. A: Please look at the adapter monitor in Runtime Workbench. If the problem is permanent. From this status message. 6. Sender Asynchronous Calls  Q: What is offered by a sender channel configured as ExactlyOnce or ExactlyOnceInOrder? A: The quality of service setting in the sender channel does not mean that this quality of service is automatically provided between the mail server and the XI system. A: Please check the status of your channel in the adapter monitor. Other Sender related Questions  Q: My mail messages are not picked up. The detail text of the channel should describe the problem. Sender with XIALL  Q: I get some exception and my mail message does not seem to be processed. The status of the adapter monitor is updated for each polling cycle.Adapters in Detail  Q: My mail messages seem to be read by the adapter but not processed. The setting only allows the adapter to be able to call some XI asynchronous receiver and the specified quality of service is provided between the adapter engine and the receiving component. etc? A: You need to use the mail package option to get mail transport specific information in the XI payload. Please look into the message monitor and find the audit log entries for this message. A: Please look at the adapter monitor in Runtime Workbench. they remain in the mail box and read again in the subsequent polling cycle. You should be able to find your mail receiver channel under the Mail adapter. Receiver Asynchronous Calls  Q: Is it guaranteed that an XI message with quality of service ExactlyOnce will result in one mail message to be sent? Last printed 9/23/2005 9:24:00 a9/p9 Page 7 of 29 . you should be able to find out if the problem is due to some communication problem with the mail server or to some mail format problem. you should look at the status right after a new message is picked up by your channel.  Q: Can I choose the name of an attachment in the mail? A: Yes. your URL should look like smtp://host/ Last printed 9/23/2005 9:24:00 a9/p9 Page 8 of 29 . the message is resent. By analyzing the captured message.ö. the cause of this problem can be identified. and Content-Disposition. if your server is called host. Most mail gateways do not support quality of service. The captured messages can be saved in a file. you can use the MessageTransformBean module (Note 793922) in the adapter framework. If some error occurs.Adapters in Detail A: No. How can I preserve these characters? A: First. To capture the mail message. For example. If you want to change or set all of these headers. the adapter simply sends the message. you must temporarily change the mode to either of the other two and capture the mail message. 9. When you create an XI message. 8. your URL can be written as pop://host:port/ where port is the port number  Q: How can I configure my sender channel for my SMTP server? A: You can specify your SMTP server as URL. the mail message sent out from the mail adapter represents each payload of the original XI message passed to the mail adapter.ü are corrupted in my mail. if your server is called host and your folder is called MyInBox which is in another folder called path. the XI payload name is automatically set in the Content-Description. please make sure that the payload passed to the mail adapter contains the correct characters. When XIPAYLOAD with the mail package is used. Please see the included documentation for this tool for more details. Therefore. Most mail clients use some heuristics based on some MIME headers to derive the name of an attachment. the mail message is created from the mail package payload of the XI message. When XIALL or XIPAYLOAD without the mail package is used. you can analyze the problem by capturing the mail message sent out form the mail adapter. The reason for the corrupted characters is most likely caused by the corrupted original payload or the incorrect character code setting in the payload. For example. Therefore. your URL can be written as imap://host:port/path/MyInBox where port is the port number  Q: Which URL do I need to specify for some POP3 folder? A: You can specify your POP3 server as URL. ContentDescription. your URL should look like imap://host/path/MyInBox If your server runs on another port than the default IMAP4 port (143). Other Receiver related Questions  Q: Some characters such as ä. This tool can be placed between the mail adapter and the mail server to capture the messages. For example. Therefore. your URL should look like pop://host/ If your server runs on another port than the default POP3 port (110). The MIME headers involved in most heuristics are Content-Type. if your server is called host. you can use TCPGateway described in Question "Can I monitor what my mail adapter sends or receives from the mail server?" to capture the mail message. Other Questions  Q: Which URL do I need to specify for some IMAP4 folder? A: You can specify your folder as URL.  Q: What is the purpose of the XIALL mode? A: This mode allows the transport of an XI message over some mail gateways. See question "Which information must be included in a problem report?". and provide the necessary information.zip for more details.  Q: Can I monitor what my mail adapter sends or receives from the mail server? A: The mail protocols such as IMAP4. What can I do? A: Please open a problem report...  Q: Which information must be included in a problem report? A: The following information must be included:    Description (participating components and concrete problem) Adapter Version SP and patch numbers of SAPXIAFC and SAPXIAF For receiver problems The channel setting Last printed 9/23/2005 9:24:00 a9/p9 Page 9 of 29 .. for POP3 over SSL. 995.. For specific usage. your URL can be written as smtp://host:port/ where port is the port number  Q: Which user authentication mechanism is supported by the sender adapter? A: The plain authentication and the CRAM-MD5 based authentication are supported(CRAM-MD5 support from SP11).. The client certificate based authentication is not supported. and smtps://. You can configure any TCP gateway or monitor tool to capture the data. describe the problem.  Q: What is the purpose of the XIPAYLOAD mode with MailPackage? A: The mail package format (Mail) allows some of the mail transport specific information to be included in the XI payload. All the information contained in the original XI message at the first system is reconstructed at the second system. pops://. they should be given in the URL.  Q: My receiver adapter is still not working. 465. You can configure a mail rerceiver adapter at one XI system and a mail sender adapter at another XI system to transport XI messages between these two systems.  Q: Can I use SSL for the connection to my mail server? A: Yes. for SMTP over SSL. 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?".. for IMAP4 over SSL. You can use URL imaps://. POP3.  Q: My sender adapter is still not working. and SMTP are TCP based protocols. please refer to "How to use MailPackage in Sender?" and "How to use MailPackage in Receiver?". If the ports differ from the respective default ports (993. You can find a tool called TCPGateway in the attachment section of the SOAP Adapter FAQ note 856597.Adapters in Detail If your server runs on another port than the default SMTP port (25). respectively). Please see tcpgw. It is only visible under XI 3.1.Adapters in Detail The The The The message entry from the adapter's message monitor in Runtime Workbench. Functions and architecture 2. See also: "Java Message Service". 3. a function was introduced for the correlation of messages. Documentation 1.  Q: My client gets no connection to the adapter's URL. Execute the same operation with the location com->sap->aii>af->service->jms if you want to log the JMS Adapter service. port is the port number.1. Question: Can I release or read JMS message properties (for defining JMS message properties (see the above mentioned book. MonsonHaefel/Chappel. Question: Does the JMS Adapter support JMS topics (publish&subscribe)? Answer: No. you cannot release JMS message properties. respectively.com and select Documentation->SAP NetWeaver->SAP NetWeaver '04 (SPS xx) there (English or German)->Process Integration->SAP Exchange Infrastructure->Runtime->Connectivity->Adapter->JMS Adapter 2. select the J2EE service "Log Configurator" and select the "Locations" tab. In this case.sap.0 Support Package 12. A JMS string property can be read in the same way to set XI message Ids. 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 where host is the host name. How do I switch on the logging? Answer: Start the J2EE Visual Administrator.. XI message that is passed to the adapter mail message that is posted to the mail server if available vendor information of the mail server  For sender problems The channel setting The message entry from the adapters' message monitor or from the error message folder in Runtime Workbench The mail message that is fetched by the adapter The XI message that is passed to the adapter engine if available The vendor information of the mail server JMS Adapter FAQ 1. Last printed 9/23/2005 9:24:00 a9/p9 Page 10 of 29 . page 102 ". and c is the channel name. Logging 3. Question: Where do I find the JMS adapter documentation? Answer: In the SAP online help. O'Reilly Publishers. s the service name.2.1 Question: I have a problem and would like to use the J2EE logging for the analysis. With XI 3. see <Hyperlink>http://help.0 Support Package 0 and Service Release 1 and unfortunately cannot be removed technically between Support Package s. Appendix C)? Answer: No.2 Question: What is the com->sap->aii->adapter->jms logging location used for? Answer: It is not used for anything. the once-and-onlyonce is in doubt". The JMS Adapter works with JMS queues because 100% Exactly Once (In order) service quality can only be guaranteed with JMS queues. 3. which allows you to create XI message IDs on JMS string properties. This location is obsolete and is not used. p is the optional party name. 2. Open the com->sap->aii->af->mp->jms->ejb there and set the log severity to "Debug" to log the JMS Adapter modules. SOAP Adapter FAQ 1. 0-596-00065-5 2001..  Q: I get the invalid channel error even though I have configured the corresponding channel in the directory. The possible causes can be "No SOAP envelope".Adapters in Detail A: Make sure that the adapter is running at the specified URL. the SOAP adapter servlet runs on the engines HTTP port. This parameter is not recognized in systems prior to SP13. p is the optional party name. For example. and c is the channel name. This setting may be modified from Visual Administrator with some restriction. Can I increase the default timeout value? A: Yes. value 600000 represents the timeout value of 10 minutes. The page should show a status page with status "OK". If your SOAP client cannot display this detailed error information. s the service name. This will show a page with the channel information if the channel is available. Please consult the documentation for Visual Administrator to view and change the security setting. respectively. You can increase this value by setting parameter XI. http://host:port /XISOAPAdapter/HelperServlet?action=FindChannel& channel=p:s:c where host is the host name. 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 timeout value for synchronous calls is 5 minutes.  Q: I get a permission error "403 Forbidden" from the adapter's servlet. You must use one of the user names assigned in security role xi_adapter_soap_message for component XISOAPAdapter. port is the port number.Timeout in the module parameter table of the SOAP adapter. you can open the following URL from your browser.  Q: Can I use SSL for my sender adapter? A: Yes. please capture the message using some tool (See question "How can I trace the whole message?"). In this case. Setting the channel's quality of service to ExactlyOnce guarantees the delivery of the Last printed 9/23/2005 9:24:00 a9/p9 Page 11 of 29 . But you can activate the engine's HTTPS port so that this servlet can receive messages sent to the HTTPS port. Please refer to the security documentation for the J2EE engine. 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. Normally. please make sure that your channel name is correct and the adapter engine's CPA cache is valid. the error message returned should be a SOAP fault message containing the detailed error information. What went wrong? A: The adapter's servlet is protected by default.  Q: My SOAP client gets a SOAP fault that indicates timeout in calling the adapter engine.xml descriptor file of the SOAP dapter web application.  Q: I get a server error "500 Internal Servler Error" from the adapter's servlet. "invalid channel". Use your browser to open the URL for your SOAP sender channel. The default authentication setting is defined in the web. The value must be given in milliseconds. See the documentation about the J2EE engine's security configuration. A: To check if the channel is available. 2. "no receiver agreement". What went wrong? A: There are several possibilities.  Q: I get an authorization error "401 Unauthorized" from the adapter's servlet. 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. What went wrong? A: It is likely that the URL is incorrect or the adapter is not correctly deployed. etc. If the channel is not available. Those messages that arrived at the SOAP adapter but resulted in some error are shown in the error message box of the message monitor.&MessageId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is a GUID string. When the client resends the message.&QueueId=xxxxxxxxxxxxxxxx where xxxxxxxxxxxxxxxx is an ABAP queue ID. It could be a connection error. What can I do? A: You need to find out what exaclty this error is. there is a possibility that the message may arrive more than once. 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.. However. Related Questions "What are the options for asynchronous calls?" 3. In this case. See question "How can I trace the whole message?". 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). In either case.Adapters in Detail message exactly once between the adapter and the back end. If your client itself does not provide detailed information. When the client sends a SOAP message and ignores the response completely as in "fire-andforget". parsing error. Other Sender related Questions  Q: My SOAP client throws an error. When the message successfully accepted by the adapter. the quality of service with AtMostOnce may be realized. the client can resend the message without resulting any duplicate. when the client previously received no response message at all or an HTTP 500 with duplicate message ID error. the client must resend the message until such a successful response is returned. If you don't see your messages in the monitor. the client may send the message with a unique message ID. When the client sends a SOAP message and checks if the response is an HTTP 200 response message. this possible duplicate only happens. you should inspect the response message that your client received.. authorization error.0&. etc. In order to eliminate duplicates for all cases. you need to set up a TCP gateway between your client and the sender adapter. For all other cases. 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.  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... The behavior of the client determines the level of quality of service achieved. The response message should contain information about the cause of the error. an HTTP 200 response with an empty SOAP envelope is returned. Related Questions "How can I trace the whole message?"  Q: What character encoding is supported by the SOAP sender adapter? Last printed 9/23/2005 9:24:00 a9/p9 Page 12 of 29 . the quality of service with AtLeastOnce can be realized. Finally. 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.0&. 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. those messages that didn't even reach the SOAP adapter will not be displayed anywhere. This will not automatically guarantee the delivery with exactly once between the client and the back end. This feature is available from SP13. To check this.  Q: I get the SSL handshaking error. you can set parameter XMBWS." and the adapter will use the HTTP protocol over an SSL connection. please refer to the security setting section of the SAP J2EE documentation. which are about 5KB and not the restricted version that are about 3KB each. you must make sure that the encoding name given in the content type and in the XML declaration must be consistent.0' encoding='iso-8859-1'?> The response message from the SOAP sender is normally encoded in UTF-8.g.0' encoding='us-ascii'?> text/xml... for instance to iso-8859-1. 5. You can configure your receiver channel to use a client certificate. 300000 for 5 minutes). charset='iso-8859-1' <?xml version='1.. Receiver Connection  Q: Can I use SSL for my receiver adapter? A: Yes. The default encoding for "text/xml" is US-ASCII. A: First. From SP13.  Q: Can I use SSL with client certificate to authenticate my adapter? A: Yes. and select IAIK.01. 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. evaluation version). If you have the restricted version.XMLEncoding to iso8859-1 in the module configuration for the SOAP adapter module.Timeout in the module configuration table.g. Please make sure that: . What is the default timeout value and can I change it? A: The default timeout value for a synchronous call to the adapter engine is 5 mintues. I get some error when I call my SSL web service. please refer to http://java. charset='utf-8' no declaration text/xml. whereas the default encoding for the XML declaration is UTF-8 or UTF-16.jar and US_export_policy.0' encoding='utf-8'?> text/xml.The JDK java security lib directory ($JAVAHOME/jre/lib/security) contains the unrestricted strong version of local_policy. . please make sure that the SSL server is working correctly with another client. Last printed 9/23/2005 9:24:00 a9/p9 Page 13 of 29 . If you want to change this encoding.g.Adapters in Detail A: The SOAP sender adapter can accept any character encoding supported by the local JDK. If you have the evaludation version..jar..0' encoding='iso-8859-1'?> application/xml <?xml version='1. Related Questions "What character encoding is supported by the SOAP receiver adapter?"  Q: My sender adapter gets a timeout error from the adapter engine.The full version of IAIK is available in the J2EE engine's Security Provider. This value must be set in milliseconds (e. The Provider Information field should show the full version (e.sun. you can change this value by setting parameter XI. charset='utf-8' <?xml version='1.com/ to obtain the unrestricted version. go to Service -> Security Provider -> Cryptography Providers. When you are using a particular character encoding with content type text/xml. IAIK Security Provider v3.  Q: I cannot call an SSL web service requiring a client certificate. The following examples show several valid combinations of content-type and XML declartion: text/xml <?xml version='1. IAIK Security Provider v3. What makes this more complex is that the default values.12) and not the evaludation version (e. If the server is working and you still have the problem. You can enter any target URL with "https:. the SOAP message may contain the SOAP fault element. For synchrnous calls. your web service should return an HTTP 200 with an empty SOAP envelope.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. its content will be returned as the fault payload in an application error message.org/soap/envelope/"> <SOAP:Body> <m:GetLastTradePriceResponse xmlns:m="Some-URI"> <Price>34. the receiver adapter expects an HTTP 200 with a SOAP envelope with an empty content for successful delivery. to provide this service of quality to the server. When your web service indeed find a duplicate. a successful response should be returned with HTTP 200. depending on whether the SOAP fault contained a detail child element or not. Second. Please consult SAP Note 870845 for the correction and/or the workaround.Adapters in Detail A: If you can call an SSL web service requiring no client certificate. Any other response will result in a XI system error and triggers retries of the message. your receiver channel must be configured to pass the XI message ID to the server. your web service must check duplicates using this message ID. For others. If you are sending a message with some quality of service.1 200 OK Content-Type: text/xml. a system error message will be returned to the caller. you should configure your receiver channel to pass the XI message header information to the server. it has been changed so that the adapter generates the system error for any SOAP fault in asynchronous calls. There have been some problems reported in SP13. When you want to check duplicates in your web service. 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. HTTP/1. In this case.  Q: Can I use several HTTP proxy servers for my channels? A: Yes. please make sure that your clietn certificate is valid and correctly stored in the key store of the J2EE engine. a SOAP fault resulted in the application or system error. charset="utf-8" <SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap. First. assuming that the previous message was simply lost. When you want to check duplicates. you should configure your receiver channel to pass the XI message header information to the server. In this case. when the fault detail element is not empty. This behavior contradicted the communication model. 6. Prior to SP11. your must make sure two things. When some error occurs.5</Price> Last printed 9/23/2005 9:24:00 a9/p9 Page 14 of 29 . You can configure your proxy setting per channel. the content of the SOAP body will be returned to the caller as the response payload.  Q: What should my web service return to the adapter for asynchronous calls? A: Currently. 7. Therefore. Other Receiver related Questions  Q: What should my web service return to the adapter? A: The receiver adapter expects a SOAP message as response. See question "How can I trace the whole message?".1 500 Internal Server Error Content-Type: text/xml.  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. What happened? A: The most likely cause is the wrong target URL or invalid authorization given in the channel configuration. If the problem persists.  Q: My receiver adapter received an HTML page instead of a SOAP XML. When your scenario is configured correctly. you need to trace the transported messages. see "What should my web service return to the adapter for asynchronous calls?".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.xmlsoap. What happened? A: See question "My receiver adapter received something other than the SOAP envelope". charset="utf-8" <SOAP:Envelope xmlns:SOAP="http://schemas.Adapters in Detail </m:GetLastTradePriceResponse> HTTP/1.1 500 Internal Server Error Content-Type: text/xml.xmlsoap. Please make sure that these values are correct.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. charset="utf-8" <SOAP:Envelope xmlns:SOAP="http://schemas. HTTP/1.  Q: My receiver adapter received something other than the SOAP envelope. your message should be displayed in the Last printed 9/23/2005 9:24:00 a9/p9 Page 15 of 29 . How this first step works is controlled by the SOAP encoding name. the XI application payload of the request message is directly sent to the web service and its response is returned in the XI application payload of the response message. You must make sure that your XI proxy is generating the valid payload according to the given WSDL in whatever the style. 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 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. What can I do? A: Please open a problem report. See question "Which information must be included in a problem report?". Some special objects such as references and arrays must be Last printed 9/23/2005 9:24:00 a9/p9 Page 16 of 29 . 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 adapter has successfully send your message to your web service. The request message from the SOAP receiver is normally encoded in UTF-8. The SOAP receiver adapter returns the response message containing the SOAP response message in its XI application payload.g. If you want to change this encoding. And this corresponds to how the XI payload is represented. you need to configure some mapping to match the payload. If your original XI application payload is not represented as a SOAP message. Other Questions  Q: My sender adapter is still not working. your proxy is generated by another WSDL and there is a mismatch in how the payload must look). the RPC style WSDL describes how one can bind an object to the SOAP message format. you need a mapping to map your XI payload between its original format and its SOAP format. 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. In this mode. In contrast. 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. any code page supported by the local JDK is accepted. 8.Adapters in Detail message monitor.  Q: My receiver adapter is still not working. These styles are used in WSDL to describe how the message is represented as a SOAP message. 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. Related Questions "What character encoding is supported by the SOAP sender adapter?"  Q: My web service returns a SOAP with multiple elements in the SOAP body but I can see only the first element in the XI main payload.XMLEncoding to iso-8859-1 in the module configuration for the SOAP adapter module. you can configure the channel to run in the noSOAP mode. If there is no error for your message. This setting is for the outgoing SOAP message and has no effect on the incoming SOAP message. most objects can be easily described in an equivalent XML schema. and provide the necessary information. For the standard encoding specified in the SOAP specification. 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. you can set parameter XMBWS. If the SOAP message contains more than one elements in its SOAP body.. for instance to iso-8859-1. If this is not the case (e. describe the problem. For the incoming SOAP message. htm for more details. this is done by either inseting a TCP gateway between the client and the server or non-invasively using some packet catching utility. The WSDL file for the web service if available. The SOAP message that the adapter is sending to the web service.  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. Typically. The vendor information of the web service. Some tools are known to store the captured messages as text and corrupt some characters.  Last printed 9/23/2005 9:24:00 a9/p9 Page 17 of 29 .Adapters in Detail 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. you need to analyze the messages that are transported. If one has to call such non conformant SOAP service. one must adjust the message accordingly. this does not automatically guarantees the interoperability. You can find a tool called TCPGateway in the attachment section of this note (stored in tcpgw.  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. 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. For sender problems:   Screenshots of the SOAP channel configuration. The SOAP message that the client is sending to the adapter. One must however note that even if one has an equivalent document style WSDL. You are free to use any tool but make sure that the tool can capture the messages as raw bytes. 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. zip contains some examples of WSDL documents and sample SOAP messages that illustrate how one can write an equivalent WSDL in another style. Please unpack this zip file and open index.zip). The audit log information from the failing message's audit log. The audit log information from the failing message's audit log or the error log for nonpersisted messages. The SOAP message that is known to work for the web service. Attachment wsdl_style_samples. &apos. many JDBC drivers and/or database management systems aren't by default and need a codepage or Unicode-awareness to be configured explicitly. This conversion function will be embedded by the JDBC Receiver into the SQL statement sent to the DBMS.sap. I always get an error about a data type conversion error.com/instguidesNW04. Please note: For the Lotus Domino Driver for JDBC. we need to make sure that the JDBC Adapter does not quote the date parameter. which are documented in note 850116.. 2. However. This answer will first describe a generic approach to implement this functionality and then provide examples for popular DBMS. we need to use a conversion function to convert a string into a DBMS-specific date type. For Type 2 drivers. As the XML document used by the JDBC Receiver is based on character strings. This can be achieved by setting the hasQuot attribute of the respective date field's XML element to "No". the data inserted into or retrieved from the table appears garbled. Date Field Handling  Q: I would like to insert a date field into a table using the JDBC Receiver Adapter. this codepage setting is often configured via the driver URL. However. What is the procedure to insert a date field using a JDBC Receiver? A: The actual implementation depends on the DBMS you are using. where the date conversion function is named TO_DATE: <DateField hasQuot="No">TO_DATE(&apos." in order to yield valid XML. For the respective JDBC drivers. For the Microsoft SQL Server DBMS.2004-07-20 08:00:00&apos. which is available on the SAP Service Marketplace under the URL: http://service. any occurrence of an apostrophe within the element data needs to be written as "&apos. For Type 4 drivers. In order that the DBMS actually executes the conversion function and does not treat it as a string. JDBC Adapter FAQ 1. The vendor information of the client.)</DateField> As you can see. Why doesn't the JDBC Adapter handle Unicode correctly? A: While the JDBC Adapter is Unicode-aware.0 Configuration Guide.1 of the SAP XI 3.  3.sda which is shipped as an empty stub with your XI installation. All DBMS offer some kind of functionality to convert one data type into another data type.Adapters in Detail   The response message that the client is receiving from the adapter. JDBC Driver Deployment   Q: How do I deploy the JDBC Driver JARs required to connect the JDBC Adapter to my DBMS? A: The JDBC driver deployment is performed using a special SDA file named aii_af_jmsproviderlib. there does not seem to be any documented method to enable support for Unicode strings. Unicode Handling  Q: I am inserting Unicode data into a database table or selecting Unicode data from a table. the statement looks as follows:  Last printed 9/23/2005 9:24:00 a9/p9 Page 18 of 29 . An example for the Oracle DBMS. please refer to the documentation of your JDBC driver or database management system.yyyy-mm-dd hh:mi:ss&apos. additional configuration steps are required. For details. information how to add your JDBC drivers to this SDA is available in section 11. 5.  6. For details.0" encoding="UTF-8" ?> <root> <stmt> <Update action="SQL_DML"> <access> UPDATE TABLE SET Name='$NAME$' WHERE ID='$ID$' < /access> <key> <NAME>Joe's Name</NAME> <ID>42< /ID> </key> </Update> </stmt> </root> When executing the resulting query. The actual escape character to use depends on your DBMS. the Adapter Monitoring shows the following error message: Last printed 9/23/2005 9:24:00 a9/p9 Page 19 of 29 .2005-01-01 01:23:45&apos. 4. Transaction Handling (Receiver)  Q: I have configured a JDBC Receiver channel with Auto Commit disabled. Are all statements of the XML payload executed within one transaction as a single LUW? A: Yes. Apostrophe Escaping for SQL_QUERY/SQL_DML with Placeholders  Q: I am sending a SQL_QUERY or SQL_DML statement that makes use of placeholders to a JDBC Receiver. &apos. Please make sure that the XML payload that you send to the JDBC Receiver already uses the correct escaping for apostrophes if you want to use the placeholder within a quoted string of your SQL statement. which looks as follows: <?xml version="1. please refer to the MS SQL Server documentation (Books Online -> Contents -> Transact-SQL Reference -> CAST and CONVERT). When sending a message to the receiver..Adapters in Detail <DateField hasQuot="No">CONVERT(DATETIME. there are other scenarios where this is not the case so that the JDBC Receiver cannot just unconditionally escape any apostrophe character occurring within a placeholder string. For details. 120)</DateField> The third parameter specifies the date format expected by the CONVERT function. refer to the respective DBMS documentation. Lotus Domino with JDBC Receiver  Q: I am using a JDBC Receiver Adapter in conjunction with the Lotus Domino Driver for JDBC perform an INSERT or UPDATE operation on a database. Please note that versions older than SP11 Patch Level 1 performed an implicit commit in conjunction with certain DBMS when a database error occurred. my DBMS reports an error similar tothe following one: "SQL command not properly ended" Why doesn't the JDBC receiver escape the apostrophe I use within my placeholder's data?  A: While it would make sense to automatically escape the apostrophe in your example where the placeholder becomes part of a quoted string. all statements contained in an XI message sent to the JDBC Receiver are executed as one atomic transaction. refer to note 823809. For details. Consequently. Additionally. Make sure that both statements use the same WHERE clause. The use of the J2EE engine's JDBC Connector and connection pooling mechanism is not supported. each JDBC channel will create its own JDBC connection. both statements have the same view on the database. Please note that this might put additional load on your DBMS due to the creation of a new database connection for each message. 8. make sure that the setting "Database Auto-Commit Enabled" is also active as the Lotus Domino Driver for JDBC does not support transactions.  Last printed 9/23/2005 9:24:00 a9/p9 Page 20 of 29 .sql. If you are connecting to an Oracle database. How can I work around this connectivity issue?  A: Enable the "Advanced Mode" for the respective JDBC Adapter channel and select the option "Disconnect from Database After Processing each Message". Please apply note 846079 before configuring this scenario. i.e.e.SQLException: [Lotus][Domino Driver for JDBC]Invalid cursor state" Is there a fix for this issue?  A: To work around this JDBC driver problem. repeatable_read or serializable). 9. An additional requirement for the correct operation of this scenario is the configuration of an appropriate transaction isolation level on the database (i. You might also consider using a "SELECT FOR UPDATE" statement instead of a plain SELECT statement to ensure proper locking on the database. 7. I sporadically receive an SQLException regarding a closed connection in the system trace or audit log or the connection as well as the JDBC Adapter channel are hanging. Network-Level Connection Problems  Q: The TCP/IP connection to my database host is running over an unreliable network connection..Adapters in Detail "java. please also refer to question #10 for an alternative solution. i. please activate the Advanced Mode for the respective JDBC Receiver channel and configure the setting "Number of Retries of Database Transaction on SQL Error" to a value > 0. J2EE JDBC Connector and Connection Pooling  Q: Does the JDBC Adapter support the use of the SAP WebAS J2EE engine's JDBC Connector and connection pool? A: Currently.e. the connection is sometimes interrupted. Transaction Handling (Sender)  Q: If I have the following configured in a JDBC Sender: Select Query: SELECT column FROM TABLENAME WHERE FLAG = "TRUE" Update Query: UPDATE TABLENAME SET FLAG = "FALSE" WHERE FLAG = "TRUE" How do I know that the JDBC adapter will not update newly added rows (rows that were added between the time that the SELECT and UPDATE queries were executed) that were not read in the initial SELECT query?  A: The SELECT and the UPDATE are run in the same DB transaction. Unfortunately. ensure that the new version is still compatible with your Oracle database server release. but not with Java 1. However. it will do so for a system acknowledgement request. Please upgrade to a current driver (ojdbc14. Operating System Command  Q: I am having difficulties getting an external operating system command to work. JDBC Drivers   Q: Which JDBC driver do you recommend to connect to <DBMS>? A: SAP does not recommend a certain JDBC driver for use with the JDBC adapter.sda prior to adding the new driver as per the instructions in the answer to question #1 above as you will get a class name collision otherwise (all JARs from aii_af_jmsproviderlib.3 only.  A: The Oracle classes12. the JDBC Adapter has no functionality that relies on the receipt of an acknowledgement.jar from aii_af_jmsproviderlib.jar) Deadlocks  Q: I have deployed the Oracle classes12. which is what a positive application acknowledgement would imply. please refer to the release notes provided by Oracle. the J2EE Engine becomes very slow and some services start to block. which does support the Java 1.sda are loaded into the same class loader and the driver class name of both driver versions is the same). The receiver of an XI message will only send an acknowledgement back to the sender if the sender has requested one. Please contact the vendor of your database management system for any recommendations. 11.4 JVM you are using. Please make sure that you remove classes12.zip / classes12.jar driver is compatible with Java 1.Adapters in Detail 10. if a JDBC Adapter Receiver receives a request to send an acknowledgement. On the other hand.4.zip / classes12.2 and Java 1. so it never requests one. A thread dump taken according to the instructions in note 710154 shows one or more blocking JDBC Sender/Reciver threads and optionally that the JVM has detected a deadlock.  12. 14. 13.jar). What can I do to diagnose the problem? A: Refer to note 841704.zip / classes12. For details.jar JDBC driver as per the instructions in the XI Configuration Guide. How can I solve this issue? Last printed 9/23/2005 9:24:00 a9/p9 Page 21 of 29 .zip / classes12. Application acknowledgements are not supported at all as the JDBC Receiver has no way to determine if the data written to the database has been correctly processed by the back-end application. Oracle JDBC Driver (classes12. Acknowledgements   Q: Does the JDBC Adapter support acknowledgements? A: You need to distinguish system acknowledgements (indicating that a message has been received by the target system) and application acknowledgements (indicating that the message has been successfully processed by the application on the receiver side). Before deploying the updated driver. I frequently notice hanging database connections. JDBC Sender: Performance Issues After Configuring A Large Amount Of Channels  Q: After configuring a large amount of JDBC Adapter sender channels. 5. Q: Which transport protocol is used during communication between BcAdapter and BC? A: The transport protocol is always HTTP (or HTTPS) as configured in the communication channel. 4. When sending this document to BC. is supported. 7. Q: Which version of Business Connector is supported by the BcAdapter? A: BcAdapter supports the SAP Business Connector 4. < host> and <port> are the configured values of the SAP J2EE Engine.0 BcAdapter.0 SAP Business Connector Adapter". For sender channels this special form of the RFC-XML document with envelope. like known by the XI Integration Repository. Starting with XI 3. Q: How does a 'RFC-XML with envelope' document look like? A: Such a document basically is a normal RFC-XML document like it is generated by the SAP XI RfcAdapter sender channel. What does this mean? A: When the BcAdapter receives a document that is not of type 'RFC-XML' or 'RFC-XML with envelope' this error happens. be created with the XI RfcAdapter.0 SP13 each JDBC Adapter sender channel permanently consumes a J2EE application thread. BC Adapter FAQ 1. Q: Which quality of service (QoS) is supported? A: For receiver channels QoS BE (Best Effort) will result in a synchronous call (sRFC) . as created by the BC. increase the number of configured J2EE application threads using the SAP J2EE Engine Config Tool ("cluster-data" -> "Global server configuration" -> "managers" -> "ApplicationThreadManager" -> "MaxThreadCount"). 9.7. For sender channels a synchronous call (sRFC) will result in a message with QoS BE. a transactional call (tRFC) will result in a message with QoS EO.0"> < sap:Header xmlns:rfcprop="urn:sap-com:document:sap:rfc:properties"> < saptr:From xmlns:saptr="urn:sap-com:document:sap:transport">FROM</saptr:From> < saptr:To xmlns:saptr="urn:sap-com:document:sap:transport">TO</saptr:To> < rfcprop:Transaction>TID</rfcprop:Transaction> </sap:Header> Last printed 9/23/2005 9:24:00 a9/p9 Page 22 of 29 . Q: What is discussed in this document? A: This document discusses questions about the XI 3. Q: Which type of documents can be processed with the BcAdapter? A: The BcAdapter supports only RFC-XML documents.Adapters in Detail  A: Up to and including XI 3. Q: Are there some terms used with respect to this FAQ? A: The abbreviation BC is used for the "SAP Business Connector". Q: What is the URL for BC Adapter sender channels? A: The URL is <protocol>://<host>:<port> /MessagingSystem/receive/BcAdapter/BC The values for <protocol>. Here is a example of this envelope: < sap:Envelope xmlns:sap="urn:sap-com:document:sap" version="1. Q: A error message like 'XRFC_DOC_TYPE_UNKNOWN not supported as Payload' is raised. For receiver channels a normal RFCXML document is supported. QoS EO (Exactly Once) will create a transactional call (tRFC) to the BC. 8. As addition this type of document is wrapped in an XML envelope. so thread shortage situations will typically occur much more rarely than with earlier SPs.0 SP14 application threads are allocated on demand by the JDBC Adapter and returned to the thread pool after it has finished the polling sequence. Such a document can e. To solve this issue. See question 4 for more information on supported document types. 2. 3. BcAdapter does a conversion into the special form of RFC-XML with an envelope that BC expects. The <protocol> value can be http or https. BcAdapter for the "XI 3. QoS EOIO is not supported by the BC-Adapter.g. Such a document will be converted by the BcAdapter into the normal form. 6. 'TO' in this example. Namespace: The namespace of the root element tag of the normal RFC-XML document enclosed by the Body-tag of the 'RFC-XML with envelope' document.g. Q: How is the XI header build from the payload in a BC sender channel?  A: A BC Adapter sender channel expects a 'RFC-XML with envelope' document like described in Q9. The result is a 'RFCXML with envelope' document (like described in Q9). This RFC-XML document is wrapped into an envelope. The Header-fields of this document are filled from the XI message header fields after this scheme:  From: A lookup of the adapter-specific identifier (RFC) for the XI message sender Party/Service is done. To: The receiver of this document. the fields System-ID and Client are concatenated and used as To. 10. The tag 'From' must be a concatenation of the SYS-ID and the client of the sending SAP-System e.  Last printed 9/23/2005 9:24:00 a9/p9 Page 23 of 29 .Adapters in Detail <sap:Body> NORMAL RFC-XML DOCUMENT </sap:Body> </sap:Envelope> Here is an explanation of the individual tags. because the XI receiver is determined during the routing step in the Integration Server. To: A lookup of the adapter-specific identifier (RFC) for the XI message receiver Party/Service is done. a XI message with the following header fields is created:      Sender Party: "" Sender Service: The XI service found via the adapter-specific identifiers (RFC) Reciver Party: "" Receiver Service: "" Interface: The name of the root element tag of the normal RFC-XML document enclosed by the Body-tag of the 'RFC-XML with envelope' document. This also has to be upper case. Body: The normal RFC-XML document is enclosed by this tag. Transaction: If the document represents a synchronous call (sRFC). 'FROM' in this example. 11. If it is not found. 'ABC123'. Only partyless services are taken into account during this search. The value of the 'To'-tag is ignored. 'TID' in this example. This way a partyless service is found in the Integration Directory. For a asynchronous call (tRFC). If it is found.    From: The sender of this document. The value of this field is matched to the adapter-specific identifiers (RFC) in the Integration Directory. the fields System-ID and Client are concatenated and used as From. If it is not found. the name of the XI message receiver Service is used as To. If this procedure is successful. the name of the XI message sender Service is used as From. the whole tag can be omitted. If it is found. the value enclosed by this tag must be the tRFC TID. Q: How is the 'RFC-XML with envelope' document build from an XI message for BC Adapter receiver channels?  A: A BC Adapter reciver channel expects a RFC-XML document like it is produced by a SAP XI RfcAdapter sender channel. RFC Adapter FAQ Q 1: What is discussed in this document? A: This document discusses questions about the XI 3.0 this Adapter Engine was renamed to 'J2SE Plain Adapter Engine' and does no longer contain a RFC Adapter. Once if a particular metadata has entered the cache.0. When you are connected to the J2EE Engine choose the tab 'Cluster' and open the appropriate server node in the tree. Q 10: What's about BAPIs? Last printed 9/23/2005 9:24:00 a9/p9 Page 24 of 29 . This only will be done for the RFC-XML document.. Q 4: Where can the RfcAdapter communication channels be configurated? A: The channels for the RfcAdapter can be configurated within the XI Integration Builder: Configuration (Integration Directory). This document only describes the J2EE RfcAdapter.Adapters in Detail  Transaction: If the XI message is asynchronous (QoS EO) this tag is filled with a TID representing the XI message-ID. With SP11 a XI EOIO-messages will result in a normal tRFC call. When you open the context menu on this entry you can start and stop the service. The caches for all communication channels are cleared when the J2EE Engine is restarted. 'SAP XI AF Messaging'). Q 8: Is is possible to issue several RFC calls within one context for RFC receiver channels? A: No. The first one came with XI 2. the cache is filled from the configured RFC metadata repository. It is based on the SAP J2EE Application Server and contains a new RfcAdapter. Then open the 'Services' node.0 RfcAdapter. Messages with exactly once in order (EOIO) are not supported till and including SP10. there is new Adapter Engine called 'J2EE Adapter Engine'. only this one is used and no lookups to the RFC metadata repository are made for this type of metadata. There you can see the entry 'SAP XI Adapter: RFC'. Q 7: Can there be multiple function module calls within one transaction for RFC sender channels? A: RfcAdapter will only support transactions (sometimes also called LUW) with one call. With XI 3. Each call will get it's own context because different connections to the receiving system can be used. When the particular data is needed during runtime. This is done because within XI there is no transactional context between messages and each RFC call is wrapped into one message. Enter a name for the new channel and choose 'Create'. A sRFC will result in a synchronous best effort (BE) message. Q 3: How can the RfcAdapter be started and stopped? A: The RfcAdapter is implemented as a J2EE Service and thus this service has to be started and stopped. the RfcAdapter J2EE Service 'SAP XI Adapter: RFC' is restarted or a dependend J2EE Service is restarted ('SAP XI AF CPA Cache'. Open the business system for which you want to communicate via RFC and choose 'New' from the context menu on the node 'Communication Channel'. which runs as a Service of the J2EE Server. Q 9: Which flavous of RFC are supported? A: RfcAdapter supports synchronous RFC (sRFC. this metadata cache is cleared. If the XI message is synchronous (QoS BE) the whole tag is suppressed.). This will affect the whole RfcAdapter and can be done from the J2EE Engines Visual Administrator. If an attempt is made to place a second call within one transaction an exception is raised. Instead. a context between several RFC calls can not be held. This means it caches the definition of function modules. structures and other datatypes. Q 6: Is there a special handling of the '/' character in the names of function modules? A: As the '/' character can cause conflicts within XML documents it is escaped with the sequence '_-'.0 and was part of the Adapter Engine. a tRFC in a asynchronous exactly once (EO) and vice versa. Queued RFC (qRFC) with inbound queues is not supported. sometimes also called only RFC) and transactional RFC (tRFC). For 'Adapter Type' you have to choose 'RFC' (via the F4-help). Q 2: Is there more than one version of a XI RFC Adapter ? A: There are two kinds of RFC Adapters. If a tRFC is send to a SAPsystem it will be executed directly (in other words synchronous) plus the tRFC exactly once handling. If the communication channel is changed within the Integration Directory and gets replicated to the appropriate Adapter Engine (see Environment -> Cache Notifications. with XI 3. A RFC sender channel will do the escaping of '/' to '_-' and a RFC receiver channel will do the opposite. A separate cache is used for each communication channel. Choose tab 'Objects' and open 'Service without Partner' -> 'Business-System'.. Q 5: What's about cache memories within the RfcAdapter? A: The RfcAdapter has a cache for the metadata of function modules. The order of the messages belonging to one EOIO-queue will be guaranteed by the Adapter Framework messaging layer. . Anyway you have to keep in mind that this can compromise the quality of service (QoS) which was guaranteed by the original message. because the receiver system at least will send back a indication that the execution has finished. So the RfcAdapter will generate an error (like timeout. The RfcAdapter will use one which is called 'localejbs/RfcAFBean'. If some custom modules are configured to be Last printed 9/23/2005 9:24:00 a9/p9 Page 25 of 29 . If it is required that multiple update BAPIs get commited together within one transaction. If the list is empty on this tab. the tRFC-subsystem of the SAPSystem will issue this commit by itself.). a message with QoS EO will lead to a (asynchronous) tRFC call. it is a good idea to use the IDoc implementation of a BAPI. so database update BAPIs may have a problem. It will treat a response value of any kind as a successful execution because it does not implement some BAPI application logic. Q 11: Is there something to know about the module processor? A: Any adapter need a EJB to communicate with the module processor of the Adapter Engine. But during the sending of the return value a problem occurs (like network.  The message was send synchronous with QoS BE (which will result in a synchronous RFC call. BAPIs can be implemented as RFC enabled function modules or IDocs. it can be put in a wrapper RFC function module which first calles this BAPI. Thus. everything will work without a special configuration. it defaults to the EJB named above and nothing has to be done.). also called sRFC). The call reaches the receiver system and the function module is executed successful with the commit at the end.). This can also happen if there even is no return value in the function module. If it is required that one update BAPI is called. In either case the wrapper RFC function module can be called by RfcAdapter. Within RfcAdapter there is no special handling of transactions like a commit.. these BAPIs can be encapsulated in a wrapper RFC function module which first calls the BAPIs and at the end does the commit of the transaction depending on their execution result. This can be configured in the Integration Directory for each communication channel on the tab 'Module'. The RFC function module implementation of a BAPI will not only report it's result in the synchronous response. if the communication should be asynchronous. Imagine these two possibilities: a synchronous message with QoS BE or a asynchronous message with QoS EO. Error. Some mechanism within the application has to deal with this type of problems. By their nature the RFC functionen modules are synchronous. The call reaches the receiver system and the function module is executed successful with the commit at the end. there will be no response and also no knowledge about the execution status. .. also called tRFC). The message was send asynchronous with QoS EO (which will result in a transactional RFC call. .  To handle this behaviour the approach to call a BAPI via a wrapper function module will not solve the problems described above.. the Adapter Framework Messaging.. But during sending back the indication that the RFC call was executed (which actually will be synchronous) a problem occurs (like network. So if no modules should be used..Adapters in Detail A: The following only applies to RFC receiver channels. BAPIs with a database update or write functionality expect a special form of commit to actually fulfill their tasks because they (often) use the SAP update technique.. . Nevertheless the RfcAdapter will treat each RFC call like described in Q 9: A XI message with QoS BE will lead to a (synchronous) sRFC call. . If the BAPI RFC function module is called (asynchronous) via tRFC. If the RFC call to such a function module was asynchronous. So updates will be possible but the problem with the missing execution result persists. The RfcAdapter will generate an error and send it back to it's persistency layer. the receiving system tRFC implementation decides whether the call was already successfully received or not.. does the interpretation of the execution result and than does the commit or rollback of the transaction. the RfcAdapter does no special handling for this values. This guarantees the exactly once protocol of the tRFC implementation.) and send this one back to the sender of the message. The following can be considered to use BAPIs with RfcAdapter regarding the interpretation of the execution result and the commit of the transaction. When send again. the IDocs are asynchronous. The message now marked as erroneous will be scheduled for a new execution because for messages with QoS EO the delivery will be guaranteed. It also will report it's execution status (like Success. Even if the RFC call was synchronous. As seen in this example the sender will not know if the message (containing the RFC call) has reached the receiver system and also it will not know if the execution happened in the receiver system. To change it's value open the service properties sheet like described in Q3 and change the value of "syncMessageDeliveryTimeoutMsec". This is also called metadata or function template. this fields will be filled automaticaly for services of type "Business System" and can be updated with the button "Compare with System Landscape Directory".ms. In this format the root element of the XML document represents the name of the function module and is enclosed in the fixed RFC namespace 'urn:sap-com:document:sap:rfc:functions'. when the conversion from XML to native RFC is done. To get this function template the name of the function module is extracted from the root element of the XML document and is queried against the metadata repository of the communication channel.rfc' shows up with the current serverity. Normally this should be an XML document in the RFC-XML format. The timeout used by RfcAdapter for synchronous calls can be configured for the whole RfcAdapter as a property of the RfcAdapter J2EE Service. After this it will wait till the responsemessage reaches or the timeout expires. is not a RFC-XML document. Q 17: How can settings affecting the whole RfcAdapter be made?  Last printed 9/23/2005 9:24:00 a9/p9 Page 26 of 29 . In case of timeout the exception named above is thrown. As prerequisite of this conversion the structures and types of the function module parameters has to be known. the exception named above is thrown. Normally this will be a name like sapgwXX.sap.Adapters in Detail used. The metadata repository doesn't contain an entry for this function module name. This value also can be looked up in the gateway monitor. Choose tab 'Locations' and open com->sap->aii->af then choose the location 'rfc'.aii. The values in the fields "R/3 System ID" and "Client" has to be maintained with the correct values of the system. Within this service choose "Service" -> "Adapter-Specific Identifiers".. A dialog box will open upon save which can perform the restart after choosing 'Yes'. This will establish the communication between the adapter and the Adapter Engine. Which reasons are possible? A: After receiving a message from the Adapter Engine. Set this serverity level to 'Debug' and also click on the button 'Copy severity to subtree'. Save these changes with the save button. After changing the property store the properties by clicking the save-button (disk symbol) on top of the page. Possible reasons are  The XML document. Q 15: Whats wrong when the error message "lookup of alternativeServiceIdentifier via CPAcache failed" shows up while sending a RFC call to the RfcAdapter? A: A RFC sender channel is located beneath a service within the Integration Directory. which was send to the RfcAdapter.. So the root element name of this document is not the name of a function module and thus can't be found in the metadata repository. where XX is the system number of the particular system. functiontemplate from repository was <null>" is shown. Set the properties 'traceExceptionListener' and 'traceServerErrorListener' to 'true' (in the right frame). What does this mean and what could be done about it? A: At the beginning of a synchronous RFC call the RfcAdapter builds up the XI requestmessage and will send this to the Adapter Engine with a timeout. Notice that this value is specified in milliseconds.api. Notice that the RfcAdapter J2EE service has to be restarted to affect this changes. Open transaction SMGW and choose Goto -> Parameters -> Display.af. log into the J2EE Engine and choose tab 'Cluster'. the RfcAdapter extracts the payload from the message. Q 16: While sending a message to the RfcAdapter the error ".sap. Open the server node for which tracing should be enabled and open Services->Log Configurator. In the right frame the name 'com.MessageExpiredException" comes up. Q 12: How can tracing be enabled for RfcAdapter? A: Open the J2EE Visual Administrator. After this click on the 'Apply' button (save symbol) so save the changes. If maintained in SLD. Beneath Attributes there will be the entries 'gateway hostname' and 'gateway service'.aii. Q 13: What is the correct value within the field 'Application server service (Gateway)' for sender channels? A: This value has to be the name of the service port which is running the gateway. the last module always has to be the RfcAdapter module. that sends the RFC call to the RfcAdapter.ra.af. It normaly only makes sense to have these values filled for services of type "Business System".# Q 14: During a synchronous RFC call to the RfcAdapter the error message "call to messaging system failed: com. For an RFC sender channel also choose 'SAP XI Adapter: RFC' beneath 'Services' in the left frame. But this only will be checked at a later point. If the metadata repository doesn't have a function module with this name. Normally the metadata repository will be an R/3 system and it's function module repository can be searched with transaction code SE37. May there are situations where the check of the connection will fail due to a temporary error (like network. To actually apply the changes. To apply the new properties the service must be restarted. in sender channels only for the metadata repository parameter. The status of each channel in the RfcAdapter can be monitored in the Adapter Monitor. Since the J2EE server can run as a cluster with several server nodes." or "com...sap. If this check fails the channel is marked as failed and will not be used for sending or receiving of RFC calles within RfcAdapter. Mainly the RFC client parameter are checked with a connect/disconnect to the remote system. This will match the wildcard '*'. Why do I get errors when sending the same data via RfcAdapter? A: Parameters are treated different when SAPGUI is used.Adapters in Detail A: The RfcAdapter is implemented as a J2EE Service and thus the properties of this service must be changed.RfcAFWException: lookup of binding via CPA-cache failed." in the Message Audit Log of the Adapter Engine. Then open the tree node 'Services' and select 'SAP XI Adapter: RFC'  Select the property which you are intend to change and it is copied into the input box at the bottom of the window.".afcommunication. The changing of J2EE properties is discussed in Q 17.aii. the properties have to be saved with the disk symbol button on top of the window.. See also Q 24 which is related to this one. This is done during startup of the whole RfcAdapter (J2EE service) or when the RfcAdapter receives a new (or changed) channel from the Integration Directory. The test is done again each time when the channel is updated in the Integration Directory or after a restart of the RfcAdapter. RfcAdapter receiver channels report a error like "RfcAdapter: receiver channel not in list of running clientPools.. What happened? A: The RfcAdapter checks the configuration of each channel during the start of this channel. Sender Namespace: The fix RFC namespace urn:sap-com:document:sap:rfc:functions Receiver Party/Receiver Service: These fields are empty. The values used for this lookup are:  Sender Party/Sender Service: The values from Party and Service belonging to the sender channel.). In receiver channels this is done for the client parameter and the metadata repository parameter.af. This will affect the whole RfcAdapter and can be done from the J2EE Engines Visual Administrator.sap. Confirm the following dialog to do the restart. The channel will not be usable despite the temporary error may disappeared when the first message should be delivered through this channel..0 SP9. Q 21: What's to know about performance? Last printed 9/23/2005 9:24:00 a9/p9 Page 27 of 29 .. Q 18: The function module works fine with my parameters when I execute it in transaction SE37. If this is common in the environment where the RfcAdapter is used.RfcAFWException: senderAgreement not found: lookup of binding via CPA-cache failed.rfc.    Q 20: It is not possible to send RFC calls to the RfcAdapter sender channel and the RfcAdapter is not registered at the SAP Gateway. Q 19: While sending a RFC call to the RfcAdapter I get a error message like "com. A detailed description of this problem can be found in note 206068. Open the tree node 'Services' and select 'SAP XI Adapter: RFC'. This can be done for any property belonging to the service.afcommunication. What is missing? A: The RfcAdapter trys to find a Sender Agreement for this RFC call but the lookup failes. Now you can change this properties value and accept it with the 'Update' button.aii.. Normally the configuration is equal on each cluster node. This parameter was introduced in XI 3.af.rfc. Single node configuration: Choose tab 'Cluster' and open the appropriate server node in the tree. . the configuration can be changed for each single node independently or global for the whole cluster. When you are connected to the J2EE Engine with the J2EE Visual Administrator do the following for:  Global configuration: Choose tab 'Global Configuration' and then tab 'Server'. Set the RfcAdapter J2EE service property 'initialRfcClientConnectCheck' from 'true' to 'false'. the check can be disabled for the whole RfcAdapter. Note 769791 describes this in detail.. Sender Interface: The name of the RFC function module. the details of an entry have to be selected. It looks like some parameter is lost or empty. The Program ID of the registered RFC-Servrer can be found in column 'TP name'. So try to avoid using common phrases as Program ID like 'rfcadapter' or 'rfcToXmb'. Does the RFC sender channel automatically reconnect to the SAP Gateway after it is available again? Last printed 9/23/2005 9:24:00 a9/p9 Page 28 of 29 . Unfortunately the list within SMGW only shows the truncated version of the Program ID (column 'TP name'). Q 22: Which value should be chosen for the field 'Program ID' for RFC sender channels? A: A RfcAdapter sender channel registers itself with this Program ID as a RFC-Server at the SAP Gateway.g. there will be one registration at the SAP Gateway for each connection.Adapters in Detail A: The RfcAdapter implementation does instrument the JARM performance monitoring. this will have a bad effect on performance at all. Q 25: A RFC sender channel is registered at a SAP Gateway which is shutdown. Note 668256 describes the procedures for ABAP remote debugging. Select Goto -> Logged on Clients. this Program ID has to be maintained in the RFC destination (transaction SM59). If the signature of the function module is changed in the SAP-system this change also has to be done in the RFC-Adapter's cache memory. XML-Namespace declarations). See also note 777356 on this issue. This functionality is also available in the function module GWY_READ_CONNECTED_SYSTEMS which can be executed in transaction SE37. Registered RFC-Servers have a SystemType of 'REGISTER_TP'. If the sending system is a SAP system. To check which Program IDs are registered at the SAP Gateway the gateway-monitor can be used via transaction SMGW. To identify a XI RfcAdapter sender channel within the SAP Gateway it is important that its Program ID is unique within this Gateway. This parser only is suitable for correct RFC-XML documents (like created by a RFC-Adapter sender channel or the SAP JCO). The results can be viewed with the J2EE Visual Administrator in the service 'Performance Tracing'. Entries from RfcAdapter are prefixed with 'XI:RFCAdapter:'. The attached file rfcnormalizer. Before the first call to one function module it's metadata is retrived from the SAP-system and stored in a local RFC-Adapter cache memory. As an alternative the report RSGETALL_REG_SERVERS can be executed in transaction SE38. Each sucessive call to the same function module will use this cache which is much faster. These elements can't be understood by the RFC-XML parser of the RFC-Adapter. Note that if tracing is enabled in the J2EE service 'Log Configurator' (not performance tracing!). The output of this report will show the full names of the Program ID in column 'Registered PROGID'. See also Q 18 which is related to this one. If there are more than one RFC-Server registered with the same Program ID. Note that if the RFC sender channel is configured to use more than one connection to the SAP Gateway. This is described in detail in note 746971. To get the full name. In case of a RFC receiver channel the called function module in the SAP system can be debuged with the ABAP debugger. So turn off tracing to increase performance. Q 24: It seems that the RFC-Adapter does not convert every parameter of the function module between native RFC and RFC-XML. The sending system uses the same Program ID to identify the RFC-Server at the SAP Gateway.jar contains a XSLT-Stylesheet which can be used for this purpose. This way the actual used parameter values of the request and the response can be viewed in the ABAP debugger. The possible solutions do accomplish this are described in Q5. The RFC-XML document looks like it has the correct RFC-XML format but there are some additional XML elements (e. which is a SAP-system. it will automaticaly schedule the RFC calles to each of the RFCServers using the round robin approach. This is done to distribute the load over all RFC-Servers equally. If the RfcAdapter runs on a J2EE cluster with more than one server node. the SAP Gateway will search its registration list for the Program ID supplied by the sending system. the number of registrations at the SAP Gateway is the number of connections configured in the RFC sender channel multiplied by the number of cluster nodes on which the RfcAdapter runs. Q 23: How can the payload of a XI message be normalized to the RFC-XML format? Is it possible to remove unwanted XML-Namespace declarations from a RFC-XML document? A: While sending a message to a RFC-Adapter receiver channel a error is thrown during RFCXML-document parsing. Why does this happen? A: The conversion between native RFC and RFC-XML is done by using the metadata provided by the metadata repository. To remove the unneeded elements from the RFC-XML document a message mapping within the Integration Server can be used. During the sending system sends some RFC calls. If not configured.' What does this mean? A: When the RFC call is send from the SAP system to the RFC sender channel the SYS-ID and the Client of the sending system are also transfered. . This situation indicates a wrong configuration either within XI or the sending SAP system. If this reconnect fails. Also for each client in one SAP system at least one unique 'Program ID' is needed (see Q22)..  Q 26: During sending a RFC call to a sender channel the following error message comes up in the sending SAP system: 'alternativeServiceIdentifier: party/service from channel configuration are not equal to party/service from lookup of alternativeServiceIdentifier. If this XI service and the one found via the lookup are not equal the described error is issued. the next reconnect attempt is made after a waiting period of 1 second.. Since SP 12: Enter the maximum number of seconds to wait between reconnect attempts in the field Maximum Reconnect Delay. If the next reconnect fails also. Open the Advanced Mode for the RFC Server Parameter.. The sender channel itself is located beneath a partyless XI service.Adapters in Detail A: The SAP Gateway is shutdown due to e. This will lead to a reconnect timing of 1.g. But this maximum time can be configured for each RFC sender channel in the XI Integration Directory. Actually the RFC sender channel will try to reconnect to the SAP Gateway.. 3600 seconds. 2.. After restarting the SAP Gateway. 4. Each SAP system (a combination of SYS-ID and Client) should have a corresponding partyless service within the XI Integration Directory.  Before SP 12: Add a line to the table and use 'jco. the maximum waiting time is defined in the middleware layer of SAP JCO. which is 3600 seconds.server. offline backup of the R/3 database while a RFCAdapter sender channel is registering at this SAP Gateway. the RFC sender channel does not seem to automatically perform a reconnect. Last printed 9/23/2005 9:24:00 a9/p9 Page 29 of 29 . 8. the waiting period is doubled and so on. Saving recources is the aim of this technique.max_startup_delay' as name and the maximum number of seconds to wait between reconnect attempts as value. alternative identifiers for RFC) to find the XI service which correspond to the SYS-ID and Client. During processing of this RFC call the sender channel does a lookup for these values in the Integration Direcory (partyless service.