BAPI Programming Guide (CA-BFA)

This BAPI Programming Guide describes the development process when developing new
BAPIs. These guidelines also apply to enhancing and modifying existing BAPIs.

The following links lead to more detailed information and guidelines in the area of BAPI
development:

• General Introduction to BAPIs

• Customer Enhancement and Modification of BAPIs
• SAP Enhancements to Released BAPIs
• BAPIs for Mass Data Transfer
• Using the ALE Services

Introduction
Business Object Types and BAPIs
Business Application Programming Interfaces (BAPIs) enable access to SAP functions
across formal, stable and dialog-free interfaces. These interfaces can be used by
external applications developed by customers and complementary software partners as
well as by other SAP applications.

BAPIs are defined as API methods of SAP Business Object Types. These object types
are used to enable object-based communication between components. Business objects
and their BAPIs enable object orientation to be used in central information processing in
companies. For example, you can reuse existing functions and data, achieve trouble-free
technical interoperability, and implement non-SAP components.
Applications can use BAPIs to directly access the application layer of the SAP System
and, as clients, applications can use the business logic of the SAP System. BAPIs
provide the client with an object-oriented view of the application objects, without needing
to know the implementation details.

BAPIs are always developed by defining scenarios. These scenarios are used to map
and implement system-wide business processes.

BAPI Explorer as a Central Development Tool

The working environment for developing BAPIs is provided by the BAPI Explorer. The
BAPI Explorer enables you to quickly find BAPIs that exist in the system. An interactive
project form that contains a checklist with the most important guidelines in this document
supports you in all phases of your BAPI development. In the BAPI Explorer you can also
navigate to the most important tools for developing your BAPI.

Interface Repository as a Central Storage for BAPIs

The standard SAP interfaces and all BAPIs are published centrally in the XML-based
Interface Repository (IFR). They are stored as XML schema, which means that they are
directly available for use in integration scenarios where multiple components
communicate with one another using the Internet. You can access the Interface
Repository in the Internet using the following address: http://ifr.sap.com.

Target Group of the Documentation

This documentation describes the guidelines SAP uses for developing and implementing
BAPIs to ensure that the development of BAPIs is as standard as possible. These
standards make BAPIs easy to use.
This programming guide is targeted at SAP developers, partners and customers who
want to implement BAPIs.

Demo Business Objects and Methods

As of Release 6.20, the business objects Flight (flight booking), FlightCustomer
(customer), FlightBooking, FlightConnection, and FlightTrip, and their BAPI methods, are
available for demo purposes.

These business objects and their BAPI methods can be used to develop simple
applications to map the business processes involved in flight bookings.

You can write a Web application for flight bookings, for example.

It is therefore possible to use simple example scenarios to gain a basic understanding

about BAPIs and how to use them.

The demo business objects and BAPI methods also serve to illustrate the BAPI
guidelines that are described in this document. That is why there are references to the
demo methods at certain places in this document. You can then use the BAPI Explorer to
view the method in the SAP System, and to read the corresponding online documentation
about the business object, the BAPI function module, and the parameters.

See also:

For more information on example scenarios that can be realized with these methods, see
Flight Data Application – Demo Example for Integration Technologies.

For examples of how to realize BAPI programming guidelines, see Technologies and
Concepts.
Overview of Development Process
This section describes the process of developing new BAPIs. The guidelines also apply
to enhancing and modifying existing BAPIs.

For more information about enhancements and modifications, see the following:

• Customer Enhancement of BAPIs

• BAPI Modifications
• SAP Enhancements to Released BAPIs

Prerequisites
To implement a BAPI using these programming guidelines, you need:

• Basic understanding of BAPIs

• Knowledge of the ABAP programming language
• General knowledge of SAP Systems

Process Flow
The entire development process can be divided into four phases:
1. Analysis:
The analysis phase involves determining which business process is to be
implemented using the BAPI. Scenarios are defined and then the steps that are to be
visible externally (to other components) and implemented by business object types
and their BAPIs, are identified.

2. Design:
For each BAPI involved in a scenario, the structure of the BAPI's interface is defined
at a conceptual level. The purpose of the design phase is to structure the interfaces
concisely and intuitively so that the BAPIs will be easy to use. At the same time the
interfaces must comply with all technical and formal guidelines.

3. Implementation:
The implementation phase can be divided into three successive stages:

• Defining the data structures (including domains and data elements) that the
BAPI parameters are based on.
• Implementing the program logic in function modules.

• Defining the BAPI in the Business Object Repository (BOR) to ensure

object-oriented access.

4. Test and release:

The documentation as well as the functionality and usability of a BAPI are checked in
the test phase. The BAPI can be released once the test phase has been completed.

Tool Support

The BAPI Explorer (Transaction BAPI) is the central tool as of Release 4.6A to support
your BAPI developments. The BAPI Explorer enables easy access to all the relevant
information in the BAPI environment (including general documentation as well details
about special business object types and BAPIs). The Explorer integrates all the tools
required for BAPI development and uses project forms to manage all the phases of the
development process.

