Business Application Programming Interface

Definition

A Business Application Programming Interface (BAPI) is a precisely defined interface providing access to processes and data in business application systems such as R/3.

BAPIs are defined as API methods of SAP Objects. These objects and their BAPIs are described and stored in the Business Object Repository (BOR).

Use

BAPIs can be called within the R/3 System from external application systems and other programs. A BAPI call can either be made as an object oriented method call or as a remote function call (RFC).

BAPIs are a global communication standard for business applications.

Examples of what BAPIs can be used for include:

�� R/3 satellite systems

�� Distributed R/3 scenarios using Application Link Enabling (ALE)

�� Connecting R/3 Systems to the Internet using Internet application components (IACs)

�� Visual Basic programs as front ends to R/3 Systems

�� Work flow applications that extend beyond system boundaries

�� Customers' and partners' own developments

�� Connections to non-SAP software

�� Connections to legacy systems

Business Object Repository (BOR)

Definition

The Business Object Repository (BOR) is the object oriented repository in the R/3 System. It contains, among other objects, SAP Business Objects and their methods.

In the BOR a Business Application Programming Interface (BAPI) is defined as an API method of an SAP Business Object. Thus defined, the BAPIs become standard with full stability guarantees as regards their content and interface.

Use

With regard to SAP Business Objects and their BAPIs, the BOR has the following functions:

• provides an object oriented view of R/3 System data and processes.

R/3 application functions are accessed using methods (BAPIs) of SAP Business Objects. Implementation information is encapsulated; only the interface functionality of the method is visible to the user.

• arranges the various interfaces in accordance with the component hierarchy, enabling functions to be searched and retrieved quickly and simply.

• Manages BAPIs in release updates.

BAPI interface enhancements made by adding parameters are recorded in the BOR. Previous interface versions can thus be reconstructed at any time.

When a BAPI is created the release version of the new BAPI is recorded in the BOR. The same applies when any interface parameter is created.

The version control of the function module that a BAPI is based on is managed in the Function Builder.

• Ensures interface stability.

Any interface changes that are carried out in the BOR, are automatically checked for syntax compatibility against the associated development objects in the ABAP Dictionary.

Integration

You should only define a BAPI as a SAP Business Object method in the BOR if the function module that the BAPI is based on has been fully implemented.

Full access to the BOR is restricted to the persons responsible for the objects involved and for quality control.

BOR-BAPI Wizard

The BOR-BAPI Wizard assists with creating new BAPI methods in the BOR. It takes you through the creation process step by step.

_________ __________________________________________________________________ 4 A _____________________________

Transaction Model for Developing BAPIs

Purpose

The transaction model in which BAPIs are used determines how you have to program BAPIs.

The transaction model described here has been used to develop BAPIs for R/3 Releases 3.1 and 4.0A.

Logical Unit of Work (LUW) and Statelessness

Within the context of this transaction model a transaction represents one processing step or one logical unit of work (LUW). When a transaction is called, database operations are either fully executed or not at all. The whole transaction must be programmed to be stateless.

This transaction model requires that:

• no data is imported that may indirectly affect the result. If a transaction is called more than once, each call must have the same result.

For BAPIs this means, for example, that Set or Get parameters cannot be used. However, you can keep Customizing data in a global memory as this data remains unchanged even if transaction calls are repeated.

• there must be no functional dependencies between two transactions.

• either all relevant data has to be changed in the database or none at all.

The following sections describe how the transaction model effects BAPI development:

• Using the Transaction Model in Release 3.1

• Using the Transaction Model in Release 4.0A

Using the Transaction Model in Release 3.1

Purpose

The example below of an external program calling a BAPI to change data in an R/3 System, illustrates how the transaction model affects BAPI development in Release 3.1. Assume the transaction was written in, for instance, Visual Basic and that data is to be changed in the R/3 System only.

The RFC connection is live the whole time the external program is logged on to the R/3 System to avoid having to connect and disconnect repeatedly. When the RFC connection is already established, an RFC call does not essentially take up any more CPU time than a direct call to the function module from within the R/3 System.

