Programming Create() BAPIs

BAPI Interface

Import Parameter

You should keep the following points in mind when defining the import parameters:

• The BAPI's import parameters in the function module contain the data required to uniquely identify an instance. All business key information may be provided, it must, however, be able to be derived. Since these are class methods, none of the BOR key fields may be a parameter in the function module or of the BAPI.

• The BAPI must also have a TestRun parameter that enables it to execute test runs. If this parameter contains the value "X", the BAPI executes normally, but does not write the results to the update task. In this way, after the BAPI BapiService.TransactionCommit executes, all results can be evaluated, (such as the application log, for example), but the BAPI has not modified the database.

  Note

  For more information, see Test Run Parameters .

• If customers are to be enabled to enhance the import parameters of the BAPI without modifications being necessary, you must create the parameter ExtensionIn .

  Note

  For information about extension parameters and recommendations on how the customer enhancement concept should be implemented in a Create() BAPI, see Customer Enhancements to BAPIs .

• You can create a change parameter to identify the values to create the instance with and to differentiate these values from the initial values when the BAPI is called. We recommend that you identify the change-relevant fields by flagging them. For more information see Change Parameters .

Export Parameter

You should keep the following points in mind when defining the export parameters:

• To make the object handle available to the calling program, the entire key fields must be returned in the export parameters of the function module. To this end, for each key field of the object type, you create an export parameter with the same name in the function module. This parameter is then filled with the appropriate values. These key parameters must have the same name as the corresponding key fields of the object type in the BOR.

• You can also create further export parameters in which, for example, generically created information is returned.

• If customers are to be allowed to extend the export parameters of the BAPI without modifications being necessary, you must create the parameter ExtensionOut . For information about extension parameters and recommendations on how the customer enhancement concept should be implemented in a Create() BAPI, see Customer Enhancements to BAPIs .

• To report messages from the method call back to the calling program, you should create the export parameter Return . To ensure the results of a Create() BAPI, called either synchronously or asynchronously, are monitored extensively, the following conventions for filling the Return parameter must be observed:

  • If the Create() BAPI executes successfully, in other words, an instance is created, the following standardized T100 message must be passed in the Return parameter:

    RETURN	MESSAGE
    TYPE	S
    ID	BAPI
    NUMBER	000
    MESSAGE_V1	< objectname >
    MESSAGE_V2	< reference_id >
    MESSAGE_V3	< reference_id >
    MESSAGE_V4	< corresponding_id >
    SYSTEM	< system >

    You should keep the following points in mind:

    • The field MESSAGE_V1 contains the external name of the associated business object type, such as SalesOrder .

    • The key under which the created object can be accessed at subsequent calls is returned in the field MESSAGE_V2. This is the external key included in the data passed when external number assignment is used, or the newly created internal key when internal number assignment is used. If the object has several key fields, the values of these key fields must be concatenated in MESSAGE_V2. The sequence in which the key fields are defined in the BOR must be adhered to for the concatenation. Moreover, the maximum length must be used for each key field. This may require the use of padding.

      Note

      If the complete key exceeds the maximum capacity of MESSAGE_V2 (that is, 50 characters), it is divided up between the fields MESSAGE_V2 and MESSAGE_V3. The first 50 characters are stored in MESSAGE_V2 and the remaining characters in MESSAGE_V3.

    • The external key is returned in MESSAGE_V4 to facilitate identification. This can be the key under which the object is stored in a non-SAP system, for example an external material number. The filling of this field serves exclusively to identify and not to access the object. If the corresponding key also consists of several fields, these must likewise be concatenated.

  • If an error occurs during the execution of the Create() BAPI, in addition to the application-specific error messages the following standardized T100 message must be passed in the Return parameter:

    RETURN	MESSAGE
    TYPE	E
    ID	BAPI
    NUMBER	001
    MESSAGE_V1	< objectname >
    MESSAGE_V2
    MESSAGE_V3
    MESSAGE_V4	< corresponding_id >
    SYSTEM	< system >

    The sole contrast to successful execution is that the fields MESSAGE_V2 and MESSAGE_V3 must be passed blank. The external key is returned in MESSAGE_V4 to facilitate identification.

• In addition to the standardized message, further messages can be written in the Return parameter.

• It is of particular importance when errors occur that messages describing the errors in detail are returned. You should, therefore, use all of the fields of the structure BAPIRET2. You should, in particular, fill the fields Parameter , Row , and Field .

  Note

  For more information about this parameter, see Return Parameters (Error Handling) .

BAPI Coding

Several Instances in one LUW

A Create() BAPI must be implemented in such a way as to enable several calls of the same Create() method to be initiated within one LUW and, consequently, to create several instances of the same object type in one LUW.

Using Temporary Storage

Both to enable several instances of the same object type to be created within one LUW and to achieve high performance, the results of a Create() BAPI should be bundled in the update task until they are actually written to the database. This is achieved by the BAPI calling the update module "IN UPDATE TASK" after the application logic has executed successfully. These update modules do not initiate individual database accesses. Instead, each operation to be performed is stored temporarily in the function group memory, and is then called indirectly in the FORM routine "ON COMMIT". This FORM routine, therefore, runs once only and, using techniques such as ARRAY insert, performs the update in only one database access.

Avoiding Incompatibilities with Customizing Settings

It could be possible that certain values set by Customizing appear differently in the BAPI interface. These values cannot be overwritten by a Create() BAPI.

To avoid incompatibility with Customizing settings, you should implement a Create() BAPI in the following way:

• The BAPI should transfer all the fields and check them against the Customizing settings. If the Customizing settings write-protect a field, the data in this field cannot be overwritten by data in the BAPI interface.

• For every incidence of incompatibility an Error message must be returned in the Return parameter to the calling program. For example, "Customizing settings do not allow the field 'MyAsset-AssetName' to be modified".

• All the fields that are assigned default values by Customizing and are therefore write-protected, must be documented.

External Key Assignment

For Create() BAPIs with an external key assignment, the caller transfers the key (ID) to the object instance to be created, for example, to a document number.

Important: The parameters for external keys should not have the same names as the object type keys in the BOR. If they do, the BAPI will be mistakenly identified as the instance method. The key generated in the BAPI should also be defined as an export parameter.