See also:

Details about the BAPI Explorer.

 Analysis
For analysis purposes, the business process, and the scenario implementing this
business process have to be described in detail. The Business Object Types used in
the scenario and their BAPIs also need to be identified. The BAPIs are atomic modules
that can be used to create different scenarios.
The main dilemma with developing BAPIs is:

On the one hand, BAPIs should be developed so that they can be used in different
scenarios, and on the other hand, the interface must be clearly structured.

It is important that you do not stipulate in this phase exactly what the signature of the
individual BAPIs is to look like. The BAPIs required for the scenario are simply identified,
and their functions and the data they require are defined.

The analysis can be divided into three phases:

1. Describing the Scenario

2. Defining the Scenario in the BAPI Explorer

3. Reviewing the Scenario

1. Describing the Scenario

The Business Process
A business process consists of a series of individual business functions. The content of
the business process should be described separately from any technical details.

Creating a sales order in an affiliate with a credit standing check in the

central organization.

To define a business process you have to:

Define the purpose and the scope of the business process

Identify the individual steps in the business process To do this you can use a
process model or use cases.

The Scenario
A scenario is the computerized implementation of a business process. It describes the
distribution and interaction of the tasks between the participating components. So there
may be several scenarios that implement the same business process.

Creating sales orders and credit standing checks in different R/3

Systems (central accounting, decentralized sales and distribution).

The process of defining the scenario involves:

Identifying the relevant components and the tasks they perform.

Determining whether application systems are to be integrated in the scenario or

other frontends are to be connected. This can affect the granularity of the steps, for
example.

Determining the information and process flows. Here you have to:

Determine which steps are to be processed system-wide and which steps are
to be processed within a single component.

Define which data is exchanged between which components and who initiates
this exchange.

Determining the sequence in which the individual steps are processed.

Identifying the steps belonging to a single transaction (LUW). See also

Transaction Model for Developing BAPIs

Developers must ask themselves whether it makes sense to

create a customer in one LUW and then create a sales order
in the same LUW .

Error handling must be much more precise and comprehensive than with local
applications.

You have to decide whether system coupling should be narrow or loose for the
scenario . You should consider factors such as system availability and performance
and how often the scenario is used.

All steps critical to performance must be identified.

You should also consider which R/3 Releases are to be supported within the
scenario.

For each scenario you must identify a person responsible for ensuring that the
scenario is correct and up-to-date.

Business Object Types and BAPIs

Each component in the scenario must provide services so that the cross-component
steps can be carried out. You have to work out how to distribute responsibility for the
services between the business object types and their BAPIs. For example, the BAPI
CreateFromData of business object type FlightBooking is used to create a sales order in
the SAP System from an external application.

For further details, see also: Business Object types.

For each component you have to first determine the business object types required You
should consider the following issues:

Encapsulation of the required functions in business object types. This involves

breaking down the whole system into separate responsibilities. The breakdown and
encapsulation of functions must be explicit and disjunctive.

Do business object types already exist for these responsibilities?

Are these sufficiently differentiated to effectively cover the requirements of the
scenario?

Do design patterns already exist?

Find out whether any problems have already been dealt with.

Example: Header/item pattern, for example, for SalesOrder,

PurchaseOrder, etc.

Delimit the responsibility for other business object types.

Determine the services provided based on the defined responsibility.

For further details, see also Design Criteria for Business Object
Types.

For each business object type you have identified, you have to determine how the
services assigned to it can be implemented using BAPIs.
You should consider the following issues:

Each service is implemented by one or more BAPIs (= method of business object

type).

BAPIs make available the functions of a business object type. You should be able
to use them independently of individual scenarios and also in different scenarios.
 To make it easier to use a BAPI in various scenarios, the BAPI
signature should be created so that the BAPI's parameters and
fields are assigned separately according to the application.

However, this type of scenario can affect the granularity of the BAPI. Application
systems are integrated differently from the integration of alternative frontends:

1. Integrating application systems

• The integration of application systems typically involves program-to-

program communication, loose asynchronous coupling and the exchange of
larger volumes of data.
• The main requirement of the business object types and BAPIs used in
these scenarios is the guarantee of high performance that can be achieved,
for example, by minimizing the number of calls.
• The result is a rough granularity of the application that is implemented by
more extensive BAPIs.
• Example: A program to create a sales order automatically.
The program uses the business object type SalesOrder with the BAPI
CreateFromData. The complete sales order is created in the sending
system and then sent to the receiving system.

2. Integrating alternative frontends

• Scenarios with alternative frontends represent human-to-machine

communication and can be implemented synchronously as well as
asynchronously.
• Business object types and BAPIs must be structured to ensure flexibility,
configurability and minimal error situations.
• The result is a finer granularity of the application that should correspond to
the dialog processing in an SAP System.
• Example: Customer sales order is created interactively in the Internet.
The sales order can be created using the two methods CreateFromData
and AddItem of the business object type SalesOrder. In this case the
method CreateFromData simply creates the sales order header, whilst the
method AddItem can add new sales order items.

