;0/ &RPPXQLFDWLRQ 6$3 %XVLQHVV &RQQHFWRU …

6$3�

�$*��é 1HXURWWVWU��é '��:DOOGRUI

;0/�&RPPXQLFDWLRQ��6$3�%XVLQHVV�&RQQHFWRU

&RQILJXUDWLRQ�*XLGH

+RZ�WR�HQDEOH�WKH�VWDQGDUG�6$3

FRPPXQLFDWLRQ�WHFKQLTXHV�IRU�WKH�LQWHUQHW

6 $3 � % X V L Q H V V � & R Q Q H F W R U5 H O H D V H ��

�

6$3�$* ;0/�FRPPXQLFDWLRQ�±�%XVLQHVV�&RQQHFWRU�&RQILJXUDWLRQ�*XLGH

LL

&RS\ULJKW

Copyright 2000 SAP AG. All rights reserved.No part of this documentation may be reproduced or transmitted in any form or for anypurpose without the express permission of SAP AG.SAP AG further does not warrant the accuracy or completeness of the information, text,graphics, links or other items contained within these materials. SAP AG shall not beliable for any special, indirect, incidental, or consequential damages, including withoutlimitation, lost revenues or lost profits, which may result from the use of these materials.The information in this documentation is subject to change without notice and does notrepresent a commitment on the part of SAP AG in the future.Some software products marketed by SAP AG and its distributors contain proprietarysoftware components of other software vendors.Microsoft®, WINDOWS, NT®, EXCEL and SQL-Server® are registered trademarksof Microsoft Corporation.IBM®, OS/2, DB2/6000®, AIX®, OS/400®, AS/400® are a registered trademark ofIBM Corporation.OSF/Motif is a registered trademark of Open Software Foundation.ORACLE is a registered trademark of ORACLE Corporation, California, USA.INFORMIX-OnLine for SAP is a registered trademark of Informix SoftwareIncorporated.UNIX® and X/Open® are registered trademarks of SCO Santa Cruz Operation.ADABAS is a registered trademark of Software AGSAP, R/2®, R/3®, RIVA®, ABAP/4, SAPoffice, SAPmail, SAPaccess®, SAP-EDI, SAP ArchiveLink, SAP EarlyWatch®, SAP Business Workflow, R/3 Retail®are registered trademarks of SAP AGAll rights reserved.


LLL

&RQWHQWV

� ,1752'8&7,21 ��

� 1(&(66$5<�&86720,=,1*�,1�7+(�%86,1(66�&211(&725��

2.1 ADDING SAP SYSTEMS.................................................................................................................................. 52.2 ADDING ROUTING RULES .............................................................................................................................. 62.3 ACCESSING BUSINESS CONNECTOR FUNCTIONALITY..................................................................................... 6

� ,'2&�&20081,&$7,21��

3.1 IDOC OUTBOUND PROCESSING (SAP IS CLIENT) ............................................................................................ 73.2 IDOC INBOUND PROCESSING (SAP IS SERVER)............................................................................................... 9

� %$3,�&20081,&$7,21��

4.1 BAPI OUTBOUND PROCESSING (SAP IS CLIENT) ......................................................................................... 114.2 BAPI INBOUND PROCESSING (SAP IS SERVER)............................................................................................ 13

� 5)&�&20081,&$7,21 ��

5.1 RFC OUTBOUND PROCESSING (SAP IS CLIENT)........................................................................................... 155.2 RFC INBOUND PROCESSING (SAP IS SERVER) ............................................................................................. 17


�

�� ,QWURGXFWLRQ

3XUSRVH�RI�WKLV�GRFXPHQW

This document describes how the standard SAP communication techniques (i.e. Idocs,BAPIs and RFCs) can be easily enabled for the internet using XML and the SAPBusiness Connector version 3.1. It is not a complete documentation about thesetechniques or the Business Connector. To find out more about these topics, pleaseconsider the related documents.

5HODWHG�'RFXPHQWV

• SAP Business Connector documentation (CD-ROM available)• SAP Interface Repository AddOn Guide• SAP RFC software development kit helpfiles

(e.g. \gui\windows\win32\sapgui\rfcsdk\help on the presentation CD)• SAP Interface Repository (http://ifr.sap.com) to learn more about SAP’s XML

Schemas• Internet Request for Comments (e.g. no. 2616 and no. 2617) (http://www.cis.ohio-

state.edu/hypertext/information/rfc.html )• A lot of information about XML and HTTPS (SSL) can be found in the internet

&HUWLILFDWLRQ�5HTXLUHPHQWV

A software product must at least meet the following requirements in order to becomecertified as an XML enabled product. More details about the requirements can be foundin the testplan belonging to the integration scenario.

• Internet communication using the protocols HTTP and HTTPS with the SAPBusiness Connector

• Adding necessary customizing into the SAP Business Connector• Sending and receiving the communication objects (i.e. Idocs, BAPIs or RFCs) that

are needed in the chosen integration scenario in XML format.

3UHSDUDWLRQV

The certification takes place in one of the SAP certification centers around the world. Thepartner will bring it’s own computer(s) with the software products to be certified. Thesoftware product may be already preinstalled; the installation of the partner’s software isnot part of the certification.Partner’s machine will be connected to an Ethernet LAN so it can access the SAP systemsused for certification. For the communication with the SAP systems an internal BusinessConnector is used that is configured in the same way as the one in the internet.


�

�� 1HFHVVDU\�FXVWRPL]LQJ�LQ�WKH�%XVLQHVV�&RQQHFWRU

To enter the administration screen of the Business Connector, simply enter the address ofthe Business Connector into a web browser (e.g. http://pbcce2.sap.com ) .

1RWH� The HTTP protocol is mentioned throughout this document to communicate withthe SAP Business Connector but it is also applied to the HTTPS protocol.

��$GGLQJ�6$3�V\VWHPV

You need to specify every SAP system that should be used within the BusinessConnector. Press the “SAP” button, then “Add server”, and then enter a name for thedestination and the necessary logon information. In the following screenshot an SAPsystem with name 6$36<67(0� is added:

Now communication between the Business Connector and the SAP system 6$36<67(0,where SAP is the server, is possible.


�

If you want to use the other direction as well (SAP is client), you need to install one ormore listeners for this SAP system. To do this, press the “SAP” button and click on the“Listener”-field for the SAP system. Then you can add a listener (e.g. 0</,67(1(5):

Now add in the SAP system with SM59 an RFC-destination that refers to the createdProgramID 0</,67(1(5. Then you can call the Business Connector from the SAPsystem using this RFC-destination.

��$GGLQJ�5RXWLQJ�5XOHV

Whenever a call arrives in the Business Connector, either from SAP with the RFCprotocol or from the external system with the HTTP(S) protocol, it has to determine therecipient of the call. To do this, the Business Connector looks into the call and extractsinformation about the 6HQGHU, 5HFHLYHU and 0VJ7\SH� Every call has to contain this kindof routing information.Then it looks into its list of Routing Rules and tries to find a rule that matches the routinginformation. In the rule the Business Connector can find the recipient and the format thatshould be used to send the call to this recipient.You can add Routing Rules by pressing the button “Routing”. There you need to specifythe Sender, Receiver and the MsgType and click the “Add Rule” button. After that youneed to specify the “Transport” and enter the “Transport Parameters”. Which value tochoose for the different SAP communication objects and directions is explained in thenext chapters.

��$FFHVVLQJ�%XVLQHVV�&RQQHFWRU�IXQFWLRQDOLW\

To access functionality in the Business Connector, so called VHUYLFHV are called via HTTP.This is done by posting a document containing the parameters to the service. In our case,we always post documents containing the XML format of the Idoc or BAPI/RFC-call to aservice of the Business Connector that converts the document and calls the SAP system.


�

The following statements must be used to post a document to the /sap/InboundIdocservice of the Business Connector. The keyword invoke must not be omitted. Theempty line that follows the header is also very important!

POST /invoke/sap/InboundIdoc HTTP/1.0

<?xml version="1.0" encoding="iso-8859-1"?><ALEREQ01> <IDOC BEGIN="1">...

Which services of the Business Connector should be used for the different SAPcommunication objects are explained in the next chapters.

�� ,GRF�FRPPXQLFDWLRQ

��,GRF�2XWERXQG�SURFHVVLQJ��6$3�LV�FOLHQW�

In the ALE customizing (transaction SALE) you specify the sender and the receiver foran Idoc (e.g. sender SAP and receiver EXTERNAL, Idoc message type MATMAS). Thenyou can send this Idoc to the Business Connector using an appropriate RFC destination.

&UHDWLQJ�WKH�5RXWLQJ�5XOH

You need to add the following Routing Rule, to convert the Idoc into XML and send itfrom the Business Connector with HTTP to an external webserver:


�

5HFHLYLQJ�WKH�,GRF

Your external webserver will receive an HTTP request containing a header with HTTPparameters and an XML document containing the Idoc in XML format. You can see thatthe routing information in the control record of the Idoc matches with the Routing Rule inthe Business Connector.

Content-type: application/x-sap.idocX-tid: [TID] +773�+HDGHU

<?xml version="1.0" encoding="iso-8859-1"?><MATMAS02> <IDOC BEGIN="1"> <EDI_DC40 SEGMENT="1"> <RCVPRN>(;7(51$/</RCVPRN> <SNDPRN>6$3</SNDPRN> <MESTYP>0$70$6</MESTYP> ...��;0/�'RFXPHQW

</EDI_DC40> <E1MARAM SEGMENT="1"> ... </E1MARAM> </IDOC></MATMAS01>

You need to answer the HTTP request that was initiated by the Business Connector. Anypositive answer is OK (e.g. Status 200).

7,'�KDQGOLQJ

You can extract the TID from the HTTP header (parameter X-tid). If an error duringtransmission occurred, SAP will resend the Idoc using the same TID. So you need to storethe TIDs in a database and check every TID that you receive from SAP:

1) 7,'�UHFHLYHG�IRU�WKH�ILUVW�WLPH: This transmission was never done before. The Idocmust be stored and processed. The TID must also be stored into a database.

2) 7,'�DOUHDG\�UHFHLYHG: This Idoc was transferred before, but an error occurred. So DONOT store or process this Idoc again.

The Business Connector does not confirm successful transactions. So your product mustdelete old TIDs after a significant time.


�

��,GRF�,QERXQG�SURFHVVLQJ��6$3�LV�VHUYHU�


Before you can send Idocs to SAP, you need to create a Routing Rule in the BusinessConnector that matches the routing information in the Idoc control record:

*HWWLQJ�D�7,'

The Business Connector can ask a SAP system to create a worldwide unique TID. Wewill use this service in the certification test. In the production environment such anadditional HTTP request might cost too much time. If it is the case, you can calculate anduse your own ‘pseudo TID’.To get a TID from the Business Connector, use the /sap/createTID service andspecify the SAP system, which should calculate the TID (e.g. 6$36<67(0).

POST /invoke/sap/createTID HTTP/1.0

serverName=6$36<67(0

The Business Connector answers this HTTP request with an HTML document containingthe TID.


��

6HQGLQJ�WKH�,GRF

Now you can post the Idoc in XML format to the Business Connector service /wm.PartnerMgr.gateway.transport.ALE/InboundProcess. Use the HTTPparameter X-tid to send the TID to the SAP system. Again, the routing information inthe Idoc control record has to match with a Routing Rule in the Business Connector.

POST /invoke/wm.PartnerMgr.gateway.transport.ALE/InboundProcessContent-type: application/x-sap.idocX-tid: [TID to use] +773�+HDGHU

<?xml version="1.0" encoding="iso-8859-1"?><MATMAS02> <IDOC BEGIN="1"> <EDI_DC40 SEGMENT="1"> <RCVPRN>6$3</RCVPRN> <SNDPRN>(;7(51$/</SNDPRN> <MESTYP>0$70$6</MESTYP> ...��;0/�'RFXPHQW

</EDI_DC40> <E1MARAM SEGMENT="1"> ... </E1MARAM> </IDOC></MATMAS01>

3URFHVVLQJ�WKH�DQVZHU�RI�WKH�%XVLQHVV�&RQQHFWRU

If the call succeeds, the Business Connector answers with an OK-status. Then you canconfirm the TID. If the call fails (e.g. timeout), you must resend the Idoc with the sameTID, so that the SAP system can detect a retransmission.

&RQILUPLQJ�WKH�7,'

You should confirm the TID to delete it from the SAP tables. You must use the sameSAP system for the confirmation that was used to create the TID:

POST /invoke/sap/confirmTID HTTP/1.0

serverName=6$36<67(0&$tid=[TID to use]


��

�� %$3,�FRPPXQLFDWLRQ

��%$3,�2XWERXQG�SURFHVVLQJ��6$3�LV�FOLHQW�

BAPI calls are sent to the Business Connector using an appropriate RFC destination.


The routing information of a BAPI call consists of the SAP systemID (e.g. 6$36<67(0),the used RFC destination (e.g. (;7B'(67) and the name of the function modulerepresenting the BAPI (e.g. %$3,B&86720(5B6($5&+). The Routing Rule in theBusiness Connector must match this information. In the Routing Rule, the BusinessObject and the Method of the BAPI must be specified:

5HFHLYLQJ�WKH�%$3,�FDOO

Your external webserver will receive an HTTP request containing a header with HTTPparameters and an XML document containing the BAPI call in XML format. You can seethat the routing information contained in the XML document matches with the RoutingRule in the Business Connector

1RWH� In the XML document the Message Type of the Routing Rule (e.g.BAPI_CUSTOMER_ SEARCH) is replaced by the BAPI name (Customer.Search).


��

Content-type: application/x-sap.busdoc

<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery> <to> <address>urn:sap-com:logical-system:(;7B'(67</address> </to> <from> <address>urn:sap-com:logical-system:6$36<67(0</address> </from> </delivery> </header> <body xmlns=""> <doc:&XVWRPHU�6HDUFK xmlns:doc="urn:sap-com:document:..."> <PiSalesorg>0001</PiSalesorg> <PiSearchFlag>2</PiSearchFlag> </doc:Customer.Search> </body> </biztalk_1>

Now you can parse and process the BAPI call and then return the result.

6HQGLQJ�WKH�%$3,�UHVSRQVH

You answer the HTTP request initiated by the Business Connector with the result of theBAPI call in XML format:


<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery/> </header> <body xmlns=""> <doc:Customer.Search.Response xmlns:doc="urn:sap-com:..."> <PiSalesorg>0001</PiSalesorg> <PiSearchFlag>2</PiSearchFlag> <Multiple> <item> <CUSTOMER>10001</CUSTOMER> </item> <item> <CUSTOMER>10002</CUSTOMER> </item> <PeCustomer/> <Return/> </doc:Customer.Search.Response> </body> </biztalk_1>


��

��%$3,�,QERXQG�SURFHVVLQJ��6$3�LV�VHUYHU�


Before you can call BAPIs in the SAP system, you need to create a Routing Rule in theBusiness Connector that matches the routing information in the BAPI XML document.

1RWH� The Message Type must match now with the BAPI and not with the functionmodule.

6HQGLQJ�WKH�%$3,�FDOO

Now you can post the BAPI call in XML format to the Business Connector service /wm.PartnerMgr.gateway.transport.BAPI/InboundProcess. Again, therouting information in the XML document has to match with the Routing Rule created inthe Business Connector.

POST /invoke/wm.PartnerMgr.gateway.transport.BAPI/InboundProcessContent-type: application/x-sap.busdoc��+773�+HDGHU

<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery> <to> <address>urn:sap-com:logical-system:6$3</address> </to> <from> <address>urn:sap-com:logical-system:(;7(51$/</address> </from> </delivery>


��

</header> <body xmlns=""> <doc:&XVWRPHU�6HDUFK xmlns:doc="urn:sap-com:document:..."> <PiSalesorg>0001</PiSalesorg> <PiSearchFlag>2</PiSearchFlag> </doc:Customer.Search> </body> </biztalk_1>

5HFHLYLQJ�WKH�%$3,�UHVSRQVH�RI�WKH�%XVLQHVV�&RQQHFWRU

If the call succeeds, the Business Connector answers with the result of the BAPI call:

<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery/> </header> <body xmlns=""> <doc:Customer.Search.Response xmlns:doc="urn:sap-com:..."> <Multiple> <item> <CUSTOMER>D2443</CUSTOMER> </item> <item> <CUSTOMER>D2444</CUSTOMER> </item> </Multiple> <PeCustomer/> <Return/> </doc:Customer.Search.Response> </body> </biztalk_1>


��

�� 5)&�FRPPXQLFDWLRQ

��5)&�2XWERXQG�SURFHVVLQJ��6$3�LV�FOLHQW�

RFC calls are sent to the Business Connector using an appropriate RFC destination.


The routing information of a RFC call consists of the SAP systemID (e.g. 6$36<67(0),the used RFC destination (e.g. (;7B'(67) and the name of the RFC function module(e.g. 4,5)B6(1'B&$7$/2*B'$7$). The Routing Rule in the Business Connectormust match this information:

5HFHLYLQJ�WKH�5)&�FDOO

Your external webserver will receive an HTTP request containing a header with HTTPparameters and an XML document containing the RFC call in XML format. You can seethat the routing information contained in the XML document matches with the RoutingRule in the Business Connector.


��


<?xml version="1.0" encoding="iso-8859-1"?><biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery> <to> <address>urn:sap-com:logical-system:(;7B'(67</address> </to> <from> <address>urn:sap-com:logical-system:6$36<67(0</address> </from> </delivery> </header> <body> <doc:4,5)B6(1'B&$7$/2*B'$7$ xmlns:doc="urn:sa..." xmlns=""> <I_CATALOG>COLOR</I_CATALOG> <T_QAICATAB/> <T_QIERRTAB/> </doc:QIRF_SEND_CATALOG_DATA> </body></biztalk_1>

Now you can parse and process the RFC call and then return the result.

6HQGLQJ�WKH�5)&�UHVSRQVH

You answer the HTTP request initiated by the Business Connector with the result of theRFC call in XML format:


<?xml version="1.0" encoding="iso-8859-1"?><biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery/> </header> <body> <doc:QIRF_SEND_CATALOG_DATA.Response xmlns:doc="ur..." xmlns=""> <T_QAICATAB> <item> <SATZART>Q45</SATZART> <KATALGART>1</KATALGART> <CODEGRUPPE>COLOR</CODEGRUPPE> <CODE>1</CODE> <KURZTEXT>Red</KURZTEXT> <QKENNZAHL>000</QKENNZAHL> </item> </T_QAICATAB> <T_QIERRTAB/> </doc:QIRF_SEND_CATALOG_DATA.Response> </body></biztalk_1>


��

��5)&�,QERXQG�SURFHVVLQJ��6$3�LV�VHUYHU�


Before you can call RFCs in the SAP system, you need to create a Routing Rule in theBusiness Connector that matches the routing information in the RFC XML document.

6HQGLQJ�WKH�5)&�FDOO

Now you can post the RFC call in XML format to the Business Connector service /wm.PartnerMgr.gateway.transport.RFC/InboundProcess. Again, therouting information in the XML document has to match with the Routing Rule created inthe Business Connector.

POST /invoke/wm.PartnerMgr.gateway.transport.RFC/InboundProcessContent-type: application/x-sap.busdoc��+773�+HDGHU

<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery> <to> <address>urn:sap-com:logical-system:6$3</address> </to> <from> <address>urn:sap-com:logical-system:(;7(51$/</address> </from> </delivery> </header> <body>


��

<doc:4,5)B6(1'B&$7$/2*B'$7$ xmlns:doc="urn:sa..." xmlns=""> <I_CATALOG>COLOR</I_CATALOG> <T_QAICATAB/> <T_QIERRTAB/> </doc:QIRF_SEND_CATALOG_DATA> </body> </biztalk_1>

5HFHLYLQJ�WKH�5)&�UHVSRQVH�RI�WKH�%XVLQHVV�&RQQHFWRU

If the call succeeds, the Business Connector answers with the result of the RFC call:

<?xml version="1.0" encoding="iso-8859-1"?> <biztalk_1 xmlns="urn:biztalk-org:biztalk:biztalk_1"> <header> <delivery/> </header><body> <doc:QIRF_SEND_CATALOG_DATA.Response xmlns:doc="ur..." xmlns=""> <T_QAICATAB> <item> <SATZART>Q45</SATZART> <KATALGART>1</KATALGART> <CODEGRUPPE>COLOR</CODEGRUPPE> <CODE>1</CODE> <KURZTEXT>Red</KURZTEXT> <QKENNZAHL>000</QKENNZAHL> </item> </T_QAICATAB> <T_QIERRTAB/> </doc:QIRF_SEND_CATALOG_DATA.Response> </body> </biztalk_1>

Documents

;0/ &RPPXQLFDWLRQ 6$3 %XVLQHVV &RQQHFWRU …