Programming Create() BAPIs
The BAPI Create() creates one instance of an SAP business object type. Likewise, the BAPI CreateMultiple() creates several instances of a business object type simultaneously.
If a workflow method called Create() already exists for the business object type in question, you can use the name CreateFromData() for your BAPI. Create() is the preferred name for this BAPI.
The BAPIs Create() and CreateMultiple() are class methods (instance-independent).
For each Create() BAPI, a method must be provided with which the created business object instance can be deleted or canceled. To do this, depending on the business application practice, you should implement one of the BAPIs below:
- Delete(), which deletes a business object instance from the database
For more information, see Programming Delete() BAPIs.
- Cancel(), which cancels a business object instance
For more information, see Programming Cancel() BAPIs.
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 is filled with 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, such as the application log, for example, can be evaluated, but the BAPI has not modified the database.
For further 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.
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
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.
Customer Enhancements to BAPIs.
- 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
- 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:
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.
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.
- If the corresponding key exists, it is returned in MESSAGE_V4. 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:
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.
For more information about this parameter, see
Return Parameters (Error Handling).
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.
For more information about bundling calls, see Details.
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 any 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.
Keep in mind that you have to convert the specified keys explicitly in upper case letters in the source code of this type of Create() BAPIs. Otherwise keys are created that cannot be used in dialog applications. This is because with dialog applications external keys are always converted implicitly in upper case letters.
Example of a Create() BAPI