SAP internal: Wherever possible, a BAPI should be created so

that it can be used for both purposes. The most important objective
is to develop a range of standardized BAPIs for each business
object type that can be used universally.

The scenario must be structured so that it is possible to get all the information
required for a BAPI call from the SAP System from other BAPIs beforehand.

If there are any BAPIs that are Customizing-dependent, BAPIs must be provided
that can export these Customizing settings.
 SAP internal: The scenario, the link to the application's object
model, and the design of new business object types are agreed
with a member of the integration team.

If business object types that do not yet exist are identified during
the analysis phase, these object types can only be created by the
integration teams.

2. Defining the Scenario in the BAPI

Explorer
Prerequisites
The scenario is fully described.

Procedure
Define a project form in the BAPI Explorer as follows:

1. Start the BAPI Explorer in the relevant development system using Transaction
BAPI (as of Release 4.6A).
2. Select the tab page Project and create a project to implement new BAPIs.
3. A project form guides you through the entire procedure for creating a BAPI. In the
first section the basic data can be created for the defined scenario .

See also:

Details on BAPI Explorer

3. Reviewing the Scenario

Before the scenario can be converted and started with a concrete definition and
implementation of the BAPI, the scenario should be reviewed.
All persons involved in the BAPI development and those responsible for quality control
should be involved in this review.

Features
The following questions should be answered:
 Does the scenario make sense as it is planned?

Have all the tasks required for the scenario description been properly completed?

Do all the BAPIs in the scenario work smoothly together?

You should only start developing the BAPI, once you have successfully completed the
review.

See also:

Designing the BAPI

Designing the BAPI

After the scenario and the business object types used in it have been identified in the
analysis of the scenario, the BAPI signature is defined conceptionally within the design
phase. The content should be described and the parameter names and the parameter
structure must be defined.

Since BAPIs represent business interfaces and not technical ones, the following central
requirement for developing BAPIs arises:
In an external application, users must be able to correctly implement a BAPI call using
their knowledge of the application and the BAPI documentation alone. Users are not
expected to have any knowledge of SAP, so that they can view the SAP System as a
"black box".

In this phase you also have to decide from the BAPI's functions, whether the BAPI is an
instance method or a class method and whether it can be implemented as a standardized
BAPI.
Instance methods refer to a specific instance of a business object type; for example, the
BAPI Flight.GetDetail retrieves the details of precisely one flight. These methods are
defined as instance-dependent in the BOR.
Class methods do not refer to a specific instance of a business object type; for example,
the BAPI Flight.GetList supplies a list of all the existing flights that match specific criteria.
Standardized create methods also belong to class methods. A create method creates a
new instance. The BAPI FlightBooking.CreateFromData() creates a new flight booking in
the SAP System, for example. These methods are defined as instance-independent in
the BOR.

The specific instances of a business object type are identified by their key fields which is
why they play a special role in this context. In the design phase, the keys of instance-
dependent BAPIs should be identified as special parameters. For more details see
Defining the Interface.

When designing the BAPI signature you should keep in mind:

 1. The design of the method (BAPI) and the parameters must comply with certain
conventions See also Conventions.
2. There are a range of standard methods and parameters that provide basic
functions. If the BAPIs and their parameters fall into this category, they must be
structured according to specified rules. For an overview see Standardized BAPIs
and Standardized Parameters.
3. So that the signature is clearly structured and easy to use, you should follow the
design recommendations.

Conventions
The following conventions apply to BAPI methods.

If the BAPI to be implemented is a standardized BAPI, use the generic names, for
example, GetList, GetDetail.
You should particularly note the difference between reading and writing methods
and between simple and multiple methods.

The method name must be in English (maximum 30 characters).

The individual components of a BAPI name are separated by the use of upper and
lower case.

Example: GetList.

Underscores ("_") are not allowed in BAPI names.

Each BAPI has a return parameter that is either an export parameter or an export
table.

So that customers can enhance BAPIs, each BAPI must have an ExtensionIn and
an ExtensionOut parameter. See also: Customer Enhancement of BAPIs.

See also: Standardized BAPI.

The following conventions apply to parameters:

Obligatory parameters should be checked to see if they can become optional in the
future. This is important to avoid possible incompatible changes to the interface
and to guarantee the stability of the interface.

If standardized parameters are used, you have to use the names specified for
standardized parameters.

BAPI parameter names should be as meaningful as possible.

Poorly chosen names include abbreviations and technical names (e.g. "flag", table
names, etc.).
 The parameter and field names must be in English with a maximum of 30
characters.

The components of a parameter name in the BOR are separated by upper and
lower case letters to make them easier to read.

Example : FlightList.

Values that belong to each other semantically should be grouped together in one
structured parameter, instead of using several scalar parameters.

For ISO-relevant fields (country, language, unit of measure, currency), additional

fields for ISO codes are provided.

The CustomerData parameter of the

