ABAP BAPI III

Defining a BAPI and Its Interface

Purpose

After you have carried out the review of the BAPI concept and it has been accepted, you can start defining the BAPI itself.

In this step, you will decide on the names, parameters, and characteristics of the BAPI and determine the structures in the ABAP Dictionary, which the BAPI will be based on. Only after you have planned and defined these required details can you start to implement the BAPI and create the required programming objects.

The table below illustrates where the planned information is written and how it fits together.

Information in the BOR, Function Builder and ABAP Dictionary


Standardized BAPIs

Use

Some BAPIs and methods provide basic functions and can be used for most SAP business object types. Such BAPIs are known as "standardized" BAPIs.

Features

With object methods and especially with BAPIs, you can differentiate between instance methods and class methods. Instance methods refer to precisely one instance (one specific occurrence) of an SAP Business Object type, for example, to one explicitly specified customer order. Whereas class methods are instance-independent.

BAPIs for Reading Data

The following BAPIs provide you with read-only access to data in the associated business object type:
GetList()
With the BAPI GetList() you can select a range of object key values, for example, company codes and material numbers. The BAPIs GetList() is a class method.

Programming GetList() BAPIs

Use

With the BAPI GetList() you can select a range of object key values, for example, company codes and material numbers. The key values returned by this BAPI can be passed on to another BAPI for further processing, for example, the BAPI GetDetail().
The BAPIs GetList() is a class method (instance-independent).

Features

Provide all the relevant fields in the interface of the GetList() BAPI. How complex and extensive you structure the interface, depends on the requirements the BAPI is to fulfill.

Import Parameters

The interface of a GetList() BAPI must provide selection parameters, in which the required selection criteria can be passed on by the calling program. The structure of selection parameters is described in the section Selection Parameters.

You must also create the parameter MaxRows that enables you to limit the number of entries selected. This parameter prevents too large a value set from being selected, if the selection parameter specification is not very precise. Use the data element BAPIMAXROW as the reference type for the MaxRows parameter.

Export Parameters

The key values selected by the BAPI GetList() are returned to the calling program in a table, together with other useful information, for example, short texts.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see
Return Parameters (Error Handling).

Extension parameters

You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.

GetDetail()
The BAPI GetDetail() uses a key to retrieve details about an instance (one specific occurrence) of a business object type and returns this data to the calling program. Then this information is reported back to the calling program. The BAPI GetDetail() is an instance method.

Programming GetDetail() BAPIs

Use

The BAPI GetDetail() is used to read details of specific object instances.
The BAPI GetDetail() is an instance method.

Features

Import Parameters

The import parameters of the GetDetail() BAPI must contain the key fields of the business object type.

For the associated method definition in the BOR, the key fields must not also be specified as method parameters. For this reason, the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition, when it creates a BAPI.

Export Parameters

The export parameters of a BAPI contain details of the instance. According to the amount of information, this should be structured in several parameters with meaningful names.

To report messages from the method call back to the calling program, you should create the export parameter Return. For more information about this parameter see Return Parameters (Error Handling).

Extension Parameters

You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.

GetStatus()

The BAPI GetStatus() is used to query the status of an SAP business object instance, for example, the processing status of a sales order. This BAPI is used only for displaying the status of an object and does not retrieve full details like the BAPI GetDetail(). The BAPI GetStatus() is an instance method.

Programming GetStatus() BAPIs

Use

With the BAPI GetStatus() you can retrieve information about the status of a particular object instance.
The BAPI GetStatus() is an instance method.

Features

Import Parameters
The import parameters of the GetStatus() BAPI must contain the key fields of the business object type.

For the associated method definition in the BOR, the key fields must not also be specified as parameters. For this reason, the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition, when it creates a BAPI.

Export Parameters

The export parameters of the BAPI contain information about the status of an object instance.

To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see Return Parameters (Error Handling).

Extension Parameters

You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.

ExistenceCheck()

The BAPI ExistenceCheck() checks whether an entry exists for a business object instance, for example, whether the customer master has been created. The ExistenceCheck() BAPI is an instance method.

Programming ExistenceCheck() BAPIs

Use

The BAPI ExistenceCheck() checks whether an entry exists in the database for an SAP business object type, for example, whether the customer master has been created.
The ExistenceCheck() BAPI is an instance method.

Features

You can implement this method as a BAPI and/or as a method of SAP Business Workflow. If you implement this method as a BAPI, it only has to be implemented once, because an ExistenceCheck() BAPI can also be used by SAP Business Workflow.

To get the highest possible performance from the BAPI ExistenceCheck(), you should reduce the number of columns to as few as possible before selecting the table rows.
select single bukrs from bkpf into lv_bukrs
where bukrs = bkpf-bukrs
and belnr = bkpf-belnr
and gjahr = bkpf-gjahr.
instead of
select single * from bkpf
where bukrs = bkpf-bukrs
and belnr = bkpf-belnr
and gjahr = bkpf-gjahr.

Import Parameters

The BAPI's import parameters in the function module only contain the key fields of the business object type.

Export Parameters

To report messages from the method call back to the calling program, you should create only the export parameter Return . For more information about this parameter see Return Parameters (Error Handling).

Activities

When a business object type is created, as the default, it inherits a definition of the method ExistenceCheck() through the interface IFSAP. For this reason, you can create an ExistenceCheck() BAPI using the BOR/BAPI Wizard, as the method name ExistenceCheck() already exists for the business object type.

We recommend therefore, that you redefine the existing method ExistenceCheck() manually in the BOR, via the menu path Edit  Redefine.

