WebSphere business objects for the ABAP Extension Module can be defined in SAP as an IDoc. IDocs are part of SAP's EDI solution known as ALE (Application Link Enabling). Their definitions are stored in SAP's BOR (Business Object Repository) and can be accessed globally within an SAP system. The IBM WebSphere Business Integration Adapter for mySAP.com leverages the definition part of ALE to interpret and parse WebSphere business objects in the SAP application in preparation for use with an SAP native API. The adapter provides an IDoc handler that supports business objects developed using IDocs.
IDoc handler is made up of two function modules. Other ABAP handlers such as Dynamic Retrieve and Dynamic Transaction are only a single function module.
Y_XR_DO_VERB_NEXTGEN passes business object data to IDoc handler, Y_XR_IDOC_HANDLER. Based on the application-specific information, Y_XR_IDOC_HANDLER reformats the business object data into the structure of the IDoc specified by the application-specific information. After reformatting, the business object data is passed to an object-specific IDoc handler (based on the object/verb combination of the business object) that handles the integration with an SAP native API. Once the object-specific IDoc handler finishes processing the business object data, it returns the business object data in IDoc format to Y_XR_IDOC_HANDLER. The business object data is now converted back to its original format and returned to Y_XR_DO_VERB_NEXTGEN.
Figure 17 illustrates the basic architecture of an IDoc handler.
Figure 17. IDoc handler
architecture
To use the adapter-provided IDoc handler, you must have an IDoc defined in the SAP application. Either SAP-delivered or customer-built IDocs can be used. Because an IDoc definition must mirror the definition of the WebSphere business object for SAP, the adapter provides a tool in IBM WebSphere InterChange Server Connector Tool (transaction YXR1) that you can use to generate the WebSphere business object definition based on the IDoc.
Before you can generate a business object definition, you must have already created a WebSphere business object in the SAP application. To create a business object definition based on an IDoc:
For more information on how the application-specific information is used for the verb functions, see "Business object data routing to ABAP handlers".
After defining the IDoc, create a function module for each verb the business object must support. Each function should have the following interface to ensure that Y_XR_IDOC_HANDLER can call it:
*" IMPORTING *" VALUE(OBJECT_KEY_IN) LIKE YXR_EVENT-OBJ_KEY OPTIONAL *" VALUE(INPUT_METHOD) LIKE BDWFAP_PAR-INPUTMETHD *" OPTIONAL *" VALUE(LOG_NUMBER) LIKE YXR_LOG_H-LOG_NR OPTIONAL *" EXPORTING *" VALUE(OBJECT_KEY_OUT) LIKE YXR_EVENT-OBJ_KEY *" VALUE(RETURN_CODE) LIKE YXR_RFCRC-YXR_RFCRC *" VALUE(RETURN_TEXT) LIKE YXR_EVENT-OBJ_KEY *" TABLES *" IDOC_DATA STRUCTURE EDIDD
IDoc handlers that support Create, Update and Delete operations receive business object data formatted as an IDoc. The role of these operations is to integrate the business object data with SAP's Call Transaction API and generate an object key. Only the object key is passed back to Y_XR_IDOC_HANDLER, not the business object data. Y_XR_IDOC_HANDLER stores the business object data in memory and inserts the object key into the first attribute marked isKey in the parent business object. Then, Y_XR_IDOC_HANDLER passes the business object data back to the connector.
The sample code below represents the following flow:
The following sample code supports SAP Sales Quote Create:
*- Initialize working variables and internal tables PERFORM INITIALIZE_IN. *- I01(MF): Begin IDoc interpretation PERFORM LOG_UPDATE(SAPLYXR1) USING C_INFORMATION_LOG TEXT-I01 SPACE SPACE SPACE. *- Interpret IDoc data structure IF NOT IDOC_DATA[] IS INITIAL. *- Move IDoc to internal tables PERFORM INTERPRET_IDOC. *- Check some of the input fields PERFORM CHECK_INPUT. *- If key values were missing, exit function IF RETURN_CODE NE 0. EXIT. ENDIF. *- E01(MF): No Idoc data lines sent for processing. ELSE. RETURN_CODE = 2. RETURN_TEXT = TEXT-E01. EXIT. ENDIF. *- Build the BDC session for transaction VA21. PERFORM BUILD_BDC_VA21. *- Call Transaction PERFORM LOG_UPDATE(SAPLYXR1) USING C_INFORMATION_LOG TEXT-I02 'VA21' C_BLANK C_BLANK. CALL TRANSACTION 'VA21' USING BDCDATA MODE INPUT_METHOD UPDATE 'S' MESSAGES INTO BDC_MESSAGES. *- Capture return code and object key from transaction PERFORM PREPARE_RETURNED_MESSAGE. ENDFUNCTION.
The Create logic has two main functions:
The first part of the Create logic is the task of translating data in the IDoc structure into working data structures. To do this, you need to create code similar to the following:
loop at idoc_data. case idoc_data-segnam. when 'ZSQVBAK'. " Header Data move idoc_data-sdata to zsqvbak. when 'ZSQVBUK'. " Status Segment move idoc_data-sdata to zsqvbuk. when 'ZSQVBP0'. " Partner Header Level move idoc_data-sdata to zsqvbp0. when 'ZSQVBAP'. " Item Detail move idoc_data-sdata to zsqvbap. when 'ZSQVBA2'. " Item Detail Part 2 move idoc_data-sdata to zsqvba2. when 'ZSQVBUP'. " Item Status move idoc_data-sdata to zsqvbup. when 'ZSQVBKD'. " Commerical data move idoc_data-sdata to zsqvbkd. when 'ZSQKONV'. " Condition move idoc_data-sdata to zsqkonv. when 'ZSQVBPA'. " Partner Item Level move idoc_data-sdata to zsqvbpa. endcase. endloop.
Object-specific IDoc handlers that support the Retrieve verb do not receive business object data from the initial IDoc handler. Y_XR_IDOC_HANDLER passes the value of the first attribute marked isKey in the business object data using the parameter OBJECT_KEY_IN. It is the IDoc handlers responsibility to use this key to retrieve all information relevant to this instance of the object using ABAP SQL and format that data in the appropriate IDoc structure.
The following code supports the Sales Quote example. The Sales Quote object must retrieve data from tables VBAK, VBUK, VBPO, VBAP, VBUP, VBKD, KNOV, and VBPA. The tables follow the hierarchy and cardinality of IDoc type ZSLSQUOT. The code does the following:
The code for IDoc type ZSLSQUOT is:
*- Clear the interface structures. clear: g_text, object_key_out, return_code, return_text, idoc_data. refresh: idoc_data. * If no key value is specified, log it as an error and exit. if object_key_in is initial or object_key_in = c_cxignore_const. perform log_update(saplyxr1) using c_error_log text-e02 space space space. return_code = 1. return_text = text-e02. exit. endif. perform initialize_global_structures. perform fill_internal_tables. if not return_code is initial. exit. endif. * Build Idoc segments from internal tables perform fill_idoc_inttab. return_code = 0. return_text = text-s01. perform log_update(saplyxr1) using c_information_log text-s01 space space space. endfunction.
The two most important parameters are OBJECT_KEY_IN for the inbound key and IDOC_DATA for the outbound data. Note that OBJECT_KEY_IN may even be a multiple key depending on the conventions you have defined.
The VBAK table drives the selection criteria for the child tables, so each table is loaded into working tables. Using the VBAK table, you can retrieve the child tables with additional keys. So, for the Sales Quote example, the code is as follows:
form fill_internal_tables. * Get information from VBAK, VBUK, VBAP, VBKD, KONV, VBPA select single * from vbak where vbeln = object_key_in. if sy-subrc <> 0. perform log_update(saplyxr1) using c_error_log text-e01 object_key_out c_blank c_blank. return_code = '1'. g_text = text-e01. replace '&' with order_number into g_text. return_text = g_text. exit. endif. select single * from vbuk where vbeln = vbak-vbeln. select * from vbap into table t_vbap where vbeln = vbak-vbeln. * Continue for other tables
The following code is used to copy the requested data from the application database into internal tables and working variables. Then it creates segments that directly correspond to the WebSphere business object definition and puts it into the SAP segment structure.
In some cases for close matches on fields between the IDoc type and the working structure, you can do an ABAP move-corresponding command. In other cases, it is more preferable to do manual moves from the working table to the IDoc type table because of the relatively few fields to move in comparison to the overall number of fields in the structure. Simply, it is used to transfer data from the working data structures into the IDoc structures and then in the flat data field.
The code is:
form fill_idoc_inttab. perform fill_zsqvbak." Fill the Sales Quote Header perform fill_zsqvbuk." Fill the Sales Quote Status perform fill_zsqvbap." Fill Sales Quote Lines endform." FILL_IDOC_INTTAB *-- fill the Sales Quote Header form fill_zsqvbak. clear idoc_data. clear zsqvbak. idoc_data-segnam = 'ZSQVBAK'. move-corresponding vbak to zsqvbak. move zsqvbak to idoc_data-sdata. append idoc_data. endform." FILL_ZSQVBAK *-- fill the Sales Quote Header Status form fill_zsqvbuk. clear idoc_data. clear zsqvbuk. idoc_data-segnam = 'ZSQVBUK'. move-corresponding vbuk to zsqvbuk. move zsqvbuk to idoc_data-sdata. append idoc_data. endform." FILL_ZSQVBAK *-- fill the Sales Quote Line and the Line Child segments form fill_zsqvbap. loop at t_vbap. clear idoc_data. clear zsqvbap. idoc_data-segnam = 'ZSQVBAP'. move-corresponding t_vbap to zsqvbap. move zsqvbap to idoc_data-sdata. append idoc_data. perform fill_zsqvba2. perform fill_zsqvbup. perform fill_zsqvbkd. perform fill_zsqkonv. perform fill_zsqvbpa. endloop. endform. *-- fill second part of vbap form fill_zsqvba2. " etc.