FlightCustomer.CreateFromData method contains, in addition to
the LANGU field (language key in SAP code), the LANGU_ISO field
(language key in ISO code).

For more information, see Actions in the ABAP Dictionary.

Unit of measure fields must accompany all quantity fields and currency identifiers
must accompany currency amount fields.

See the FlightList parameter of the Flight.GetList method: In

addition to the PRICE currency field (standard list price of the
flight), there is also the CURR currency field (local currency of the
airline).

See also: Standardized Parameters.

Standardized BAPIs
Use
Some BAPIs provide basic functions and can be used for most SAP business object
types. These BAPIs should be implemented the same for all business object types.
Standardized BAPIs are easier to use and prevent users having to deal with a large
number of different BAPIs. Whenever possible, a standardized BAPI must be used in
preference to an individual BAPI.
Features
The following standardized BAPIs are provided:

Reading instances of SAP business objects

• GetList ( )
With the BAPI GetList you can select a range of object key values, for example,
company codes and material numbers. The BAPI GetList() is a class method.
For more information see Programming GetList() BAPIs.

• GetDetail ( )
With the BAPI GetDetail() the details of an instance of a business object type are
retrieved and returned to the calling program. The instance is identified via its
key. The BAPI GetDetail() is an instance method.
For more information see Programming GetDetail() BAPIs.

BAPIs that can create, change or delete instances of a business object type

The following BAPIs of the same object type have to be programmed so that they can be
called several times within one transaction. For example, if, after customer 1 has been
created, a second customer 2 is created in the same transaction, the second BAPI call
must not affect the consistency of customer 1. After completing the transaction with a
Commit Work, both the customers are saved consistently in the database.

• Create( ) and CreateFromData( )

The BAPIs Create() and CreateFromData() create an instance of an SAP
business object type, a flight booking or a customer, for example. These BAPIs
are class methods.
For more information see Programming Create() BAPIs.

• Change ( )
The BAPI Change( ) changes an existing instance of an SAP business object
type. The BAPI Change () is an instance method.
For more information see Programming Change() BAPIs.

• Delete( ) and Undelete( )

The BAPI Delete() deletes an instance of an SAP business object type from the
database or sets a deletion flag.
The BAPI Undelete() removes a deletion flag. These BAPIs are instance
methods.
For more information see Programming Delete() / Undelete() BAPIs.

• Cancel ( )
Unlike the BAPI Delete(), the BAPI Cancel() cancels an instance of a business
object type, that is the instance to be cancelled remains in the database and an
additional instance is created which is actually canceled. The Cancel() BAPI is an
instance method.
For more information see Programming Cancel() BAPIs.
 • Add<subobject> ( ) and Remove<subobject> ( )
The BAPI Add<subobject> adds a subobject to an existing object instance and
the BAPI and Remove<subobject> removes a subobject from an object instance.
These BAPIs are instance methods.
For further information see Programming Methods for Sub-Objects.

BAPIs for Mass Data Processing

The BAPIs listed above for creating and changing data can also be used for mass
processing.
For more information, see BAPIs Used for Mass Data Transfer.

BAPIs for Replicating Business Object Instances

• Replicate( ) and SaveReplica( )

The BAPIs Replicate() and SaveReplica() are implemented as methods of
replicable business object types. They enable specific instances of an object type
to be copied to one or more different systems. These BAPIs are used mainly to
transfer data between distributed systems within the context of Application Link
Enabling (ALE). These BAPIs are class methods.
For more information see Programming Replicate()/SaveReplica() BAPIs.

Other Less Used Standardized BAPIs

• Programming GetStatus() BAPIs

• Programming ExistenceCheck() BAPIs

Standardized Parameters
Use
Some parameters can be created for various BAPIs because they contain the same or
the equivalent data in all BAPIs. They should be implemented the same in all BAPIs.

Features
Address parameters

Specific reference structures are defined for address parameters in BAPIs. You should
copy these structures to use in your BAPI, especially if the underlying object type uses
the central address management (CAM).
For more information see Address Parameters.

Change Parameters

In BAPIs that cause database changes (for example, Change() and Create() BAPIs) you
must be able to distinguish between parameter fields that contain modified values and
parameter fields that have not been modified. This distinction is made through the use of
standardized parameters.
For more information see Change Parameters.

Extension parameters

The parameters ExtensionIn and ExtensionOut provide customers with a mechanism that
enables BAPIs to be enhanced without modifications.
For further information, see Extension Parameters and Customer Enhancement of
BAPIs.

Return Parameters

Each BAPI must have an export return parameter for returning messages to the calling
application. To provide application programmers with a consistent error handling process
for BAPI calls, all return parameters must be implemented in the same, standardized
way.
For further information see Return Parameters.

Selection Parameters

Standardized selection parameters are used in BAPIs that can be used to search for
specific instances of a business object type (e.g. in GetList() ). These parameters enable
the BAPI caller to specify the relevant selection criteria.
For more information see Selection Parameters.

