Transcript
Adapters in Detail A detailed description of the common adapters
Table of Contents ADAPTERS ADAPTERS IN DETAIL............ DETAIL...................... .................... ..................... ..................... ..................... ..................... .................... ..................... ..................... ..................... ....................................1 .........................1 OVERVIEW.............. .............. .............. .............. .............. ............... .............. .............. .............. .............. .......... ..... .......... ....... 2
ACKNOWLEDGMENTS ....................................................................................................................................................... .......................................................................................................................................................3 3 XI ADAPTER ARCHITECTURE OVERVIEW............. ............... .............. .............. .............. .............. ............... .... 4
XI COMPONENTS RELATING TO THE ADAPTER .....................................................................................................................4 .....................................................................................................................4 The Adapter Engine .............. ............................ ............................ ............................ ............................ ............................. ............................. ............................ ............................ ............................ ................ .. 4 The Adapter Framework .............. ............................ ............................ ............................. ............................. ............................ ............................ ............................ ...................... ............. .......... ......... .... 4 Resource Resourc e Adapter Adapterss............. ........................... ............................ ............................ ............................. ............................. ............................ ............................ ......................... ................ ........... ............ .......... .... 5 Partner Connectiv Connectivity ity Kit.............. ............................ ............................ ............................. ............................. ............................ ............................ ............................ ...................... ............. .......... ......... .... 5 XI ADAPTERS............... .............. .............. .............. .............. ............... .............. .............. .............. .............. ............ .... 5
IDOC ADAPTER ..............................................................................................................................................................5 ..............................................................................................................................................................5 Implementation Implementa tion Considerat Considerations ions............ ........................... ............................. ............................ ............................ ............................ ............................. ......................... ................ ............ .......... .... 5 Integration Integrat ion............... ............................. ............................ ............................ ............................ ............................ ............................. ............................. ............................ ............................ ......................... ............... .... 6 RFC ADAPTER .................... .............................. ..................... ..................... .................... ..................... ..................... ..................... ..................... .................... ..................... ..................... .................................. ........................ 6 JDBC ADAPTER ............................................................................................................................................................6 ............................................................................................................................................................6 SOAP ADAPTER ............................................................................................................................................................6 ............................................................................................................................................................6 FILE / FTP ADAPTER ..................... ............................... .................... ..................... ..................... ..................... ..................... .................... ..................... ..................... ..................... ................................... ........................ 6 MAIL ADAPTER ..............................................................................................................................................................6 ..............................................................................................................................................................6 BUSINESS CONNECTOR ADAPTER .................... ............................... ..................... .................... ..................... ..................... ..................... ..................... .................... ......................................... ............................... 6 JMS ADAPTER ..................... ............................... ..................... ..................... .................... ..................... ..................... ..................... ..................... .................... ..................... ............................................ ................................. 6 MAIL ADAPTER ..............................................................................................................................................................6 ..............................................................................................................................................................6 HTTP ADAPTER ............................................................................................................................................................6 ............................................................................................................................................................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
Tran Transp spor ortt Prot Protoc ocol ol
Mess Messag age e Protocol
Quality of Service
Attac ttachm hmen entts
Ackno cknowl wled edgm gme ents nts
IDoc
Sender Adapter:
IDoc-XML
EO, EOIO with qRFC
No
System error acknowledgments
tRFC
Application acknowledgements
File Receiver Adapter:
Application error acknowledgements
tRFC RFC
RFC
RFC-XML
BE, EO, EOIO
No
Plain HTTP
HTTP(S) 1.0
XI payload in HTTP body
BE, EO, EOIO
No
SAP Business Connector (BC)
HTTP(S)
RFC XML with envelope
BE, EO
No
See below under Acknowledgments.
File/FTP
1.
File system (NFS)
BE, EO, EOIO
Yes
See below under Acknowledgments.
2.
File transfer protocol/file transfer protocol using SSL/TLS
JDBC
Attri ttribu buttes in Message Header
See below under Acknowledgments.
Sender
No
IDoc-XML
JDBC 2.0
3.
File
4.
File with content conversion
Sender Adapter: JDBC 2.0
BE, EO, EOIO
(Sender)
No
Sender Receiver
See below under Acknowledgments.
Receiver Adapter: XML SQL format Native SQL format
Last printed 9/23/2005 9:24:00 a9/p9
Page 2 of 29
Adapters in Detail JMS
SOAP
5.
SonicMQ JMS Provider
6.
WebSphereMQ (non-JMS)
7.
Access JMS Provider with JNDI
8.
(Read) JMS Provider Administered Objects from File
9.
Access JMS Provider Generically
Sender Adapter:
JMS 1.x
SOAP 1.1
HTTP
EO, EOIO
No
BE, EO, EOIO
Yes
BE, EO
Yes
Receiver Adapter:
(sender, receiver)
See below under Acknowledgments.
Sender
See below under Acknowledgments.
Sender
Receiver
Receiver
HTTP(S) SMTP(S) Marketplace
Mail
10.
HTTP(S)
11.
JMS Sonic MQ 3.5
Sender Adapter: IMAP4
MML
(sender, receiver) 12.
IXALL
13.
XIPAYLOAD
BE, EO, EOIO
Yes, for XIPAYLOAD
See below under Acknowledgments.
See below under Acknowledgments.
Sender Receiver
(sender, receiver)
POP3 Receiver Adapter IMAP4 SMTP RNIF20
RNIF11
CIDX
XI
14.
HTTP 1.1
15.
HTTPS
16.
HTTP 1.1
17.
HTTPS
18.
HTTP 1.1
19.
HTTPS
HTTP(S) 1.0
RNIF 2.0
EO
No
See below under Acknowledgments.
RNIF 1.1
EO
No
See below under Acknowledgments.
RNIF 1.1
EO
No
See below under Acknowledgments.
BE, EO, EOIO
No
20.
XI 2.0
21.
XI 3.0
Acknowledgments Receiver adapters that run on the Adapter Engine support system acknowledgments if they are requested by the sender. Acknowledgements are triggered when a message is successfully processed by the adapter or if an error occurs while it is being processed. Receiver adapters do not support application acknowledgments. The RNIF and CIDX adapters are exceptions to this rule, since they also support scenario-dependent application acknowledgments. Sender adapters of the Adapter Engine do not request any acknowledgments.
Last printed 9/23/2005 9:24:00 a9/p9
Page 3 of 29
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- and HTTPbased messages to the specific protocol and format required by these systems, and vice versa. The Adapter Engine is a separate software component that is automatically installed on the Integration Server. You can also install the Adapter Engine separately on another host as a local (non-central) adapter engine.
The Adapter Framework A central component of the adapter runtime is the Adapter Framework , with services for messaging, queuing, and security handling. The adapter framework supports the JCA standard (JCA: J2EE Connection Architecture) and communicates with Resource Adapters, which are either a component of SAP XI or are provided by SAP partners. All adapters shipped by SAP are resource adapters, apart from the IDoc adapter. TIP: See OSS note 821268 for FAQ on the Adapter Framework.
Last printed 9/23/2005 9:24:00 a9/p9
Page 4 of 29
Adapters in Detail
Resource Adapters These are the adapters developed and delivered by SAP as well as the adapters developed by 3 rd party providers (e.g. Seeburger, 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 PCK enables messages to be exchanged with the business system landscape of the smaller business partner. 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 message is forwarded to the Integration Server for further processing. To forward XML messages from the Integration Server to a receiver business system in the system landscape of the smaller business partner, the PCK of the business partner receives the message, converts it into the format required by the receiver system, and then forwards the message. 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.20 and with external systems. A direct system connection using proxies and without additional adapters is supported for SAP systems that are based on SAP Web Application Server 6.20 or higher.
IDoc Adapter The IDoc adapter enables you to process IDocs (Intermediate Documents) using the Integration Engine. IDocs from SAP systems Release 3.1x or higher are supported. The IDoc adapter is used by SAP systems to connect to a centrally configured Integration Engine using IDocs. A system that has an Integration Engine of this type is referred to as the Integration Server. External systems can also use the IDoc adapter to connect to an Integration Server.
Implementation Considerations Only use the IDoc adapter to integrate SAP systems with the Integration Server if a scenario of this kind suits your requirements. For example, if you want to make IDoc data in the form of XML messages available to additional receivers, 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.
Last printed 9/23/2005 9:24:00 a9/p9
Page 5 of 29
Adapters in Detail
Integration The IDoc adapter is part of the Integration Server. Essentially, the IDoc adapter comprises two parts, namely an adapter at the Integration Server inbound channel, and an adapter at the Integration Server outbound channel. The metadata for the IDoc types involved is shared. The adapter at the inbound channel is located before the Integration Server pipeline and calls this pipeline. The adapter at the outbound channel, however, is called by the pipeline, and can therefore be regarded as part of the pipeline. The connected systems transfer or receive IDocs through their IDoc RFC interface.
RFC Adapter TIP: See OSS note 730870 for FAQ on the Adapter.
JDBC Adapter TIP: See OSS note 831162 for FAQ on the Adapter.
SOAP Adapter TIP: See OSS note 856597 for FAQ on the Adapter.
File / FTP Adapter TIP: See OSS note 821267 for FAQ on the Adapter.
Mail Adapter Business Connector Adapter TIP: See OSS note 774854 for FAQ on the Adapter.
JMS Adapter TIP: See OSS note 856346 for FAQ on the Adapter.
Mail Adapter TIP: See OSS note 856599 for FAQ on the Adapter.
HTTP Adapter
APENDICES Mail Adapter FAQ 1. Sender Connection
Last printed 9/23/2005 9:24:00 a9/p9
Page 6 of 29
Adapters in Detail
Q: My mail messages seem to be read by the adapter but not processed. At least there is no message shown in the message monitor.
A: Please look at the adapter monitor in Runtime Workbench. You should be able to find your mail sender channel under the Mail adapter. The detail text of the channel should describe the problem. 2. Sender with XIALL
Q: I get some exception and my mail message does not seem to be processed.
A: Please check the status of your channel in the adapter monitor. The status of the adapter monitor is updated for each polling cycle. Therefore, you should look at the status right after a new message is picked up by your channel. From this status message, 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. 3. Sender with XIPAYLOAD
Q: How can I get the original sender email address and subject, etc?
A: You need to use the mail package option to get mail transport specific information in the XI payload. In SP14, there will be a new mechanism to transport transport specific information for all adapters. 4. 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. 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. If some error occurs 5. Other Sender related Questions
Q: My mail messages are not picked up.
A: The mail sender channel with IMAP4 fetches only the unread messages from the specified mail box in the order they are stored. Therefore, please make sure that you have some unread messages in the top of the list (if ordered by most recent on top). After a polling cycle, you can look at the status of this channel at the adapter's monitor. This should show any error if the messages are not processed correctly. Once the messages are read but not processed correctly, they remain in the mail box but are not read in the subsequent polling cycle. 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. The channel with POP3 fetches all messages from the specified mail box in the order they are stored. After a polling cycle, you can look at the status of this channel at the adapter's monitor. This should show any error if the messages are not processed correctly. Once the messages are read but not processed correctly, they remain in the mail box and read again in the subsequent polling cycle. If the problem is permanent, you must correct the problem or delete these messages using your mail client program. 6. Receiver Connection
Q: My mail messages does not seem to be sent out.
A: Please look at the adapter monitor in Runtime Workbench. You should be able to find your mail receiver channel under the Mail adapter. If this status is OK. Please look into the message monitor and find the audit log entries for this message. The detail text of the audit log should describe the problem. 7. 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
Adapters in Detail A: No. Most mail gateways do not support quality of service. Therefore, the adapter simply sends the message. If some error occurs, the message is resent. 8. Other Receiver related Questions
Q: Some characters such as ä,ö,ü are corrupted in my mail. How can I preserve these characters?
A: First, please make sure that the payload passed to the mail adapter contains the correct characters. When XIALL or XIPAYLOAD without the mail package is used, the mail message sent out from the mail adapter represents each payload of the original XI message passed to the mail adapter. Therefore, you can analyze the problem by capturing the mail message sent out form the mail adapter. When XIPAYLOAD with the mail package is used, the mail message is created from the mail package payload of the XI message. Therefore, you must temporarily change the mode to either of the other two and capture the mail message. To capture the mail message, 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. This tool can be placed between the mail adapter and the mail server to capture the messages. The captured messages can be saved in a file. Please see the included documentation for this tool for more details. The reason for the corrupted characters is most likely caused by the corrupted original payload or the incorrect character code setting in the payload. By analyzing the captured message, the cause of this problem can be identified.
Q: Can I choose the name of an attachment in the mail?
A: Yes. Most mail clients use some heuristics based on some MIME headers to derive the name of an attachment. The MIME headers involved in most heuristics are Content-Type, ContentDescription, and Content-Disposition. When you create an XI message, the XI payload name is automatically set in the Content-Description. If you want to change or set all of these headers, you can use the MessageTransformBean module (Note 793922) in the adapter framework. 9. Other Questions
Q: Which URL do I need to specify for some IMAP4 folder?
A: You can specify your folder as URL. For example, if your server is called host and your folder is called MyInBox which is in another folder called path, your URL should look like imap://host/path/MyInBox If your server runs on another port than the default IMAP4 port (143), 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. For example, if your server is called host, your URL should look like pop://host/ If your server runs on another port than the default POP3 port (110), 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. For example, if your server is called host, your URL should look like smtp://host/
Last printed 9/23/2005 9:24:00 a9/p9
Page 8 of 29
Adapters in Detail If your server runs on another port than the default SMTP port (25), 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.
Q: Can I use SSL for the connection to my mail server?
A: Yes. You can use URL imaps://... for IMAP4 over SSL, pops://... for POP3 over SSL, and smtps://... for SMTP over SSL. If the ports differ from the respective default ports (993, 995, 465, respectively), they should be given in the URL.
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: What is the purpose of the XIALL mode?
A: This mode allows the transport of an XI message over some mail gateways. 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. All the information contained in the original XI message at the first system is reconstructed at the second system.
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. For specific usage, please refer to "How to use MailPackage in Sender?" and "How to use MailPackage in Receiver?".
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: Can I monitor what my mail adapter sends or receives from the mail server?
A: The mail protocols such as IMAP4, POP3, and SMTP are TCP based protocols. You can configure any TCP gateway or monitor tool to capture the data. You can find a tool called TCPGateway in the attachment section of the SOAP Adapter FAQ note 856597. Please see tcpgw.zip for more details.
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
Adapters in Detail The message entry from the adapter's message monitor in Runtime Workbench. The XI message that is passed to the adapter The mail message that is posted to the mail server if available The 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. Documentation 1.1. Question: Where do I find the JMS adapter documentation? Answer: In the SAP online help, see
http://help.sap.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. Functions and architecture 2.1. Question: Does the JMS Adapter support JMS topics (publish&subscribe)? Answer: No. The JMS Adapter works with JMS queues because 100% Exactly Once (In order) service quality can only be guaranteed with JMS queues. See also: "Java Message Service", MonsonHaefel/Chappel, O'Reilly Publishers, 0-596-00065-5 2001, page 102 "... In this case, the once-and-onlyonce is in doubt". 2.2. Question: Can I release or read JMS message properties (for defining JMS message properties (see the above mentioned book, Appendix C)? Answer: No, you cannot release JMS message properties. With XI 3.0 Support Package 12, a function was introduced for the correlation of messages, which allows you to create XI message IDs on JMS string properties. A JMS string property can be read in the same way to set XI message Ids. 3. Logging 3.1 Question: I have a problem and would like to use the J2EE logging for the analysis. How do I switch on the logging? Answer: Start the J2EE Visual Administrator, select the J2EE service "Log Configurator" and select the "Locations" tab. Open the com->sap->aii->af->mp->jms->ejb there and set the log severity to "Debug" to log the JMS Adapter modules. Execute the same operation with the location com->sap->aii>af->service->jms if you want to log the JMS Adapter service. 3.2 Question: What is the com->sap->aii->adapter->jms logging location used for? Answer: It is not used for anything. This location is obsolete and is not used. It is only visible under XI 3.0 Support Package 0 and Service Release 1 and unfortunately cannot be removed technically between Support Package s.
SOAP Adapter FAQ 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 where host 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.
Last printed 9/23/2005 9:24:00 a9/p9
Page 10 of 29
Adapters in Detail 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 where host 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: My SOAP client gets a SOAP fault that indicates timeout in calling the adapter engine. Can I increase the default timeout value?
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. 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
Last printed 9/23/2005 9:24:00 a9/p9
Page 11 of 29
Adapters in Detail 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-andforget", 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-xxxxxxxxxxxxis 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?
Last printed 9/23/2005 9:24:00 a9/p9
Page 12 of 29
Adapters in Detail 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 text/xml; charset='utf-8' text/xml; charset='utf-8' no declaration text/xml; charset='iso-8859-1' application/xml 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 set parameter XMBWS.XMLEncoding to iso8859-1 in the module configuration for the SOAP adapter module. Related Questions "What character encoding is supported by the SOAP receiver adapter?"
Q: My sender adapter gets a timeout error from the adapter engine. 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. From SP13, you can change this value by setting parameter XI.Timeout in the module configuration table. This value must be set in milliseconds (e.g., 300000 for 5 minutes). 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.
Q: I cannot call an SSL web service requiring a client certificate.
Last printed 9/23/2005 9:24:00 a9/p9
Page 13 of 29
Adapters in Detail 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.
Q: Can I use several HTTP proxy servers for my channels?
A: Yes. You can configure your proxy setting per channel. 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" 34.5 will result in an application response message with response payload 34.5
Last printed 9/23/2005 9:24:00 a9/p9
Page 14 of 29
Adapters in Detail HTTP/1.1 500 Internal Server Error Content-Type: text/xml; charset="utf-8" SOAP:MustUnderstand SOAP Must Understand Error will result in a system error message. HTTP/1.1 500 Internal Server Error Content-Type: text/xml; charset="utf-8" SOAP:Server Server Error My application didn't work 1001 will result in an application error message with fault payload My application didn't work 1001 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
Last printed 9/23/2005 9:24:00 a9/p9
Page 15 of 29
Adapters in Detail 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 returns 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 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 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 response message containing the SOAP response message in its XI application payload. If your original XI application payload is not represented as a SOAP message, you need a mapping to map your XI payload between its original format and its SOAP format. 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
Last printed 9/23/2005 9:24:00 a9/p9
Page 16 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. 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: 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 nonpersisted messages. The SOAP message that the client is sending to the adapter.
Last printed 9/23/2005 9:24:00 a9/p9
Page 17 of 29
Adapters in Detail
The response message that the client is receiving from the adapter.
The vendor information of the client.
JDBC Adapter FAQ 1. 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.sda which is shipped as an empty stub with your XI installation. For Type 4 drivers, information how to add your JDBC drivers to this SDA is available in section 11.1 of the SAP XI 3.0 Configuration Guide, which is available on the SAP Service Marketplace under the URL: http://service.sap.com/instguidesNW04. For Type 2 drivers, additional configuration steps are required, which are documented in note 850116.
2. Unicode Handling
Q: I am inserting Unicode data into a database table or selecting Unicode data from a table. However, the data inserted into or retrieved from the table appears garbled. Why doesn't the JDBC Adapter handle Unicode correctly? A: While the JDBC Adapter is Unicode-aware, many JDBC drivers and/or database management systems aren't by default and need a codepage or Unicode-awareness to be configured explicitly. For the respective JDBC drivers, this codepage setting is often configured via the driver URL. For details, please refer to the documentation of your JDBC driver or database management system. Please note: For the Lotus Domino Driver for JDBC, there does not seem to be any documented method to enable support for Unicode strings.
3. Date Field Handling
Q: I would like to insert a date field into a table using the JDBC Receiver Adapter. However, I always get an error about a data type conversion error. What is the procedure to insert a date field using a JDBC Receiver? A: The actual implementation depends on the DBMS you are using. This answer will first describe a generic approach to implement this functionality and then provide examples for popular DBMS. All DBMS offer some kind of functionality to convert one data type into another data type. As the XML document used by the JDBC Receiver is based on character strings, we need to use a conversion function to convert a string into a DBMS-specific date type. This conversion function will be embedded by the JDBC Receiver into the SQL statement sent to the DBMS. In order that the DBMS actually executes the conversion function and does not treat it as a string, we need to make sure that the JDBC Adapter does not quote the date parameter. This can be achieved by setting the hasQuot attribute of the respective date field's XML element to "No". An example for the Oracle DBMS, where the date conversion function is named TO_DATE: TO_DATE('2004-07-20 08:00:00', 'yyyy-mm-dd hh:mi:ss') As you can see, any occurrence of an apostrophe within the element data needs to be written as "'" in order to yield valid XML. For the Microsoft SQL Server DBMS, the statement looks as follows:
Last printed 9/23/2005 9:24:00 a9/p9
Page 18 of 29
Adapters in Detail CONVERT(DATETIME, '2005-01-01 01:23:45', 120) The third parameter specifies the date format expected by the CONVERT function. For details, please refer to the MS SQL Server documentation (Books Online -> Contents -> Transact-SQL Reference -> CAST and CONVERT). 4. 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, which looks as follows: UPDATE TABLE SET Name='$NAME$' WHERE ID='$ID$' < /access> Joe's Name 42< /ID> When executing the resulting query, 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, 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. 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. The actual escape character to use depends on your DBMS. For details, refer to the respective DBMS documentation.
5. 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, all statements contained in an XI message sent to the JDBC Receiver are executed as one atomic transaction. Please note that versions older than SP11 Patch Level 1 performed an implicit commit in conjunction with certain DBMS when a database error occurred. For details, refer to note 823809.
6. 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. When sending a message to the receiver, the Adapter Monitoring shows the following error message:
Last printed 9/23/2005 9:24:00 a9/p9
Page 19 of 29
Adapters in Detail "java.sql.SQLException: [Lotus][Domino Driver for JDBC]Invalid cursor state" Is there a fix for this issue?
A: To work around this JDBC driver problem, 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. Additionally, make sure that the setting "Database Auto-Commit Enabled" is also active as the Lotus Domino Driver for JDBC does not support transactions. Please apply note 846079 before configuring this scenario.
7. Network-Level Connection Problems
Q: The TCP/IP connection to my database host is running over an unreliable network connection, i.e. the connection is sometimes interrupted. Consequently, 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. 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 note that this might put additional load on your DBMS due to the creation of a new database connection for each message. If you are connecting to an Oracle database, please also refer to question #10 for an alternative solution.
8. 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, i.e. both statements have the same view on the database. Make sure that both statements use the same WHERE clause. An additional requirement for the correct operation of this scenario is the configuration of an appropriate transaction isolation level on the database (i.e., repeatable_read or serializable). You might also consider using a "SELECT FOR UPDATE" statement instead of a plain SELECT statement to ensure proper locking on the database.
9. 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, each JDBC channel will create its own JDBC connection. The use of the J2EE engine's JDBC Connector and connection pooling mechanism is not supported.
Last printed 9/23/2005 9:24:00 a9/p9
Page 20 of 29
Adapters in Detail 10. Oracle JDBC Driver (classes12.zip / classes12.jar) Deadlocks
Q: I have deployed the Oracle classes12.zip / classes12.jar JDBC driver as per the instructions in the XI Configuration Guide. Unfortunately, I frequently notice hanging database connections. 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.
A: The Oracle classes12.zip / classes12.jar driver is compatible with Java 1.2 and Java 1.3 only, but not with Java 1.4. Please upgrade to a current driver (ojdbc14.jar), which does support the Java 1.4 JVM you are using. Please make sure that you remove classes12.zip / classes12.jar from aii_af_jmsproviderlib.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.sda are loaded into the same class loader and the driver class name of both driver versions is the same). Before deploying the updated driver, ensure that the new version is still compatible with your Oracle database server release. For details, please refer to the release notes provided by Oracle.
11. Operating System Command
Q: I am having difficulties getting an external operating system command to work. What can I do to diagnose the problem? A: Refer to note 841704.
12. 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).
The receiver of an XI message will only send an acknowledgement back to the sender if the sender has requested one. However, the JDBC Adapter has no functionality that relies on the receipt of an acknowledgement, so it never requests one. On the other hand, if a JDBC Adapter Receiver receives a request to send an acknowledgement, it will do so for a system acknowledgement request. 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, which is what a positive application acknowledgement would imply. 13. JDBC Drivers
Q: Which JDBC driver do you recommend to connect to ? A: SAP does not recommend a certain JDBC driver for use with the JDBC adapter. Please contact the vendor of your database management system for any recommendations.
14. JDBC Sender: Performance Issues After Configuring A Large Amount Of Channels
Q: After configuring a large amount of JDBC Adapter sender channels, the J2EE Engine becomes very slow and some services start to block. How can I solve this issue?
Last printed 9/23/2005 9:24:00 a9/p9
Page 21 of 29
Adapters in Detail
A: Up to and including XI 3.0 SP13 each JDBC Adapter sender channel permanently consumes a J2EE application thread. To solve this issue, increase the number of configured J2EE application threads using the SAP J2EE Engine Config Tool ("cluster-data" -> "Global server configuration" -> "managers" -> "ApplicationThreadManager" -> "MaxThreadCount"). Starting with XI 3.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, so thread shortage situations will typically occur much more rarely than with earlier SPs.
BC Adapter FAQ 1. Q: What is discussed in this document? A: This document discusses questions about the XI 3.0 BcAdapter. 2. Q: Are there some terms used with respect to this FAQ? A: The abbreviation BC is used for the "SAP Business Connector", BcAdapter for the "XI 3.0 SAP Business Connector Adapter". 3. Q: Which version of Business Connector is supported by the BcAdapter? A: BcAdapter supports the SAP Business Connector 4.7. 4. Q: Which type of documents can be processed with the BcAdapter? A: The BcAdapter supports only RFC-XML documents. For receiver channels a normal RFCXML document is supported. Such a document can e.g. be created with the XI RfcAdapter. When sending this document to BC, BcAdapter does a conversion into the special form of RFC-XML with an envelope that BC expects. For sender channels this special form of the RFC-XML document with envelope, as created by the BC, is supported. Such a document will be converted by the BcAdapter into the normal form, like known by the XI Integration Repository. 5. Q: Which quality of service (QoS) is supported? A: For receiver channels QoS BE (Best Effort) will result in a synchronous call (sRFC) , QoS EO (Exactly Once) will create a transactional call (tRFC) to the BC. 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. QoS EOIO is not supported by the BC-Adapter. 6. 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. 7. Q: A error message like 'XRFC_DOC_TYPE_UNKNOWN not supported as Payload' is raised. 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. See question 4 for more information on supported document types. 8. Q: What is the URL for BC Adapter sender channels? A: The URL is ://: /MessagingSystem/receive/BcAdapter/BC The values for , < host> and are the configured values of the SAP J2EE Engine. The value can be http or https. 9. 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. As addition this type of document is wrapped in an XML envelope. Here is a example of this envelope: < sap:Envelope xmlns:sap="urn:sap-com:document:sap" version="1.0"> < sap:Header xmlns:rfcprop="urn:sap-com:document:sap:rfc:properties"> < saptr:From xmlns:saptr="urn:sap-com:document:sap:transport">FROM < saptr:To xmlns:saptr="urn:sap-com:document:sap:transport">TO < rfcprop:Transaction>TID
Last printed 9/23/2005 9:24:00 a9/p9
Page 22 of 29
Adapters in Detail NORMAL RFC-XML DOCUMENT Here is an explanation of the individual tags.
From: The sender of this document. 'FROM' in this example. To: The receiver of this document. 'TO' in this example. Transaction: If the document represents a synchronous call (sRFC), the whole tag can be omitted. For a asynchronous call (tRFC), the value enclosed by this tag must be the tRFC TID. 'TID' in this example. Body: The normal RFC-XML document is enclosed by this tag. 10. 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 tag 'From' must be a concatenation of the SYS-ID and the client of the sending SAP-System e.g. 'ABC123'. This also has to be upper case. The value of this field is matched to the adapter-specific identifiers (RFC) in the Integration Directory. Only partyless services are taken into account during this search. This way a partyless service is found in the Integration Directory. The value of the 'To'-tag is ignored, because the XI receiver is determined during the routing step in the Integration Server. If this procedure is successful, 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. 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. 11. 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. This RFC-XML document is wrapped into an envelope. The result is a 'RFCXML with envelope' document (like described in Q9). 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. If it is found, the fields System-ID and Client are concatenated and used as From. If it is not found, the name of the XI message sender Service is used as From. To: A lookup of the adapter-specific identifier (RFC) for the XI message receiver Party/Service is done. If it is found, the fields System-ID and Client are concatenated and used as To. If it is not found, the name of the XI message receiver Service is used as To.
Last printed 9/23/2005 9:24:00 a9/p9
Page 23 of 29
Adapters in Detail
Transaction: If the XI message is asynchronous (QoS EO) this tag is filled with a TID representing the XI message-ID. If the XI message is synchronous (QoS BE) the whole tag is suppressed.
RFC Adapter FAQ Q 1: What is discussed in this document? A: This document discusses questions about the XI 3.0 RfcAdapter. Q 2: Is there more than one version of a XI RFC Adapter ? A: There are two kinds of RFC Adapters. The first one came with XI 2.0 and was part of the Adapter Engine. With XI 3.0 this Adapter Engine was renamed to 'J2SE Plain Adapter Engine' and does no longer contain a RFC Adapter. Instead, with XI 3.0, there is new Adapter Engine called 'J2EE Adapter Engine'. It is based on the SAP J2EE Application Server and contains a new RfcAdapter, which runs as a Service of the J2EE Server. This document only describes the J2EE RfcAdapter. 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. This will affect the whole RfcAdapter and can be done from the J2EE Engines Visual Administrator. When you are connected to the J2EE Engine choose the tab 'Cluster' and open the appropriate server node in the tree. Then open the 'Services' node. There you can see the entry 'SAP XI Adapter: RFC'. When you open the context menu on this entry you can start and stop the service. 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). Choose tab 'Objects' and open 'Service without Partner' -> 'Business-System'. Open the business system for which you want to communicate via RFC and choose 'New' from the context menu on the node 'Communication Channel'. Enter a name for the new channel and choose 'Create'. For 'Adapter Type' you have to choose 'RFC' (via the F4-help). Q 5: What's about cache memories within the RfcAdapter? A: The RfcAdapter has a cache for the metadata of function modules. This means it caches the definition of function modules, structures and other datatypes. A separate cache is used for each communication channel. When the particular data is needed during runtime, the cache is filled from the configured RFC metadata repository. Once if a particular metadata has entered the cache, only this one is used and no lookups to the RFC metadata repository are made for this type of metadata. If the communication channel is changed within the Integration Directory and gets replicated to the appropriate Adapter Engine (see Environment -> Cache Notifications...), this metadata cache is cleared. The caches for all communication channels are cleared when the J2EE Engine is restarted, the RfcAdapter J2EE Service 'SAP XI Adapter: RFC' is restarted or a dependend J2EE Service is restarted ('SAP XI AF CPA Cache', 'SAP XI AF Messaging'). 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 '_-'. A RFC sender channel will do the escaping of '/' to '_-' and a RFC receiver channel will do the opposite. This only will be done for the RFC-XML document. 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. If an attempt is made to place a second call within one transaction an exception is raised. This is done because within XI there is no transactional context between messages and each RFC call is wrapped into one message. Q 8: Is is possible to issue several RFC calls within one context for RFC receiver channels? A: No, a context between several RFC calls can not be held. Each call will get it's own context because different connections to the receiving system can be used. Q 9: Which flavous of RFC are supported? A: RfcAdapter supports synchronous RFC (sRFC, sometimes also called only RFC) and transactional RFC (tRFC). Queued RFC (qRFC) with inbound queues is not supported. A sRFC will result in a synchronous best effort (BE) message; a tRFC in a asynchronous exactly once (EO) and vice versa. Messages with exactly once in order (EOIO) are not supported till and including SP10. With SP11 a XI EOIO-messages will result in a normal tRFC call. If a tRFC is send to a SAPsystem it will be executed directly (in other words synchronous) plus the tRFC exactly once handling. The order of the messages belonging to one EOIO-queue will be guaranteed by the Adapter Framework messaging layer. Q 10: What's about BAPIs?
Last printed 9/23/2005 9:24:00 a9/p9
Page 24 of 29
Adapters in Detail A: The following only applies to RFC receiver channels. BAPIs can be implemented as RFC enabled function modules or IDocs. By their nature the RFC functionen modules are synchronous, the IDocs are asynchronous. Thus, if the communication should be asynchronous, it is a good idea to use the IDoc implementation of a BAPI. The RFC function module implementation of a BAPI will not only report it's result in the synchronous response. It also will report it's execution status (like Success, Error, ...). If the RFC call to such a function module was asynchronous, there will be no response and also no knowledge about the execution status. Even if the RFC call was synchronous, the RfcAdapter does no special handling for this values. It will treat a response value of any kind as a successful execution because it does not implement some BAPI application logic. 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, a message with QoS EO will lead to a (asynchronous) tRFC call. 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. Within RfcAdapter there is no special handling of transactions like a commit, so database update BAPIs may have a problem. If the BAPI RFC function module is called (asynchronous) via tRFC, the tRFC-subsystem of the SAPSystem will issue this commit by itself. So updates will be possible but the problem with the missing execution result persists. The following can be considered to use BAPIs with RfcAdapter regarding the interpretation of the execution result and the commit of the transaction. If it is required that one update BAPI is called, it can be put in a wrapper RFC function module which first calles this BAPI, does the interpretation of the execution result and than does the commit or rollback of the transaction. If it is required that multiple update BAPIs get commited together within one transaction, 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. In either case the wrapper RFC function module can be called by RfcAdapter. Anyway you have to keep in mind that this can compromise the quality of service (QoS) which was guaranteed by the original message. Imagine these two possibilities: a synchronous message with QoS BE or a asynchronous message with QoS EO.
The message was send synchronous with QoS BE (which will result in a synchronous RFC call, also called sRFC). The call reaches the receiver system and the function module is executed successful with the commit at the end. But during the sending of the return value a problem occurs (like network, ...). This can also happen if there even is no return value in the function module, 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, ...) and send this one back to the sender of the message. 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. The message was send asynchronous with QoS EO (which will result in a transactional RFC call, also called tRFC). The call reaches the receiver system and the function module is executed successful with the commit at the end. But during sending back the indication that the RFC call was executed (which actually will be synchronous) a problem occurs (like network, ...). The RfcAdapter will generate an error and send it back to it's persistency layer, the Adapter Framework Messaging. The message now marked as erroneous will be scheduled for a new execution because for messages with QoS EO the delivery will be guaranteed. When send again, the receiving system tRFC implementation decides whether the call was already successfully received or not. This guarantees the exactly once protocol of the tRFC implementation.
To handle this behaviour the approach to call a BAPI via a wrapper function module will not solve the problems described above. Some mechanism within the application has to deal with this type of problems. 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. The RfcAdapter will use one which is called 'localejbs/RfcAFBean'. This can be configured in the Integration Directory for each communication channel on the tab 'Module'. If the list is empty on this tab, it defaults to the EJB named above and nothing has to be done. So if no modules should be used, everything will work without a special configuration. If some custom modules are configured to be
Last printed 9/23/2005 9:24:00 a9/p9
Page 25 of 29
Adapters in Detail used, the last module always has to be the RfcAdapter module. This will establish the communication between the adapter and the Adapter Engine. Q 12: How can tracing be enabled for RfcAdapter? A: Open the J2EE Visual Administrator, log into the J2EE Engine and choose tab 'Cluster'. Open the server node for which tracing should be enabled and open Services->Log Configurator. Choose tab 'Locations' and open com->sap->aii->af then choose the location 'rfc'. In the right frame the name 'com.sap.aii.af.rfc' shows up with the current serverity. Set this serverity level to ' Debug' and also click on the button 'Copy severity to subtree'. After this click on the 'Apply' button (save symbol) so save the changes. For an RFC sender channel also choose 'SAP XI Adapter: RFC' beneath 'Services' in the left frame. Set the properties 'traceExceptionListener' and 'traceServerErrorListener' to 'true' (in the right frame). Save these changes with the save button. Notice that the RfcAdapter J2EE service has to be restarted to affect this changes. A dialog box will open upon save which can perform the restart after choosing 'Yes'. 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. Normally this will be a name like sapgwXX, where XX is the system number of the particular system. This value also can be looked up in the gateway monitor. Open transaction SMGW and choose Goto -> Parameters -> Display. Beneath Attributes there will be the entries 'gateway hostname' and 'gateway service'.# Q 14: During a synchronous RFC call to the RfcAdapter the error message "call to messaging system failed: com.sap.aii.af.ra.ms.api.MessageExpiredException" comes up. 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. After this it will wait till the responsemessage reaches or the timeout expires. In case of timeout the exception named above is thrown. The timeout used by RfcAdapter for synchronous calls can be configured for the whole RfcAdapter as a property of the RfcAdapter J2EE Service. To change it's value open the service properties sheet like described in Q3 and change the value of "syncMessageDeliveryTimeoutMsec". Notice that this value is specified in milliseconds. After changing the property store the properties by clicking the save-button (disk symbol) on top of the page. 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. Within this service choose "Service" -> "Adapter-Specific Identifiers". The values in the fields "R/3 System ID" and "Client" has to be maintained with the correct values of the system, that sends the RFC call to the RfcAdapter. It normaly only makes sense to have these values filled for services of type "Business System". If maintained in SLD, this fields will be filled automaticaly for services of type "Business System" and can be updated with the button "Compare with System Landscape Directory". Q 16: While sending a message to the RfcAdapter the error "... functiontemplate from repository was " is shown. Which reasons are possible? A: After receiving a message from the Adapter Engine, the RfcAdapter extracts the payload from the message. Normally this should be an XML document in the RFC-XML format. 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'. But this only will be checked at a later point, when the conversion from XML to native RFC is done. As prerequisite of this conversion the structures and types of the function module parameters has to be known. This is also called metadata or function template. 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. If the metadata repository doesn't have a function module with this name, the exception named above is thrown. Possible reasons are
The XML document, which was send to the RfcAdapter, is not a RFC-XML document. 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. The metadata repository doesn't contain an entry for this function module name. Normally the metadata repository will be an R/3 system and it's function module repository can be searched with transaction code SE37. 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
Adapters in Detail A: The RfcAdapter is implemented as a J2EE Service and thus the properties of this service must be changed. This will affect the whole RfcAdapter and can be done from the J2EE Engines Visual Administrator. Since the J2EE server can run as a cluster with several server nodes, the configuration can be changed for each single node independently or global for the whole cluster. Normally the configuration is equal on each cluster node. 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'. Open the tree node 'Services' and select 'SAP XI Adapter: RFC'. Single node configuration: Choose tab 'Cluster' and open the appropriate server node in the tree. 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. Now you can change this properties value and accept it with the 'Update' button. This can be done for any property belonging to the service. To actually apply the changes, the properties have to be saved with the disk symbol button on top of the window. To apply the new properties the service must be restarted. Confirm the following dialog to do the restart. Q 18: The function module works fine with my parameters when I execute it in transaction SE37. Why do I get errors when sending the same data via RfcAdapter? A: Parameters are treated different when SAPGUI is used. A detailed description of this problem can be found in note 206068. See also Q 24 which is related to this one. Q 19: While sending a RFC call to the RfcAdapter I get a error message like "com.sap.aii.af.rfc.afcommunication.RfcAFWException: lookup of binding via CPA-cache failed..." or "com.sap.aii.af.rfc.afcommunication.RfcAFWException: senderAgreement not found: lookup of binding via CPA-cache failed...". What is missing? A: The RfcAdapter trys to find a Sender Agreement for this RFC call but the lookup failes. The values used for this lookup are:
Sender Party/Sender Service: The values from Party and Service belonging to the sender channel.
Sender Interface: The name of the RFC function module.
Sender Namespace: The fix RFC namespace urn:sap-com:document:sap:rfc:functions
Receiver Party/Receiver Service: These fields are empty. This will match the wildcard '*'.
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. RfcAdapter receiver channels report a error like "RfcAdapter: receiver channel not in list of running clientPools..." in the Message Audit Log of the Adapter Engine. What happened? A: The RfcAdapter checks the configuration of each channel during the start of this channel. 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. Mainly the RFC client parameter are checked with a connect/disconnect to the remote system. In receiver channels this is done for the client parameter and the metadata repository parameter, in sender channels only for the metadata repository parameter. If this check fails the channel is marked as failed and will not be used for sending or receiving of RFC calles within RfcAdapter. The test is done again each time when the channel is updated in the Integration Directory or after a restart of the RfcAdapter. The status of each channel in the RfcAdapter can be monitored in the Adapter Monitor. Note 769791 describes this in detail. May there are situations where the check of the connection will fail due to a temporary error (like network, ...). The channel will not be usable despite the temporary error may disappeared when the first message should be delivered through this channel. If this is common in the environment where the RfcAdapter is used, the check can be disabled for the whole RfcAdapter. Set the RfcAdapter J2EE service property 'initialRfcClientConnectCheck' from 'true' to 'false'. The changing of J2EE properties is discussed in Q 17. This parameter was introduced in XI 3.0 SP9. Q 21: What's to know about performance?
Last printed 9/23/2005 9:24:00 a9/p9
Page 27 of 29
Adapters in Detail A: The RfcAdapter implementation does instrument the JARM performance monitoring. This is described in detail in note 746971. The results can be viewed with the J2EE Visual Administrator in the service 'Performance Tracing'. Entries from RfcAdapter are prefixed with 'XI:RFCAdapter:'. Note that if tracing is enabled in the J2EE service 'Log Configurator' (not performance tracing!), this will have a bad effect on performance at all. So turn off tracing to increase performance. See also note 777356 on this issue. 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. The sending system uses the same Program ID to identify the RFC-Server at the SAP Gateway. If the sending system is a SAP system, this Program ID has to be maintained in the RFC destination (transaction SM59). During the sending system sends some RFC calls, the SAP Gateway will search its registration list for the Program ID supplied by the sending system. If there are more than one RFC-Server registered with the same Program ID, 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. To identify a XI RfcAdapter sender channel within the SAP Gateway it is important that its Program ID is unique within this Gateway. So try to avoid using common phrases as Program ID like 'rfcadapter' or 'rfcToXmb'. To check which Program IDs are registered at the SAP Gateway the gateway-monitor can be used via transaction SMGW. Select Goto -> Logged on Clients. Registered RFC-Servers have a System Type of 'REGISTER_TP'. The Program ID of the registered RFC-Servrer can be found in column 'TP name'. Unfortunately the list within SMGW only shows the truncated version of the Program ID (column 'TP name'). To get the full name, the details of an entry have to be selected. As an alternative the report RSGETALL_REG_SERVERS can be executed in transaction SE38. The output of this report will show the full names of the Program ID in column 'Registered PROGID'. This functionality is also available in the function module GWY_READ_CONNECTED_SYSTEMS which can be executed in transaction SE37. Note that if the RFC sender channel is configured to use more than one connection to the SAP Gateway, there will be one registration at the SAP Gateway for each connection. If the RfcAdapter runs on a J2EE cluster with more than one server node, 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. The RFC-XML document looks like it has the correct RFC-XML format but there are some additional XML elements (e.g. XML-Namespace declarations). These elements can't be understood by the RFC-XML parser of the RFC-Adapter. This parser only is suitable for correct RFC-XML documents (like created by a RFC-Adapter sender channel or the SAP JCO). To remove the unneeded elements from the RFC-XML document a message mapping within the Integration Server can be used. The attached file rfcnormalizer.jar contains a XSLT-Stylesheet which can be used for this purpose. Q 24: It seems that the RFC-Adapter does not convert every parameter of the function module between native RFC and RFC-XML. It looks like some parameter is lost or empty. Why does this happen? A: The conversion between native RFC and RFC-XML is done by using the metadata provided by the metadata repository, which is a SAP-system. 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. Each sucessive call to the same function module will use this cache which is much faster. 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. The possible solutions do accomplish this are described in Q5. In case of a RFC receiver channel the called function module in the SAP system can be debuged with the ABAP debugger. This way the actual used parameter values of the request and the response can be viewed in the ABAP debugger. Note 668256 describes the procedures for ABAP remote debugging. See also Q 18 which is related to this one. Q 25: A RFC sender channel is registered at a SAP Gateway which is shutdown. 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
Adapters in Detail A: The SAP Gateway is shutdown due to e.g. offline backup of the R/3 database while a RFCAdapter sender channel is registering at this SAP Gateway. After restarting the SAP Gateway, the RFC sender channel does not seem to automatically perform a reconnect. Actually the RFC sender channel will try to reconnect to the SAP Gateway. If this reconnect fails, the next reconnect attempt is made after a waiting period of 1 second. If the next reconnect fails also, the waiting period is doubled and so on. This will lead to a reconnect timing of 1, 2, 4, 8, ..., 3600 seconds. Saving recources is the aim of this technique. If not configured, the maximum waiting time is defined in the middleware layer of SAP JCO, which is 3600 seconds. But this maximum time can be configured for each RFC sender channel in the XI Integration Directory. Open the Advanced Mode for the RFC Server Parameter.
Before SP 12: Add a line to the table and use 'jco.server.max_startup_delay' as name and the maximum number of seconds to wait between reconnect attempts as value. Since SP 12: Enter the maximum number of seconds to wait between reconnect attempts in the field Maximum Reconnect Delay.
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...' 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. During processing of this RFC call the sender channel does a lookup for these values in the Integration Direcory (partyless service, alternative identifiers for RFC) to find the XI service which correspond to the SYS-ID and Client. The sender channel itself is located beneath a partyless XI service. If this XI service and the one found via the lookup are not equal the described error is issued. This situation indicates a wrong configuration either within XI or the sending SAP system. Each SAP system (a combination of SYS-ID and Client) should have a corresponding partyless service within the XI Integration Directory. Also for each client in one SAP system at least one unique 'Program ID' is needed (see Q22).
Last printed 9/23/2005 9:24:00 a9/p9
Page 29 of 29
