Background information

Business object development for the ABAP Extension Module consists of creating an application-specific business object definition and an associated ABAP handler for each verb that you want to support.

To develop an application-specific business object, you must create a business object definition that supports your business needs. The IBM WebSphere Business Integration Adapter for mySAP.com (SAP R/3 Version 4.x) includes tools that facilitate the process of developing business object definitions in the SAP application. Although you can use Business Object Designer or a text editor to create business object definitions for the ABAP Extension Module, it is recommended that you initially use the adapter's business object development tools. These tools use the SAP application's native definitions as a template.

For each application-specific business object definition that you develop, you must support it by using an adapter-provided ABAP handler or by developing a custom ABAP handler. The ABAP handler is the mechanism that gets data into and out of the SAP application database.

Note:
The application-specific business object and the ABAP handler rely on each other's consistency to pass data into and out of the SAP application. Therefore, if you change the business object definition, you must also change the ABAP handler.

An ABAP handler for the connector is implemented as an ABAP function module. ABAP handlers are one or more function modules that work together to fulfill a business object request from the business object router /CWLD/RFC_DO_VERB_NEXTGEN. ABAP handlers are responsible for passing business object data into and out of the SAP application.

Note:
SAP supports many verbs other than those (Create, Retrieve, Update, and Delete) supported by the WebSphere business integration system. You can develop an ABAP handler to support any verb.

To develop an ABAP handler, you must understand how the connector gets data into and out of the SAP application and what form that data takes during this process. For a high-level description of business object processing, see Overview of the ABAP Extension module. For a detailed description of business object processing, see Business object processing in the ABAP Extension module.

Note:
When you develop business objects, you must make sure that the objects are added to the connector's table /CWLD/OBJECTS table in the SAP R/3 application. If they are not, then you will not be able to access the objects for customization (for example, setting up the object for event distribution).

SAP native APIs

Adapter-provided ABAP handlers use SAP native APIs, which enable ABAP handlers to pass data into and out of the SAP application. The WebSphere business integration system has implemented the following native APIs:

ABAP SQL

ABAP SQL is SAP's proprietary version of SQL. It is database- and platform- independent, so that whatever SQL code you write, you can run it on any database and platform combination that SAP supports. ABAP SQL is similar in syntax to other versions of SQL and supports all of the basic database table commands such as update, insert, modify, select, and delete. For a complete description of ABAP SQL, its use, syntax and functionality, see your SAP documentation.

Using ABAP SQL, an ABAP handler can modify SAP database tables with business object data for create, update, and delete operations. It can also use the business object data in the where clause of an ABAP select statement as the keys.

Note:
The WebSphere business integration system never uses ABAP SQL to modify SAP tables, because this may corrupt the integrity of the database. The connector uses ABAP SQL only to retrieve data and to modify adapter-delivered database tables.

Call Transaction

Call Transaction is SAP-provided functionality for entering data into an SAP system. Call Transaction guarantees that the data adheres to SAP's data model by using the same screens an online user sees in a transaction. This process is commonly referred to as screen scraping. To use Call Transaction, specify the following types of instructions:

Initiation is passed as a single value parameter in the Call Transaction call. Navigation and Mapping instructions are passed in together in a table with a specific format. This format is usable for invoking Call Transaction for any SAP transaction. In this format, these instructions are referred to as the BDC data, BDC table, or BDC session.

Batch data communication (BDC)

Batch Data Communication (BDC) is an instruction set that SAP can follow to execute a transaction without user intervention. The instructions dictate the sequence in which a transaction's screens are processed and which fields should be populated with data on which screens. All of the elements of an SAP transaction that are exposed to an online user have identifications that can be used in a BDC. The elements are as follows:

To get a screen's BDC identity, place the cursor in any field on the screen. Press F1 for help and then F9 for technical information. The program name and screen number are listed under Screen Data.

To get an input field's BDC identity, place the cursor in each field on the screen in which you want to input data. Press F1 for help and then F9 for technical information. If there is a box named Field Description for Batch Input, then use the information in the Screen Field field. If this box does not exist, from the Field Data box, concatenate the Table Name and Field Name together with a hyphen.

To get a command's BDC identity, highlight the command in the menu and press F1 for help. Use the value in the Function field.

Business application programming interface (BAPI)

Use the BAPI Module to support BAPIs. For more information, see Overview of the BAPI Module.

IBM WebSphere function module interface

Every ABAP handler must implement the same function module interface. The function module interface guarantees that the business object router /CWLD/RFC_DO_VERB_NEXTGEN can pass business object data to and from ABAP handlers. The interface is:

*"*"Local interface: 
 *"  IMPORTING 
 *"        VALUE(PROC_FUNC_1) LIKE  RS38L-NAME OPTIONAL 
 *"        VALUE(PROC_FUNC_2) LIKE  RS38L-NAME OPTIONAL 
 *"        VALUE(OBJECT_NAME) LIKE  /CWLD/LOG_HEADER-OBJ_NAME OPTIONAL 
 *"        VALUE(OBJECT_VERB) LIKE /CWLD/WIZ_IN-OBJ_VERB OPTIONAL 
 *"        VALUE(ARCHIVE) OPTIONAL 
 *"        VALUE(TEXT) LIKE  T100-TEXT OPTIONAL 
 *"  EXPORTING 
 *"        VALUE(RETURN_TEXT) LIKE /CWLD/LOG_HEADER-OBJ_KEY 
 *"        VALUE(RFCRC) LIKE /CWLD/RFCRC_STRU-RFCRC 
 *"  TABLES 
 *"        RFC_STRUCTURE STRUCTURE /CWLD/OBJ_STRU 
 *"  EXCEPTIONS 
 *"        NOT_FOUND 
 *"        ERROR_PROCESSING 
 