Test Run Parameters

The parameter TestRun is used in write BAPIs (Create() and Change() ), to check the
entries for the object instance in the database before actually creating the object
instance. The creation of the object instance is only simulated and data is not updated.
For further information see Test Run Parameters.

Text Transfer Parameters

To transfer BAPI documentation texts (e.g. the documentation of a business object type),
you have to create standardized text transfer parameters.
For more information see Text Transfer Parameters.

Design Recommendations for Interfaces

So that BAPIs can be used intuitively, you should follow the design recommendations
below:

Parameter data should be grouped together according to business criteria.

The inbound interface should be clearly structured and intuitive. Parameters should
in the first instance be structured in accordance with the application.

Example: Structured parameters should be structured so that they

contain all the fields required for the simplest application in one
logical block. Additional fields required for special cases should be
grouped by application and attached to the "main block".

The interface must not contain any fields that external users would not be able to
interpret. You must also try to remove any internal details specific to R/3.

You should check whether scalar parameters might be used in the future as (more
complex) selection parameters (for example in the definition of ranges).

To avoid later changes to the interface, which may be incompatible, parameters

should be created as "optional" wherever possible.

Whenever possible, search help (F4 help) should be provided for parameters and
parameter fields. This enables the client to easily determine all the possible input
values for a field by calling the BAPI Helpvalues.GetList.
See also: Providing Input Help (F4 Help)

A search help is defined for the AirlineID parameter (airline ID) in

the Flight.GetList method. If you call the Helpvalues.GetList
method, the system finds all existing airline IDs.

Dependencies between data fields and between parameters must be included in

the documentation.

All the information supplied with a BAPI should be able to be used easily without
having to change any of the data. So export structures should be able to be reused
as the input of a different BAPI.

All key fields in GetDetail() and GetList() BAPIs must be displayed as text fields.

If there are several texts for one key field, these texts must be
stored in a separate table.

When you are structuring the interface, you should consider what the BAPI is used
for.

• With BAPIs used for batch processing performance is the most important
consideration in the design.

• BAPIs used for alternative front-ends require a more flexible interface as

they tend to be used in more complex processes.
 See also Example of BAPI Conceptual Design.

Implementing a BAPI
Once you have completed the conceptual design of the BAPI, information specific to SAP
must now be considered in the implementation phase. For example, the SAP data
structures are determined and the program logic is implemented for the BAPI
parameters.

The following documentation provides an overview of the implementation process and

the relevant components and tools for the BAPIs are introduced. Each work step is then
described in detail.

See also:
The Implementation Process
Actions in the ABAP Dictionary
Actions in the Function Builder
Actions in the BOR
BAPI Documentation
BAPI/ALE Integration

The Implementation Process

A BAPI is defined in the Business Object Repository (BOR) as an API method of an SAP
business object type. Business object types and their BAPIs are described and created in
the BOR. A BAPI is usually implemented as an RFC-enabled function module. These
function modules are created and described in the Function Builder. The definitions and
descriptions of the data structures used by the BAPI are defined in the ABAP Dictionary.

The graphic below illustrates the relationships between the components:

Process Flow
The structure of the tools in the ABAP Workbench determine how the BAPI is
implemented.

1. Defining the Data Structures (including domains and data elements) in the ABAP
Dictionary.
2. Implementing the Function Module in the Function Builder
3. Defining the Business Object Type and Its Methods in the BOR

All three phases have accompanying documentation that is created in the

corresponding tools.

All the required worksteps can be started from the BAPI

Explorer.

See also:

Tools
Further Issues

Actions in the ABAP Dictionary

The first step of the implementation phase is to define all the data structures (including
domains and data elements) in the ABAP Dictionary. These data structures are required
for the parameters of the BAPI to be implemented. You can access the ABAP Dictionary
from the project form in the BAPI Explorer.

The conventions below are important:

Conventions for BAPI Data Structures

Each parameter must refer to a data structure in the ABAP Dictionary. In the case of
structured parameters this is always to the whole BAPI data structure. But if the
parameter consists of only one field, it must refer to a field in a BAPI structure.

The structured parameters DestinationFrom and DestinationTo in

the Flight.GetList method refer to the same BAPI structure,
BAPISFLDST. The Airline parameter, which consists of one field
only, refers to the BAPISFLKEY-AIRLINEID field.

You have to create separate data structures for BAPIs that are independent of the
data structures generally used in the SAP application.
Reason : When the BAPI is released the underlying structures of the BAPI are
frozen and restrictions apply if you want to later change the structures. See also
SAP Enhancements to Released BAPIs.

Existing internal structures can be mapped to existing BAPI

structures with a field mapping function module that is automatically
generated by a mapping tool (transaction BDBS).
For more information see Converting Between Internal and
External Data Formats.

All data structure names must begin with <namespace>BAPI.

BAPI structure names should be as meaningful as possible.

You must not use APPENDs and INCLUDEs in BAPI data structures.

Reason : APPENDs and INCLUDEs can cause incompatibilities, if BAPI data