• Enter the function module that implements the ExistenceCheck() BAPI.
• Create the method parameter RETURN (the key fields of the business object type are not included in the method definition in the BOR).

BAPIs for Creating or Changing Data

The following BAPIs can create, change or delete instances of a business object type:
Create() or CreateFromData()
The BAPI Create() or CreateFromData() creates an instance of an SAP business object type, for example, a purchase order. These BAPIs are class methods.

Programming Create() BAPIs

Use

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 cancelled. 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.

Features

Import Parameters

The BAPI's import parameters in the function module contain the data required to uniquely identify an instance. For this you can either enter all object keys or else you must ensure that these can be derived.

If required, you can also use a test run parameter to check the entry for an object instance before actually creating the instance in the database. For further information see Test Run Parameters.

You can create a change parameter to identify the values to create the instance with and to tell 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 Parameters

To make the object key available to the calling program, the entire key fields must be returned in the export parameters.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see Return Parameters (Error Handling).

Extension parameters

You can create extension parameters to enable customers to enhance the functionality
of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
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 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.
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.

Locking

We recommend that you implement Create() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.

Change()
The BAPI Change() changes an existing instance of a SAP business object type, for example, a purchase order. The Change() BAPI is an instance method.


Programming Change() BAPIs

Use

The BAPI Change() changes an existing instance of an SAP business object type, for example, a sales order.

The BAPI Change() is an instance method, whereas the BAPI ChangeMultiple() is a class method (instance-independent).

Features

Import Parameters

The import parameters of the Change() BAPI must contain the key fields of the business object type.

If required, you can create also create these parameters:
• A test run parameter for checking the entry for an object instance before actually creating/changing the instance in the database.
• A change parameter to identify parameter fields containing modified values and parameter fields that have not been modified.
For more information about these parameters see Standardized Parameters.
Export Parameters
To make the object key available to the calling program, the entire key fields must be returned in the export parameters.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see Return Parameters (Error Handling).
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
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 Change() BAPI.

To avoid incompatibility with Customizing settings, you should implement a Change() 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.

Locking

We recommend that you implement Change() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.

Delete() and Undelete()
The BAPI Delete() deletes an instance of an SAP business object type from the database, for example, a purchase order.
The BAPI Undelete() removes a deletion flag.
These BAPIs are instance methods.

Programming Delete() BAPIs

Use

The BAPI Delete() deletes an instance of an SAP business object type from the database. Likewise, the BAPI DeleteMultiple() deletes several instances of a business object type. Delete() BAPIs must always delete entire instances, for example, a whole material master.

(Whereas the BAPI Cancel() cancels an instance of a business object, that is the instance to be cancelled remains in the database and an additional instance is created that is canceled. For more information see Programming Cancel() BAPIs).

A delete() BAPI can delete immediately or at a later time by setting the deletion flag. The type of deletion you use in your BAPI is irrelevant to the caller, so you do not have to include these details in the BAPI interface.

The BAPI Undelete() is used to reset a deletion flag that has been set for a specific object.

The BAPIs Delete() and Undelete() are instance methods, whereas the BAPIs DeleteMutliple() and UndeleteMutliple() are class methods (instance-independent).

Features

The interfaces of the Delete() and Undelete() BAPIs should be identical.
Import Parameters
The BAPI's import parameters have to identify the business object instances to be deleted.

• If an instance is to be deleted, you have to create a parameter for each key field in the business object type.
• If several instances are to be deleted, you must create a table for the key fields of the business object type. You can do this using a range table.
If required, you can create also create these parameters:
• A test run parameter for checking the entry for an object instance before actually deleting the instance from the database.
• When the BAPI DeleteMultiple() is used, it must be possible to use the selection criteria to select the object instances to be deleted. To do this you can create selection parameters.


Implement the interface of a Delete() BAPI so that it is not possible to delete all the instances simply by parameterizing the interface, for example by specifying default settings.

Export Parameters

To report messages from the method call back to the calling program, you should create only the export parameter Return . For more information about this parameter see Return Parameters (Error Handling).

Extension parameters

You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.

Locking

We recommend that you implement Delete() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.



Cancel()
Unlike the BAPI Delete () the BAPI Cancel() cancels an instance of a business object, that is the instance to be cancelled remains in the database and an additional instance is created that is canceled).
The Cancel() BAPI is an instance method.

Programming Cancel() BAPIs
Use
The Cancel() BAPI cancels one instance of a business object.
Unlike the BAPI Delete(), which deletes an object instance from the database, with the BAPI Cancel():

• The canceled instance of the business object is not deleted
• An additional instance is created with which the instance of the business object is deleted
The Cancel() BAPI is used to cancel business processes such as goods movements or invoice receipts.
The Cancel() BAPI is an instance method.

Features

Import Parameters

The data of the instance to be created comes from the data of the business object instance to be cancelled.

You can also create further parameters to specify information relevant for the actual cancellation process, for example, the name of the user performing the cancellation.

If required, you can also create a test run parameter, which can check the details of the object instance before it is actually canceled. For more information about this parameter see Test Run Parameters.

Export Parameters

To report messages from the method call back to the calling program, you should create the parameter Return. For more information about this parameter see Return Parameters (Error Handling).
You have to put the key of the created instance in another export parameter.
Locking
We recommend that you implement Cancel() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.

Add and Remove
The BAPI Add adds a sub-object to an existing object instance and the BAPI and Remove removes a sub-object from an object instance. These BAPIs are instance methods.