In the importing section of the interface, you can communicate values such as the ABAP handler name, business object name, and business object.

The exporting section of the interface is used to communicate the results of the ABAP handler processing. The return code RFCRC parameter is a single field used to determine the code a connector returns. The possible values are:

RC = 0 (success, VALCHANGE)

RC = 1 (failure, FAIL)

RC = 21 (success, SUCCESS)

The RETURN_TEXT parameter is a 120-character free text field that is written to by the connector or logged as an error message in the return status descriptor. If the ABAP handler does not provide a value for this parameter, then /CWLD/RFC_DO_VERB_NEXTGEN supplies default text depending on the return code.

Note:
The exceptions section of the interface defines two exceptions. It is recommended that you use the exporting parameters instead.

IBM WebSphere ABAP handler APIs

The adapter provides several APIs that facilitate the development of ABAP handlers for the WebSphere business objects for SAP. These APIs were developed as "generic" ABAP handlers, because they require only metadata to support additional business objects of any type. The adapter provides the following ABAP handler APIs:

The adapter provides a set of tools that support these APIs. For all three ABAP handler APIs, the tools can be found in IBM CrossWorlds Station (transaction /n/CWLD/HOME). The adapter also provides SAPODA. For more information, see Appendix E, Generating business object definitions using SAPODA.

The following sections discuss the adapter-provided APIs and gives you steps on how to use IBM CrossWorlds Station tools and SAPODA to develop business objects for them.

Important:
You must log on to the SAP system in English when using IBM CrossWorlds Station tools to generate business object definitions or ABAP handlers. The CrossWorlds Station log is available only in English. You must also log on to the SAP system in English for the SAPODA.

Business object attribute properties

Business object architecture defines various properties for attributes. This section describes how the connector interprets several of these properties and describes how to set them when modifying a business object. Table 13 lists the business object attribute properties for the ABAP Extension Module.

Table 13. Business object attribute properties for the ABAP Extension Module
Property name Description
Name Each business object attribute must have a unique name.
Type The value is String.
MaxLength This property is not used.
IsKey The first simple attribute of a business object is set as the key attribute. All key attributes should be of type String. Setting a child object as a key attribute is not supported.
IsForeignKey This property is not used.
IsRequired This property specifies whether an attribute must contain a value.
AppSpecificInfo The value of this property is different depending on which ABAP handler supports the business object. The adapter delivers business object generation tools that automatically provide this value. If you modify the generated value, the business object may fail to process properly.
DefaultValue This property specifies the value to assign to this attribute if there is no run-time value.

Adapter development tools

The adapter provides business object development tools that let you generate a WebSphere business object definition file from within the SAP application. This business object definition file directly corresponds to the SAP business process and API from which it was generated.

Note:
When the IBM WebSphere InterChange Server is the integration broker, verify that your final business object definition file contains the version at the top. Early versions of the WebSphere InterChange Server require version text, which is located in the \repository\ReposVersion.txt file under the product directory. Also verify that the definition includes all of the required business objects and attributes (including the ObjectEventID attribute).

In IBM CrossWorlds Station, the following development tools are available:

Important:
You must log on to the SAP system in English when using IBM CrossWorlds Station to generate business object definitions or ABAP handlers. The CrossWorlds Station log is available only in English. You must also log on to the SAP system in English for the SAPODA.

Note:
For information on using Advanced Outbound Wizard, which creates hierarchical or flat business object definitions by stepping through the desired SAP transaction, see Generating business objects: Advanced Outbound Wizard.

Inbound wizard

The Inbound Wizard tool enables you to define business objects and the metadata required for their processing by recording your actions as you step through an SAP transaction that supports your required functionality. You do not need to write any ABAP code nor do you need to know the underlying database schema for the business object.

The Inbound Wizard generates the data for the Dynamic Transaction table by recording and interpreting user actions in an SAP transaction. It supports the definition of flat (non-hierarchical) business objects. In other words, it does not support business objects that contain child business objects. The Inbound Wizard can be used as a code generator to facilitate the development of more complex objects that require static code.

Note:
You can manually develop new business objects or modify existing business objects by adding/modifying entries to the Dynamic Transaction table.

For more information on developing business objects for business object requests, see Developing business objects using dynamic transaction.

Developing business object definitions using object definition generator

The Object Definition Generator enables you to build a WebSphere business object definition based on an IDoc or on the metadata in the Dynamic Transaction table. The business object definition file that is produced maintains the relationships and structure of the IDoc. The IDoc handler uses business objects developed from these IDocs. Therefore, the generator allows you to add your object-specific IDoc handler function modules when you generate the business object definition.

Once the business object definition is generated, you need only modify attribute names and make sure that the definition supports all of the desired functionality.

Note:
This tool is used primarily to generate business objects based on IDocs, but can also be used for Dynamic Transaction.

For more information on developing business objects using the Object Definition Generator, see Developing business objects using IDocs.

Developing business object definitions using SAPODA

SAPODA enables you to build a WebSphere business object definition based on an IDoc, or the tables used by Dynamic Retrieve and Dynamic Transaction. For more information on developing business objects using SAPODA, see Appendix E, Generating business object definitions using SAPODA.

Copyright IBM Corp. 2003, 2004