structures are changed.

Always try to use existing central data elements and domains for fields.
 The Example of the BAPI Flight.GetDetail shows how data
structures should be defined.

Conventions for Field Names

The fields in structures must have meaningful English names with a maximum of 30
characters.

SAP internal: Use report BAPIFELD to create a list of English field

name proposals for an ABAP Dictionary structure. Refer to the
report documentation to find out how to use the report.

A meaningful English default field name with a maximum of 30 characters should be

defined for each data element.

SAP internal: In the future the default name is always proposed by

the SAP internal report BAPIFELD.

Procedure : You can take data objects that still need to be edited
from the report BAPIFELD. In the ABAP Dictionary you can define
the default field name of the data element by choosing Definition →
Default field name.

Conventions for Input Help

You may have to define single values or a value table for the domain so that F4
help is available for use.

All the useful input help (which can be used in the service BAPI
Helpvalues.GetList) must be defined for the data structures/data elements. To do
this a foreign key must be specified in the fields of a BAPI structure. If a search help
has been defined in a field domain, a foreign key must also be defined.

To do this, look at the BAPI structure BAPISFLDST, which is based

on the parameters DestinationFrom and DestinationTo in the
Flight.GetList method. The value table SAIRPORT is defined for the
S_AIRPID domain for the AIRPORTID field in this structure. In the
BAPI structure BAPISFLDST, a foreign key dependency is defined
 for this table.

Technical Conventions

The internal data format is used for all parameter fields.

See also Converting Between Internal and External Data Formats.

If an external key as well as an internal key has been defined in the database, the
external key must always be used in the BAPI interface.

For fields relevant for ISO (country, language, unit of measure, currency), additional
fields for ISO codes are provided.

Always try to use the standard domains listed below for fields. We recommend that
you use your own data elements for the fields. If it does not make sense to use your
own data elements, use the standard data elements that are listed below.

Field Standard Standard Data Element

Domains

Country (SAP code) LAND1 LAND1

Country (ISO code) INTCA INTCA

Currency (SAP code) WAERS CURCY or WAERS

Currency (ISO code) ISOCD ISOCD

Language (SAP SPRAS SPRAS

code)

Language (ISO code) LAISO LAISO

Unit of measurement MEINS MSEHI or MEINS

(SAP code)

Unit of measurement ISOCD_UNIT ISOCD_UNIT

(ISO code)

For more information, see Internal and External Data Formats.

All currency fields use the domain BAPICURR. In special cases the domain
BAPICUREXT can also be used.

The currency field PRICE (standard list price of the flight) in the
BAPI structure BAPISBOPRI, which is based on the parameter
TicketPrice in the method FlightBooking.CreateFromData, uses the
BAPICURR domain.
 You must always use a period for the decimal point.

All currency amounts and units of measure must have the decimal point in the
correct place.

Reason : The BAPI always uses a standard amount format with commas. So when
converting currency amounts use the function modules:
BAPI_CURRENCY_CONV_TO_EXTERNAL and
BAPI_CURRENCY_CONV_TO_INTERNAL.

With quantity fields the reference field/reference table must be correctly set to the
unit of measure field.

All the date elements for date fields must have the format YYYYMMDD.

Conventions for BAPI/ALE Integration

So that an IDoc for asynchronous communication can be generated from a BAPI, the
following conditions must be satisfied:

BAPI structure names must not be longer than 27 characters, otherwise the
automatically generated name for the associated segment will be too long and will
have to be changed manually later.

Reason : The segment is generated following the convention <BAPI structure

name> + <three digit number>.

Single fields in a data structure can only be a maximum of 250 bytes.

Conventions for Customer Developments

If IBUs, partners and customers are creating data structures (domains or data
elements), the Namespaces provided by SAP must be complied with.

Make sure that SAP internal namespaces are consistent, too. This
means that if a namespace is used for the whole application, the
BAPIs must use the same namespace.
Actions in the Function Builder
Once the parameters have been defined, the function module underlying the BAPI is
created in the Function Builder (transaction SE37). Transaction SE37 can be accessed
from within the project form in the BAPI Explorer.

When creating the function module you must follow the rules below:

All function modules must have the naming convention:

<Name space>BAPI_<business object>_<method>.

A maximum of 30 characters is allowed.

If required, you can abbreviate the name but still following the above convention.
You must still be able to recognize the business object type assignment.

Method name: FlightBooking.CreateFromData; function module

name: BAPI_FLBOOKING_CREATEFROMDATA

All the BAPIs belonging to one SAP business object type should be created in one
function group. You should only deviate from this rule in exceptional cases.

BAPIs belonging to different SAP business object types must not be put in the same
function group.

The next steps:

Defining the Interface

Implementing the Function Module

Actions in the BOR

After the function module has been created, you have to define the BAPI as a method of
a business object type. By storing the BAPI in the central Business Object Repository
(BOR), you enable object-oriented access to the BAPI and the ALE distribution model
may be able to be connected to (with asynchronous communication).