There is one BAPI call for each transaction in the transaction model supported in 3.1. BAPIs can only be called synchronously. A BAPI call is essentially the call of the underlying RFC capable function module.

Process Flow

The process flow of the program consists of the steps below (see graphic):

Log on

_________ __________________________________________________________________ 5A _____________________________

..... (Visual Basic source code)

Call BAPI to read and/or change data

..... (Visual Basic source code)

Call BAPI to read and/or change data

..... (Visual Basic source code)

Log off

Prerequisites

What do the terms "LUW" and "statelessness" mean to BAPIs that are implemented in the framework of this transaction model?

If a transaction represents one Logical Unit of Work and in addition is supposed to be stateless, BAPIs are affected as follows:

• Initial state each time a BAPI is called

A repeated call of one BAPI must produce the same result. Only data that is not affected by the execution of the BAPI, for example, customizing data, can be buffered.

• No functional dependency between two BAPIs

A BAPI call must not be negatively affected by an earlier call of another BAPI. A follow up call must not presuppose an earlier call.

• All or nothing principle

A database change, for example, creating a new sales order, must be carried out completely or not at all (LUW).

This is why BAPIs to be implemented in 3.1 are created with integrated commit control. The "Commit Work" command is always invoked at the end of the function module of a BAPI that modifies data.

_________ __________________________________________________________________ 6 A _____________________________

Using the Transaction Model in Release 4.0A

Purpose

In Release 4.0A the Commit control must be taken out of write BAPIs, that is, those BAPIs that cause database changes. However, the existing transaction model used in Release 3.1 should not be changed. This is achieved by using the RFC capable function module BAPI_TRANSACTION_COMMIT which executes the command "Commit Work".

This procedure is required because BAPIs are used for continued development of the R/3 System, for example, for separating individual R/3 components. If this is the case, BAPIs must support the transaction model used in the R/3 System.

Features

A program based on this transaction model could consist of the following steps (see graphic):

Log on

..... (Visual Basic source code)

Call BAPI to read and/or change data

Call BAPI_TRANSACTION_COMMIT

..... (Visual Basic source code)

Call BAPI to read and/or change data

Call BAPI_TRANSACTION_COMMIT

..... (Visual Basic source code)

Log off

_________ __________________________________________________________________ 7A _____________________________

Defining and Implementing the BAPI

Purpose

A BAPI is an API method of a business object and is defined as such in the Business Object Repository (BOR). However, a BAPI is implemented as an RFC capable function module which is maintained in the Function Builder.

For function modules that implement BAPIs certain standards and rules must be adhered to over and above the standard programming rules for function modules. This section describes how to define a BAPI and which particular guidelines to comply with.

When implementing BAPIs follow the requirements below to ensure you achieve consistent behavior and representation of BAPIs as object oriented methods of SAP Business Objects.

There is a range of BAPIs that provide basic functions and these can be implemented for most of the SAP Business Objects. For information on these BAPIs see the section Frequently Used BAPIs. Check if the BAPI you want to implement is in one of these general categories.

Process Flow

The process of defining and implementing a BAPI consists of the following steps:

• Describing the Scenario in which the BAPI is used

• Reviewing the BAPI Concept and BAPI Scenario

• Defining a BAPI and Its Interface

• Creating Individual Programming Objects

• Testing the BAPI

• Releasing and Freezing the BAPI

_________ __________________________________________________________________ 8 A _____________________________

Frequently Used BAPIs

Definition

Some BAPIs and methods provide basic functions and can be used for most SAP Business Objects. These BAPIs are:

BAPIs for Reading Data

The following BAPIs provide you with read-only access to data in the associated Business Object:

• GetList

With this BAPI you can select a range of object key values, for example, company codes and material numbers. To specify appropriate selection requirements the calling program must pass the relevant parameters to the interface.

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. The key values can then be passed on to another BAPI for further processing, for example, the BAPI GetDetail, as listed below.

