Structure of Parameter Documentation (SAP Library - BAPI Programming Guide (CA-BFA))

Structure of Parameter Documentation

Prerequisites

Parameter documentation consists of the keyblocks Description, Value Range, and Default Values. The information you enter in these keyblocks depends on the type of parameter. First you must therefore determine the following:

...

1. Whether the parameter you are documenting implements one of the key fields of the business object

Check in the BAPI Explorer (transaction BAPI) if the parameter to be documented is displayed as a key field in the associated business object, or actually as a parameter in the BAPI.

2. Whether the parameter you are documenting is the Return parameter.

3. Whether the parameter you are documenting relates to a single field, a structure, or a table.

To find this out, select the appropriate tab "Import", "Export" or "Tables" in the Function Builder to display the required parameter. Double-click the field Reference field/Reference structure to display the ABAP Dictionary. There you can find out information about the structure of the parameter:

○ For structure-based parameters, the Reference field/Reference structure field contains the name of the structure. The BOOKINGDATA parameter in the BAPI_FLBOOKING_CREATEFROMDATA function module (which implements the FlightBooking.CreateFromData() BAPI) is based on the BAPISBONEW structure, for example.

○ For parameters based on a single field, the Reference field/Reference structure field contains the name of the structure, followed by a hyphen (-), followed by the name of the field in the structure on which the parameter is based. The RESERVE_ONLY parameter in the BAPI_FLBOOKING_CREATEFROMDATA function module (which implements the FlightBooking.CreateFromData() BAPI) is based on the BAPISBODAT-RESERVED field (the RESERVED field in the BAPISBODAT structure), for example.

Procedure

Using Same Parameters in Several BAPIs

Using transaction SE61, you can write a general text for parameters that are used in several BAPIs at the same time.

You insert this text in the respective parameter documentation by setting an INCLUDE link. To do this, in the parameter documentation, insert the character /: on the left side in the format column and the command INCLUDE <name of general text> in the relevant lines in the SAPscript editor.

Documenting Single-Field Parameters

If the parameter refers to a single field only, determine whether there is any data element documentation for this field. This is described in Checking or Writing Data Element Documentation. If not, you have to write the data element documentation.

Check whether the data element documentation describes the parameter in sufficient detail.

Parameter documentation is then structured in the following way:

Keyblock	Contents
Meaning	If the data element documentation describes the parameter sufficiently, enter the following standard sentence in the keyblock: “For information on the definition of <short text>, see the corresponding data element documentation: <hyperlink to data element documentation>.” If other information is relevant for this parameter, you should add it here. If the data element documentation is not appropriate, describe the business content of the parameter.
Value Range	Include any fixed values and their effect. Also say whether a check is carried out and how invalid values are handled. The following generally applies: Generally you should not provide information on data types given in the ABAP Dictionary, as this cam be accessed in the ABAP Dictionary. Only provide information on data types if it will be useful. This keyblock should not contain Customizing information that could vary from system to system.
Default	Assigning parameters default values. Only describe this information for import parameters. Specify whether a value has been assigned to this field via Customizing and indicate that this makes the field read-only.

Documenting Structure/Table Parameters

If the parameter relates to a structure or table, make sure that data element documentation has been written for each field in the structure/table. This is described in Checking or Writing Data Element Documentation.

Parameter documentation is then structured as follows:

Keyblock	Contents
Meaning	Describe the business content of the parameter. Do not use any information provided in the data element documentation. Do not describe the fields themselves - the BAPI Explorer automatically includes the data element documentation for each field into the parameter documentation. Instead, specify: ● Which field must be filled so that the parameter is valid, that is the mandatory fields. ● The dependencies between fields. For example, if a specific field must/can be filled may depend on another field being filled. Enter the character /: on the left side in the format column of the SAPscript editor and the command INCLUDE BAPI_DATAELEMENT in the relevant lines in the SAPscript editor. This automatically inserts the following sentence: “For more information on the individual parameter fields, see the data element documentation in the ABAP dictionary.” Extension Parameters For *ExtensionIn* parameters, insert the following standard sentence: "This parameter acts as a data container. In the parameter you can transfer additional data that was not planned at the interface to the method. The data is transferred in one table. The format of the data records in this table is determined by the BAPIPAREX structure. This structure contains multiple data record fields (VALUEPART1, VALUEPART2, ...) and one field for the name of a help structure that is created by the customer (STRUCTURE). Since the data for each data record is written to the corresponding data record fields in parts one after the other, a help structure is required for interpreting the data. If customers want to add fields to an SAP database table, we recommend that they use BAPI Table Extensions as help structures. For more information about various customer enhancements and about which help structures to use, see the Customer Enhancement and Modification of BAPIs document in the SAP Library under CA-BFA: Enhancements, Modifications ... To do this, enter the /: character on the left-hand side in the format column and enter the INCLUDE BAPI_EXTIN command on the right-hand side in the SAPscript editor. For *ExtensionOut* parameters, insert the following standard sentence: "This parameter acts as a data container. You can use this parameter to return additional data that was not planned at the interface. The data is transferred in one table. The format of the data records in this table is determined by the BAPIPAREX structure. This structure contains multiple data record fields (VALUEPART1, VALUEPART2, ...) and one field for the name of the help structure (STRUCTURE). Since the data for each data record is written to the corresponding data record fields in parts one after the other, a help structure is required for interpreting the data. If customers want to add fields to an SAP database table, we recommend that they use BAPI Table Extensions as help structures. For more information about various customer enhancements and about which help structures to use, see the Customer Enhancement and Modification of BAPIs document in the SAP Library under CA-BFA: Enhancements, Modifications ... To do this, enter the /: character on the left-hand side in the format column and enter the INCLUDE BAPI_EXTOUT command on the right-hand side in the SAPscript editor.
Value Range	Include any fixed values and their effect. Also say whether a check is carried out and how invalid values are handled. For ExtensionIn and ExtensionOut parameters: If these are combined with BAPI Table Extensions, list all available BAPI Table Extensions. The following generally applies: Generally you should not provide information on data types given in the ABAP Dictionary, as this cam be accessed in the ABAP Dictionary. Only provide information on data types if it will be useful. This keyblock should not contain Customizing information that could vary from system to system.
Default	Assigning parameters default values. Only describe this information for import parameters. Specify whether a value has been assigned to this field via Customizing and indicate that this makes the field read-only.

Documenting Return Parameters

Each BAPI has a Return parameter that returns messages to the application that called the BAPI. Application programmers wanting to use BAPIs must know exactly which messages can be returned by the BAPI so that they can process them in their applications.

When a BAPI is being called, it can call other function modules that can return their own messages. This is why BAPI messages must be listed in the documentation of the Return parameter as well as important or likely messages that are generated by other function modules or programming objects and then passed to the calling program via the BAPI. Ask your BAPI developer about this.

All BAPI messages are entered in table T100. It is easiest if you ask the developer responsible to give you a list of error messages in the table structure described below. It is important that you do not make any changes to the messages in table T100 without first discussing them with your developer. Such changes could affect the stability of the BAPI interface guaranteed by SAP because the changes may be semantically incompatible.

Parameter documentation is then structured as follows:

Keyblock	Contents
Meaning	To define the parameter, enter a standard sentence using the INCLUDE command as follows: Insert the character /: on the left side in the format column of the SAPscript editor and the command INCLUDE BAPI_TABLE in the relevant lines in the SAPscript editor. This automatically inserts the following sentence: "This table contains the return messages from the method call." Some BAPIs perform a database rollback when an abort message (type A) occurs in the Return parameter, revoking all activities since the last COMMIT WORK command. Document this explicitly, if this is the case.
Value Range	Specify all the return codes for your BAPI, including possible messages that may be indirectly returned to the calling application via the BAPI. Enter the return values in a table under the following columns (specify the format PE instead of AS in the format column): Type ID Number Message To group the error messages together, you should divide the table into theme areas. For example: Authorization messages Type ID Number Message E FN 019 Cannot access … E FN 020 No authorization for… Messages on value checks Type ID Number Message E FN 021 Flight .....does not exist Under the heading: Other possible messages enter the most important or likely messages generated by other function modules and passed to the calling program via the BAPI. Notes for BAPIs in Release 3.1: If you are documenting a BAPI implemented in Release 3.1, the table consists of the following columns only: Type Code Message For example, enter: Type Code Message E FN020 Flight ..... does not exist.
Default	Leave empty.

Documenting Parameters that Implement Key Fields

Some BAPIs use the key fields of their business object. These are implemented as parameters in the function module the BAPI is based on.

Find out whether the key field of the business object has been documented. If required, create the documentation as data element documentation, as described in Checking or Writing Data Element Documentation.

In the parameter documentation itself, refer to the key field documentation as follows:

Keyblock	Contents
Meaning	Define the parameter by entering a standard sentence with an INCLUDE command. To do this, proceed as follows: Enter the character /: on the left side in the format column of the SAPscript editor and the command INCLUDE BAPI_KEYFIELD in the relevant lines in the SAPscript editor. This automatically inserts the following standard sentence: "This parameter implements the key field of the business object with the same name. See the documentation for the key field for more information about this parameter.”
Value Range	Leave empty.
Default	Leave empty.