The BOR can be accessed from within the project form in the BAPI Explorer.
Process Flow
To define the BAPI:

1. Identify the SAP business object type.

2. Append the BAPI as an API method to the business object type.

You can use the BAPI Wizard to do this. This generates the method in the BOR
based on the BAPI function module you created.
You have to perform some additional tasks in this procedure. Keep in mind the
following points:

Upper case/lower case (each new word must be in upper case). See also
Example: BOR and Function Module Parameters.

The import and export behavior of the table parameters must be correctly
defined in the BOR.

Reason : Unlike the function module, in the BOR you can differentiate
between import and export tables. You should therefore only select the
standard option Import/export, if the table is actually going to be imported and
exported.

The return parameter is always defined as an export parameter.

As well as making the task much easier, the Wizard also ensures that the BAPI
interface is identical in the BOR and in the function module. In particular this
concerns the following points:

• For each function module parameter there is one BOR parameter (or one
key field) of the same name (or vice versa).

• The associated parameters are based on the same ABAP Dictionary

structure.

• The associated parameters have the same characteristics (mandatory or

optional, import, export or table parameters).

The following example shows the relationship between the definition

of the BAPI method in the BOR and the function module.

If you cannot use the BAPI Wizard (e.g. to change the BAPI later or to
redefine a method), you can change the method in the BOR itself. Make
sure that the above points are complied with.
For developments undertaken by IBUs, customers and partners the additional points
below are important:

Read the documentation about Customer Enhancements and Modifications to

BAPIs.

As a customer you can create your own BAPIs for your own business object types
or you can define a subtype of an existing SAP business object type. We strongly
advise you NOT to define new BAPIs of SAP business object types because this
involves modifications.

All development objects (business object types, BAPIs, parameters) have to be

created in their own namespace.

Make sure that SAP internal namespaces are consistent, too. This
means that if a namespace is used for the whole application, the
BAPIs must use the same namespace. However, there are
constraints when you create a technical name for a business object
since it may contain a maximum of 10 characters only.

Documenting the BAPI

Principles
The quality of your BAPI documentation depends on the following principle:

The documentation must be in sufficient detail so that an external developer familiar with
the business background but not with the SAP System, can use the BAPI.

Features
The documentation for the BAPI covers four areas:

1. The SAP business object type documentation.

2. The method documentation should answer the following questions:

What is the business function of the BAPI and what is it used for?

What do the BAPI functions actually do?

Are there any important limitations, that is, are there functions that this BAPI
cannot perform?
 What must you pay particular attention to with this BAPI? (e.g. authorization
checks)
What other prerequisites apply to the BAPI?

Are there any Customizing dependencies?

What dependencies are there between this BAPI and other BAPIs, and
between individual method parameters?

Is it a BAPI with buffering?

If it is, the BAPI must be explicitly identified as such.

Does the BAPI contain a COMMIT WORK command?

If it does, it must be documented.

3. The BAPI parameter documentation answers the following questions:

What is the parameter used for?

Which fields of a parameter must be filled, that is, what are the mandatory
fields?

What are the dependencies between fields?

Are there parameter dependencies and field dependencies within a structure?

Are there any fixed values and what do they do?

What are the default values of the parameter?

All the fields that are assigned default values by Customizing and are
therefore write-protected, must be documented.

Does the documentation of the return parameter comply with the guidelines
and does it contain all the relevant error messages?

If there is a termination, is a database rollback executed as an exception

within the BAPI?

If it is, you must describe this process in the documentation for the return
parameter.

Are all the available BAPI table extensions listed in the documentation on the
extension parameters (ExtensionIn, ExtensionOut)?

4. Data element documentation underlying the fields in the BAPI parameters

Finally, you must also make sure that the documentation about the
function modules and parameters has been saved by the documentation
developer as an active version so that it appears in the translator's
worklist.
 Refer to Examples of BAPI Documentation. See also the
documentation about the demo business object types Flight,
FlightBooking, and FlightCustomer, and the corresponding BAPI
methods.

BAPI/ALE Integration
BAPIs are integrated into the ALE communication model. ALE communication is
asynchronous and message-based. ALE communication is the preferred way to integrate
distributed SAP Systems, for example, for distributing master data.

Since Release 4.0 BAPIs are the standardized interfaces for ALE-supported
communication. ALE services, such as asynchronous BAPI calls, distribution model,
monitoring and error handling can be used for BAPIs. The IDoc types required for the
ALE services can be generated from BAPIs.

See also: Using the ALE Services

When you use BAPIs for asynchronous messaging, the application in the sending system
calls the generated ALE IDoc interface instead of the BAPI. The ALE IDoc interface
performs the following tasks:

• Creates an IDoc from the BAPI data

• Sends the IDoc to the target system
• Receives the IDoc in the target system, creates the BAPI data from the IDoc and
calls the BAPI

You can use Transaction BDBG to create the other objects required for the asynchronous
communication (message type, IDoc type, inbound and outbound function module).

