How-to Guide SAP NetWeaver 04

How To Use BAPI wrappers in asynchronous scenarios with ccBPM

Version 1.00 December 2004 Applicable Releases: SAP NetWeaver 04 (XI 3.0 / ccBPM)

 Copyright 2004 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, and Informix are trademarks or registered trademarks of IBM Corporation in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C , World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MaxDB is a trademark of MySQL AB, Sweden. SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data

contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. These materials are provided as is without a warranty of any kind, either express or implied, including but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. SAP shall not be liable for damages of any kind including without limitation direct, special, indirect, or consequential damages that may result from the use of these materials. SAP does not warrant the accuracy or completeness of the information, text, graphics, links or other items contained within these materials. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third party web pages nor provide any warranty whatsoever relating to third party web pages. SAP NetWeaver How-to Guides are intended to simplify the product implementation. While specific product features and procedures typically are explained in a practical business context, it is not implied that those features and procedures are the only approach in solving a specific business problem using SAP NetWeaver. Should you wish to receive additional information, clarification or support, please refer to SAP Consulting. Any software coding and/or code lines / strings (Code) included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAP intentionally or grossly negligent.

1 Business Scenario
An external application communicates to R/3 via the SAP Exchange Infrastructure. A business transaction needs to be executed in the R/3 system, such as a PO creation. The business logic is available as a BAPI. The scenario must be executed asynchronously, but there needs to be an automatic confirmation that the business data was successfully processed (this would be the equivalent of an application acknowledgement). Cross-component BPM (ccBPM) will be used to process the confirmation message.

2 Introduction
We are assuming the following requirements: 1. R/3 connectivity must be via BAPI/RFC

The requirement is such that only BAPI/RFC technology can be used (no proxies, no IDocs). Lets say that the R/3 release is 4.6c, and there is a standard BAPI available already. 2. The standard BAPI must be called synchronously.

Due to the nature of the BAPI, it must be called synchronously. For example in this case the BAPI call will return a PO number. If the BAPI was called asynchronously, then the response would not be available. 3. The request message in XI must be processed asynchronously.

Based on the XI best practices, scenarios should be asynchronous whenever possible, in order to make use of the XI guaranteed delivery mechanism (EO and EOIO). The calling application will emit an asynchronous request and then immediately proceed to other tasks (non-blocking call). Our challenge here is that on the target side the XI message should be processed asynchronously, for performance reasons, but at the same time we dont want to lose the result of the transaction (ie the PO Number). Therefore we will use an asynchronous wrapper function module which will in turn call the standard BAPI synchronously. Note that when a function module is called asynchronously, the transactional RFC (tRFC) protocol is used automatically, which provides guaranteed delivery at the RFC level. 4. The confirmation message in XI must be processed asynchronously.

The next challenge is to pass the confirmation message back to XI. This will be implemented by triggering an independent tRFC call right before the end of the BAPI wrapper. This tRFC call will send an asynchronous confirmation message (application acknowledgement) back to XI. Note that ABAP proxies would provide a more elegant way to handle acknowledgements. However, as stated above, the assumption is that the target system does not support proxies. In a way, the scenario presented in this document can be seen as a tRFC-based workaround for the ABAP proxy-based application acknowledgements. 5. Cross-component Business Process Management (ccBPM) will be used to correlate the confirmation message to the original request.

-1-

It is the responsibility of ccBPM to correlate the 2 messages, and detect from the contents of the confirmation message, whether the transaction was successfully posted in the target application. Based on this information the process can take further action, for example raise an alert in case of failure, or send a confirmation all the way back to the calling application. In this example, the Vendor number will be used as correlation ID. Note about transaction handling with BAPI calls. The newer BAPIs work with explicit commits, which means that the BAPI call must be followed by a call to BAPI_TRANSACTION_COMMIT, within the same RFC session. The XI RFC adapter cannot maintain an RFC session open, therefore BAPIs with explicit commits cannot be invoked directly from XI. The wrapper concept discussed in this document can also be used as a workaround for wrapping a BAPI call and the subsequent transaction commit, within one tRFC call which will be viewed by XI as an atomic transaction. For simplicity purposes, we assume that the standard BAPI used in this example contains an implicit commit. Please consult OSS note 730870 for more details. The diagram below represents the flow of the messages and the execution of the ABAP logic relevant to our scenario:

Calling app

R/3 4.6C system ZBAPI asynchronous wrapper ZBAPI_PO_CREATE_ASYNC

Call the standard BAPI synchronously (BAPI_PO_CREATE)

Capture the response of the sync BAPI call Emit a new asynchronous ZBAPI call back to XI, containing the confirmation (ack) message.

ZBAPI_PO_SEND_RESP_XI_ASYNC

ccBPM (XI)

There are 3 BAPIs used in this scenario: 1. BAPI_PO_CREATE This is a standard SAP BAPI for creating purchase orders. Note that the BAPI has an implicit commit. The input of this BAPI is the data necessary for creating a PO (PO header and line items). The output is the PO document, which contains the PO number. 2. ZBAPI_PO_CREATE_ASYNC This is the wrapper for the standard BAPI call. The input is the minimal amount of data necessary to create a PO. It is a subset of the input of (1). This includes, among others, the vendor number for which the PO is to be created. Because this wrapper is designed to be called asynchronously, there is no output.

-2-

3. ZBAPI_PO_SEND_RESP_XI_ASYNC This is only a stub (no implementation), which will be used to issue a confirmation message back to XI. There are 2 inputs: the Vendor Number (input of (2)) and the newly created PO number (output of (1)). In ccBPM, the Vendor Number will be used to correlate the 2 messages. In real-life situations maybe other fields would be used to establish the correlation, in addition to or instead of the vendor number.

3 The Step By Step Solution

3.1 Create an RFC interface for the confirmation message.

1. Create a remote-enabled function module in SE37. In this example the name of the FM is ZBAPI_PO_SEND_RESP_XI_ASYNC. This FM will be used to send the asynchronous confirmation (acknowledgement) message back to XI.

2. This RFC takes two inputs: PO_NUMBER and VENDOR_NUMBER. Make sure to pass the parameters by value, since the FM is RFC-enabled.

3. Save and activate the function module. Again, no implementation logic is necessary since this is only a stub used to make an asynchronous call back into XI.

-3-

3.2 Create the main RFC Wrapper

4. Create a function module in SE37 (ZBAPI_PO_CREATE_ASYNC). Dont forget to make the FM RFC-enabled. The input of this wrapper depends on the standard BAPI that you will be invoking. In this case we are passing a subset of the PO_HEADER and PO_ITEMS. Again no export parameter is necessary since the wrapper will be called asynchronously.

5. Provide an implementation for the wrapper (full implementation can be found at the bottom of this document). Format the data and call the actual standard BAPI.

*prepare the data for the standard BAPI call: *execute synchronous BAPI call: CALL FUNCTION 'BAPI_PO_CREATE' EXPORTING PO_HEADER = BAPI_PO_HEADER IMPORTING PURCHASEORDER = PURCHASEORDER TABLES PO_ITEMS = BAPI_PO_ITEMS PO_ITEM_SCHEDULES = BAPI_PO_SCHEDULES

6. Continue the implementation of the wrapper: execute asynchronous call to send confirmation message to XI. in background task means that the call will be done asynchronously (over tRFC). A commit work statement must follow the call. The destination is a TCP/IP RFC destination which points to the XI RFC adapter sender channel.

CALL FUNCTION 'ZBAPI_PO_SEND_RESP_XI_ASYNC' in background task destination 'RFC2XR3' exporting PO_NUMBER = PURCHASEORDER VENDOR_NUMBER = PO_HEADER-VENDOR. commit work.

7. This concludes the ABAP development part. Make sure to save and activate your objects.

-4-

3.3 Create the necessary XI design objects

8. Import the 2 custom function modules into the Integration Repository.

9. Create interface and mapping objects as necessary. In our example we use a custom XML PO request as outbound interface from the calling application. There is a mapping between the custom XML and the BAPI wrapper call.

-5-

3.4 Create the business process model

10. Create a simple process which contains a receive-send-receive sequence. This is a simplified example. There is no exception handling in the process, and there is no further action after receiving the confirmation message. Note that all steps are asynchronous.

