Actions by the BAPI Developer (SAP Library - Enhancements, Modifications, ? (CA-BFA))

loop at extensionin.

case extensionin-structure.

when 'BAPI_TE_STRAVELAG.

move extensionin+c_lenstruc to wa_bapi_te_stravelag.
* Constant c_lenstruct possesses the length of field
* STRUCTURE of structure BAPIPAREX. This constant
* ensures that only the values from VALUEPART1 through
* VALUEPART4 are assigned to the table extension .
read table t_stravelag with key agencynum = agencynumber.
catch system-exceptions conversion_errors = 1.

move-corresponding wa_bapi_te_stravelag to t_stravelag.

Actions by the BAPI Developer

Purpose

BAPI developers must first supply the ExtensionIn and/or ExtensionOut parameters in the BAPI interface, as well as a maximum of two BAdIs in the BAPI function module, according to the requirements of the specific BAPI. This allows the customers to implement all three types of enhancement with this BAPI.

Developers can also support customers further by anticipating which SAP database tables might sensibly be appended with customer fields, and which existing fields from other tables might be included in the BAPI.

Process Flow

The example below explains which actions a BAPI developer would have to perform for a specific case. In this example, we will design an extendable BAPI TravelAgency.CreateFromData and provide for specific enhancements to database table STRAVELAG.

We can divide our activities into the following five steps:

Creating the extension parameter in the BAPI interface
Depending on the requirements made of the BAPI in question, the BAPI developer creates one extension parameter for the data import (ExtensionIn) and/or one extension parameter for the data export (ExtensionOut) in the interface of the BAPI function module.
You must observe the following guidelines:

		The naming convention for the extension parameter is ExtensionIn for import parameter enhancements and ExtensionOut for export parameter enhancements.
		The extension parameters must be defined as table parameters.
		The extension parameters are always based on reference structure BAPIPAREX.
		All the BAPI table extensions used in the BAPI and their assignment to the respective BAPI parameters must be described in the documentation of the extension parameter.

Note

The section Use with the Standardized BAPIs contains recommendations on which extension parameters to used for the individual standardized BAPIs.

Defining the BAPI table extensions
This step is only necessary if you plan to think about underlying SAP tables for the BAPI that the customers can sensibly enhance with their own fields and existing fields. If so, use transaction SE11 to create a BAPI table extension as a data structure for every SAP table that can be sensibly extended. The following guidelines have to be observed when creating BAPI table extensions:

		The naming convention for BAPI table extensions is BAPI_TE_<table_name>. If you cannot follow this naming convention due to the length restriction for structure names, then you must specify this explicitly in the documentation of the table extension and the BAPI.
		Create one BAPI table extension for each table to be extended. Please note, however, that each table can only have one table extension. Therefore, if several BAPIs use the same table, they will have to share the table extension.
		Exception:	If a BAPI has two or more parameters that refer to the same database table, then a separate BAPI table extension is created for each of these BAPI parameters. The naming convention in this case is BAPI_TE<table_name><consecutive_number>. In our example, the table extensions would be called BAPI_TE_STRAVELAG1, BAPI_TE_STRAVELAG2, and so on.
		The structure of the BAPI table extension must contain all the identified key fields of the table to which the BAPI table extension relates. The table extension does not contain any other fields except the key fields.

In the above example, the BAPI table extension must be called BAPI_TE_STRAVELAG and possess key AGENCYNUM.

Modifying the BAPI function module
At the most, each BAPI function module can have the following structure:

FUNCTION BAPI_ERWEITERUNG_TEST

<BADI_1>

<BADI_2>

END FUNCTION

Therefore, in the most complex case, BAPI developers must allow customer enhancement to their function modules in three places:

BAdI 1
This BAdI is only required if the BAPI has an ExtensionIn parameter. This BAdI allows the customer to check all the data that is passed on to the BAPI, including the ExtensionIn parameter. The BAdI must have the following parameters:

			All BAPI import parameters and tables are passed on as an import. In particular, the ExtensionIn parameter must be available in the BAdI.
			The BAdI must return the Return parameter as an export, to allow the BAPI to report any errors that occurred in the BAdI.
			If required by the application, additional parameters can also be passed on to the BAdI as import or export.

Reading ExtensionIn
This step is only required when the customer has added their own fields to an SAP table or included existing fields in the BAPI, and the developer wants to make sure that the enhancements passed on in the ExtensionIn are automatically written to the additional table fields. This means no customer programming is required to write the customer enhancements directly to the corresponding database tables.
In particular, program this automatic filling of the extended fields in the case of Create()- , Add<sub-object>()- , and SaveReplica()- BAPIs.

The extraction of a data record from the container is performed in two steps:

		a)	The container format is first converted to the required temporary structure by the corresponding BAPI table extension. Because the values have the same sequence in both the container and the BAPI table extension, this can be implemented with a single MOVE command.
		b)	This structure is then used to fill the additional database fields with MOVE-CORRESPONDING. To do this, the corresponding key value must be used to determine the line in the database where the values will be inserted.

The entire process can be described in pseudo-coding as follows:

LOOP at ExtensionIn
	IF required table extension exists in ExtensionIn
		THEN MOVE values from ExtensionIn TO table extension END.
		Find correct line in database table. Fill database table with table extension using MOVE-CORRESPONDING.
END LOOP

Therefore the table enhancements can only be filled automatically when the fields the customer added to the BAPI table extension correspond exactly with the fields of the extended table, as the MOVE-CORRESPONDING command only works in this case.

Our concrete example results in the following coding:

Exception:

In the case of Create() BAPIs with internal number assignment, the value of the key is not yet know when the BAPI is called, and therefore cannot be included in the container. As a consequence, the key value generated in the BAPI must be explicitly assigned to the table extension after the container has been extracted. In this case, we would modify the above example as follows:

BAdI 2
This BAdI is required when the customer is allowed to further process the data passed on with ExtensionIn or otherwise manipulate the database. If the customer has enhanced the export parameters of the BAPI, the second BAdI must be used to fill the ExtensionOut parameter. The BAdI must have the following parameters:

			The BAdI is given all BAPI import parameters, including ExtensionIn, as an import. Table parameters in the BAPI function module remain as tables in the BAdI.
			The BAdI must return ExtensionOut and the Return parameter as an export.
			If required by the application, additional parameters can also be passed on to the BAdI as import or export.

Note

The section Use with the Standardized BAPIs contains recommendations on which precautions should be taken for the respective underlying function modules.

A detailed programming example for implementing a BAPI module is available under Examples.

Filling ExtensionIn before a BAPI call
If the coding supplied by SAP calls a BAPI, the developer has to decide whether or not to automatically fill the ExtensionIn parameter with the enhancements before the call. In this case, the filling of ExtensionIn has to be programmed explicitly. The concrete data flow for filling ExtensionIn is described under Actions by the Customer.

Evaluating ExtensionOut after a BAPI call
If the coding supplied by SAP calls a BAPI, the developer can make sure that the ExtensionOut parameter is evaluated automatically. Please note, however, that evaluations of this type can only be anticipated in rare cases.