See also: Maintaining the BAPI ALE Interface.

A BAPI should only be implemented as an asynchronous interface, if at least of the

following conditions is satisfied:

• Database changes are consistent in all systems

Data must be updated consistently on a remote system as well as on the local
system.
• Looser coupling
With a synchronous interface the coupling between the client and the server
system is too narrow. If the connection is interrupted the client system would not
be able to function properly.
• Performance
The interface has a large volume of data or database operations to be carried on
the server system will take a long time. In this situation a synchronous interface
cannot be used because performance would be too low.
BAPI/ALE integration requires that:

Message types are created and IDoc types are generated for all write BAPIs.
See also: Maintaining BAPI ALE Interfaces.

All IDoc types and the associated segments are released.

The BAPI interface and the IDoc interface are identical. Make sure that the
message type, IDoc type and segments are regenerated, particularly if the BAPI is
changed.

All BAPI export parameters with the exception of the return parameter
are ignored and are not included in the IDoc type that is generated.

SAP internal: If the BAPI serves integration purposes between the

various SAP products, then the interface information must be made
available to the relevant systems. To do this, the data structures that the
BAPI uses (including the data elements and domains), and the ALE
interface have to move to the application basis.

If the applications have restricted usability, you have to explicitly release

the BAPI function module for cross-application use.

To do this, contact a member of the integration team.

Testing and Releasing

To check that the BAPIs, business object types and documentation are all correct,
special tests and ToDo checks must be carried out. Once the test phase has been
successfully completed, the business object type, BOR methods and function modules
can be released.

For more information see:

Testing

Releasing

Testing
After you have implemented the underlying function module of your BAPI, and you have
defined the BAPI as a method of an SAP business object type in the Business Object
Repository (BOR), you should test the BAPI.

Carry out the test together with the persons responsible for quality
control in your development group.

Test Phase
The following steps are carried out in the test phase:

Testing the Documentation

Check that the documentation for each business object type, each BAPI and for
each interface parameter is available and that you understand it. As the BAPI
documentation is critical for being able to use the BAPI, this test should be carried
out thoroughly.

Testing the BAPI Syntax

In the test phase you must check that the BAPI meets all the conventions described
above, and that you have followed the guidelines for developing BAPIs. You can
check that the syntax is correct using the BAPI Explorer and the BAPI ToDo. An
implicit check is also carried out when the BAPI is appended in the BAPI/BOR
Wizard and when it is released in the BOR.

To test the BAPI syntax in the BAPI Explorer, position the cursor on
the relevant BAPI in the left-hand frame. Select the tab page Tools
in the right-hand frame and then the option BAPI Consistency
Checks.

Testing the BAPI Semantics

After you have checked that the syntax is correct, you have to check that the
semantics of the BAPI are correct (testing the functions and integrity). You have the
following options:

Testing the underlying function module in the Function Builder

You can test the parameters in your function module in one test. Enter the
appropriate test values in the parameters to verify that the source code in the
function module can run without errors.

However, the test in the Function Builder has the following drawbacks:

• The tests do not update the database because a COMMIT WORK cannot
be executed.
 • The tests cannot be automated.
• The test data is not transported into other systems and is lost if the function
module is changed. So, for example, no regression tests can be carried out.

Testing the function module with the Computer Aided Testing Tool (CATT)

Function modules can be tested within the SAP standard test tool using the CATT
test module type F. The CATT has the following advantages over testing in the
Function Builder:

• The tests do change the database because a COMMIT WORK is

automatically executed.
• The tests can be automated.
• The test data is transported with the test module and is therefore available
in other systems and releases for regression tests.

Tests with the CATT should be carried out in preference to tests in

the Function Builder because the test runs are retained and can be
optimally integrated into the SAP quality assurance process.

For more information on using CATT for testing function modules,

see CATT: Using Function Module Tests.

Testing the BAPI call in an external application

To use a BAPI in an external application, the following conditions must be fulfilled:

• The syntax of the BAPI is correct.

This should be tested by the BAPI developer using the BAPI Explorer.

• The communication functions without errors.

This should be checked using appropriate tests from the Middleware
departments.

Testing the BAPI on different platforms

The platform tests are carried out during the final assembly. The tests can only be
carried out when the BAPI semantics have been tested with CATT, and when the
CATT procedures created in the tests can be used again in the final assembly.

If you find any errors in the BAPI implementation, correct them and
repeat the tests until you and the quality control team in your group are
fully satisfied with the BAPI implementation and with the documentation.
Releasing
Once all the tests have been completed, the BAPIs and all their associated development
objects can be released for customers to use. They can only be released if the following
conditions are fulfilled:

The documentation has been fully completed.

There are no consistency errors.

For more information about releasing BAPIs see Further Issues.

Procedure
You have to carry out the following steps:

Releasing the BAPI Function Module in the Function Builder.

Release the Business Object Type in the BOR.

Release the BAPI as a method in the BOR.

With write BAPIs release the IDoc and its segments.