For further information on programming GetList BAPIs see Programming Value Ranges.

• GetDetail

The BAPI GetDetail uses a key to retrieve details about a specific instance of an object and returns this data to the calling program.

• GetStatus

The BAPI GetStatus is used to query the status of an SAP Business Object, for example, to determine 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.

• ExistenceCheck

The BAPI ExistenceCheck checks whether an entry exists for an SAP Business Object, for example, whether the customer master has been created. You should implement this method as a workflow method and not as a BAPI (RFC capable function module).

The method CompanyCode.ExistenceCheck of the business object CompanyCode (BUS0002) is an example of this. This workflow method is indirectly invoked when the calling program instantiates an object, for example, by using GetSAPObject("CompanyCode") from within Visual Basic.

BAPIs for Creating or Changing Data

The following BAPIs can create, change or delete instances of a business object:

• Create or CreateFromData

The BAPI Create or CreateFromData creates an instance of an object, for example, a sales order.

• Change

The BAPI Change changes an existing instance of a SAP Business Object, for example, a sales order.

For more information about the BAPI Change see Programming Replicate/Clone BAPIs.

• Delete

The BAPI Delete deletes an instance of a SAP Business Object, for example, a sales order.

_________ __________________________________________________________________ 9A _____________________________

BAPIs for Replicating Business Object Instances

The BAPIs below can be implemented as methods of business objects that can be replicated. For further information about these BAPIs see Programming Replicate/Clone BAPIs:

• Replicate

The BAPI Replicate is used by a client system to request clones of business objects in a server system.

This method must be implemented for each business object to be cloned.

At least one of the following BAPIs must be implemented for each business object to be cloned:

• Clone

The BAPI Clone is used by a system to replicate one business object on another system or to modify one business object that has already been cloned.

• CloneMultiple

The BAPI CloneMultiple is used by a system to replicate several business objects on another system or to modify several business objects that have already been cloned. Unlike the BAPI Clone, the BAPI CloneMultiple can replicate or modify several business object instances at the same time.

_________ __________________________________________________________________ 10 A _____________________________

Defining a BAPI Scenario

Purpose

Before you program a BAPI you should clearly define the processes and situations the BAPI will be used for.

Process Flow

To define the scenario the BAPI is to be used for, consider the following issues:

• Which scenario is to be implemented?

Every BAPI should be based on a model of a scenario in which it can be usefully employed. You can describe the scenario in the form of a process model.

• Which SAP Business Objects are involved?

From the scenario definition and with the help of the process model you can get information about the SAP Business Objects relevant to the BAPI scenario.

Example

In the scenario to be implemented, a BAPI is required to read data about a creditor. First of all, a list of creditors is to be displayed from which a specific creditor can be selected. Then, using another BAPI, specific details about this creditor are to be displayed.

The relevant SAP Business Object for this scenario is Creditor.

• What functionality should the BAPI provide and how does it affect related BAPIs, especially the other BAPIs of the SAP Business Object in question?

In line with the scenario concept BAPIs must complement each other to create a complete scenario. Their relationships with each other must be clearly defined.

Example

To read a creditor's details as described in the above scenario, two BAPIs are required:

- Display list of creditors

- Display details of a specific creditor

The interdependency between these two BAPIs is evident because first the creditor list is displayed to obtain the ID of the specific creditor sought. From this ID, details of this creditor can then be displayed.

However, the two BAPIs remain functionally independent of each other, because if the creditor ID is known, the BAPI "Display details of a specific creditor" can be used without first calling the BAPI "Display list of creditors".

• To what extent can the BAPI's functionality be implemented within the scope of the business object?

A BAPI should be developed so that it provides functionality exclusively within the context of its associated SAP Business Object. If the data of a different SAP Business Object is to be read or updated then the appropriate interface for this object must be used. The functions or methods of these other objects are used implicitly (delegation principle).

Example

_________ __________________________________________________________________ 11A _____________________________

The BAPIs required to read creditor details in the above scenario are only able to access data in the SAP Business Object Creditor. Other object types are not involved.