11. Create a correlation object between the wrapper call and the confirmation message.

12. The first receive step handles the original asynchronous request from the calling application.

13. The send step issues an asynchronous call which will be mapped to the ZBAPI_PO_CREATE_ASYNC call. The mapping takes place outside BPM and is not discussed here. The correlation is activated.

14. The second receive step handles the ZBAPI_PO_SEND_RESP_XI_ASYNC. This is considered to be an independent asynchronous request message. Therefore it should be correlated to the previous send step.

-6-

3.5 Create the necessary XI configuration objects, and test.

15. 3 receiver determinations need to be created: From sender to BPM From BPM to R/3 (wrapper call) From R/3 to BPM (async confirmation).

We wont go into the details of creating these objects. 16. The scenario can be tested by submitting an asynchronous message from the calling application (in this case simulated by a plain HTTP client). 3 messages can be seen in the XI monitor. Inspection of the most recent message (confirmation) shows that a PO number was created for the specific vendor.

17. The Process shows as complete. The correlation was established for the vendor number.

4 Appendix
Here is the complete code of the BAPI wrapper. This is for example purposes only. Please note the tRFC call into XI at the end (highlighted in bold).
FUNCTION ZBAPI_PO_CREATE_ASYNC. *"---------------------------------------------------------------------*"*"Local interface: *" IMPORTING *" VALUE(PO_HEADER) TYPE ZBAPI_PO_HEADER *" VALUE(BYPASS_BAPI) TYPE CHAR1 OPTIONAL

-7-

*" TABLES *" PO_ITEMS STRUCTURE ZBAPI_PO_DETAIL *"---------------------------------------------------------------------DATA: BAPI_PO_HEADER LIKE BAPIEKKOC, BAPI_PO_ITEMS LIKE BAPIEKPOC OCCURS 0 WITH HEADER LINE, BAPI_PO_SCHEDULES LIKE BAPIEKET OCCURS 0 WITH HEADER LINE, RANDOM_PO LIKE DATATYPE-INTEGER4, PURCHASEORDER LIKE BAPIEKKOC-PO_NUMBER. if BYPASS_BAPI ne ''. CALL FUNCTION 'RANDOM_I4' EXPORTING RND_MIN = 0 RND_MAX = 1000000000 IMPORTING RND_VALUE = RANDOM_PO . move RANDOM_PO to PURCHASEORDER. else. * Below are use to call BAPI_PO_CREATE move-corresponding PO_HEADER to BAPI_PO_HEADER. loop at PO_ITEMS. move-corresponding PO_ITEMS to BAPI_PO_ITEMS. append BAPI_PO_ITEMS. move-corresponding PO_ITEMS to BAPI_PO_SCHEDULES. append BAPI_PO_SCHEDULES. endloop. CALL FUNCTION 'BAPI_PO_CREATE' EXPORTING PO_HEADER PO_HEADER_ADD_DATA HEADER_ADD_DATA_RELEVANT PO_ADDRESS SKIP_ITEMS_WITH_ERROR ITEM_ADD_DATA_RELEVANT IMPORTING PURCHASEORDER TABLES PO_ITEMS PO_ITEM_ADD_DATA PO_ITEM_SCHEDULES PO_ITEM_ACCOUNT_ASSIGNMENT PO_ITEM_TEXT RETURN PO_LIMITS PO_CONTRACT_LIMITS PO_SERVICES PO_SRV_ACCASS_VALUES PO_SERVICES_TEXT PO_BUSINESS_PARTNER EXTENSIONIN POADDRDELIVERY

* * * * *

= BAPI_PO_HEADER = = = = 'X' = = PURCHASEORDER = BAPI_PO_ITEMS = = BAPI_PO_SCHEDULES = = = = = = = = = = =

* * * * * * * * * * * *

CALL FUNCTION 'ZBAPI_PO_SEND_RESP_XI_ASYNC' in background task destination 'RFC2XR3' exporting PO_NUMBER = PURCHASEORDER VENDOR_NUMBER = PO_HEADER-VENDOR. commit work. endif. ENDFUNCTION.

-8-

www.sdn.sap.com/irj/sdn/howtoguides