• Is the BAPI assigned to the SAP Business Object in a meaningful and semantically correct way?

Result

Once you have considered these issues you will be able to clearly conceptualize the functionality of the planned BAPI(s). You will also have identified the SAP Business Objects relevant to the BAPI scenario.

Review

Purpose

In the previous step you created a concept for a scenario a BAPI could be applied to. You also defined relevant SAP Business Objects.

Before you implement the scenario and begin defining and developing the BAPI, you should carry out a review of the scenario concept.

Process Flow

You should carry out the review of the BAPI scenario in cooperation with all persons involved in the BAPI development and those responsible for quality control in your development group.

Result

Start developing the BAPI only after you have successfully completed the review.

_________ __________________________________________________________________ 12 A _____________________________

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 the BAPI will be based on.

Only after you have planned and defined these required details can you start to implement the BAPI, as described in Creating Individual Programming Objects and Programming BAPIs.

Process Flow

To define the scope and required components of the BAPI to be implemented, the following steps must be completed:

• Determining the SAP Business Object and Its Key Fields

• Defining the Interface Structure of the BAPI

• Identifying the name of the function group, or if a function group does not exist already, planning a name for one.

All BAPIs belonging to one SAP Business Object should be stored as function modules in one function group. Ascertain whether a function group has already been created for the BAPIs of the SAP Business Object in question. If a function group does not already exist, then plan a name for the one to be created.

You can use the default technical name (object type) of the SAP Business Object as the basis of the function group name. The technical name of a SAP Business Object usually takes the form of BUSnnnn, where n is a number. Use the suffix "nnnn" as the name of the function group. For example, if the technical name of the object is BUS1008 then the associated BAPI function group is called 1008.

To ascertain the technical name of the Business Object, open the Business Object in the Business Object Repository (BOR), as described in Determining the SAP Business Object and Its Key Fields. To display further details, for example, the object type, double click the name of the Business Object.

• Assigning a name to the function module

Choose a name that gives an indication of what the BAPI is used for. The naming convention is: BAPI_<Business Object name>_<method name>. For information about naming a method refer to Naming the Method in the BOR.

For example, in the case of a BAPI which reads details for the object type Creditor, the name of the associated function module is BAPI_CREDITOR_GETDETAIL.

• Naming Parameters in the Function Module

• Defining the format for passing the values in the function module interface.

Parameters must not be converted before they are passed to and from the BAPI interface. This is because BAPIs are programming interfaces and not end user interfaces. Exceptions are currency codes, ISO codes and fields with an internal key.

• Specifying the Required Objects in ABAP Dictionary

• Naming the Method in the BOR

• Naming Parameters in the BOR

_________ __________________________________________________________________ 1 _____________________________

123 Determining the SAP Business Object and Its Key Fields

You have to identify the relevant SAP Business Object in the Business Object Repository (BOR) and determine whether the key fields of the Business Object are relevant for your BAPI.

A key is defined in the BOR for most SAP Business Objects. This key can consist of several key fields. The contents of these key fields uniquely identify one individual instance of an SAP Business Object.

You can differentiate between instance-dependent and instance-independent BAPI methods. Unlike instance-independent methods, instance-dependent methods relate to one instance (one specific occurrence) of an SAP Business Object type, for example to one specific sales order.

In the case of instance-dependent BAPIs, the key fields of the corresponding SAP Business Object must be used as parameters in the function module the BAPI is based on so that the associated object instance can be identified. The names of the key fields in the SAP Business Object and the corresponding parameters in the BAPI function module must be the same, because the name links the key fields to the parameters.

All the key fields defined in the BOR for the SAP Business Object in question must be used as the parameters in the function module. For further information see Defining the Interface Structure of the BAPI.

Example

SAP Business Object Creditor has a key field named CreditorId.

This key field must be defined as a parameter with the name CREDITORID in the function modules of the instant-dependent BAPIs for this Business Object.

To display the Business Object and its key fields follow the steps below:

1. Select Tools → ABAP Workbench → Overview → Business Object Browser . The business objects are displayed in the order of the R/3 application hierarchy.

2. Select the required SAP Business Object in the application hierarchy and double click it to open it.

3. To display the Business Object's key fields, expand the node Key fields.

_________ __________________________________________________________________ 14 A _____________________________

Defining the Interface Structure of the BAPI

Purpose

In this step you are going to define the BAPI interface, that is, the individual import, export and table parameters required for calling the BAPI.

Caution

You cannot use Changing and Exception parameters in a function module which implements a BAPI.

Process Flow

To define the interface parameters, proceed as follows:

1. Check whether the key fields of the SAP Business Object are required in the interface. The key fields of the SAP Business Object are some of the most important BAPI parameters.

- If a key value is to be passed to the BAPI by the calling program, the key field must be set as an import parameter in the function module of the BAPI. That way a specific instance of the Business Object is identified.

For example, this could be a customer number (CustomerNo) in the BAPIs Customer.GetDetail and Customer.CheckPassword, or the number of a sales document in the BAPI SalesOrder.GetStatus.

- For BAPIs that generate instances, for example, the BAPIs Create or CreateFromData, the key field of the Business Object should be set as an export parameter in the BAPI function module.

These BAPIs return one key value, for example, an order number in the BAPI SalesOrder.CreateFromData.

- For BAPIs that are class methods a key field is neither set as an import nor as an export parameter in the BAPI function module.

Class methods are instance-independent and are called without the use of key values. Usually they return a table with a selection of key values. Exceptions are write BAPIs, as described in the list item above.

2. Specify what other data is relevant as import, export or table parameters for the BAPI. Every BAPI must have an Export parameter return that reports messages back to the calling program.

Example

The BAPI to be developed is to read data from the SAP Business Object Creditor. To read creditor details, the calling program has to pass the ID of the creditor and the company code. The creditor data returned is to include general details, specific details and bank details.

To map these requirements onto the BAPI interface, the following parameters must be set in the function module which the BAPI is based on:

�� The key field CreditorID of the SAP Business Object as an import parameter

�� An import parameter for the company code

�� A Return parameter that reports messages back to the calling program

�� A parameter for general details of the creditor

�� A parameter for specific details of the creditor

�� A parameter for bank details of the creditor

_________ __________________________________________________________________ 15A _____________________________

Naming Parameters in the Function Module

Purpose

In the previous step you identified the contents of the interface parameters. Now you can specify the names of these parameters in the function module.

Prerequisites

You can only define export, import and table parameters in the function module interface of the BAPI.

Give meaningful names to the parameters in the function module interface to give the BAPI an easy-to-use interface. This is because the names you choose for the function module parameters are used in the Business Object Repository (BOR) as the names of the corresponding method parameters.

When assigning parameter names follow the guidelines below:

• The names must be in English

• The names of parameters in the function module can generally be a maximum of 30 alphanumeric characters. The names of parameters in a function module that implements a BAPI can only have a maxiumum of 20 alphanumeric characters, because the names of parameters in the function module must be identical to the parameter names in the BOR, and the latter are restricted to a maxiumum of 20 characters.

• The names of parameters in the function module must be written in capitals.

• Choose meaningful names and do not use abbreviations.

Example

In the above example based on the creditor scenario, the following parameters were identified:

• An import parameter for the key field CreditorId of the SAP Business Object

• An import parameter for the company code

• A Return parameter

• A parameter for general details of creditor

• A parameter for specific details of creditor

• A parameter for bank details of creditor

You could use the following names for these parameters in the function module:

Parameters and their Names in the Function Module

Contents	Name in Function Module	Parameter Type
Creditor number Company code General creditor details Specific creditor details Return parameter Bank details	CREDITORID COMPANYCODE CREDITORGENERALDATA CREDITORCOMPANYDATA RETURN CREDITORBANKDATA	IMPORTING IMPORTING EXPORTING EXPORTING EXPORTING TABLES