Professional Documents
Culture Documents
Content
Business Application Programming Interface (BAPI) 3
Business Object Repository (BOR) 4
Transaction Model for Developing BAPIs 5
Defining and Implementing the BAPI 8
Frequently Used BAPIs 9
Defining a BAPI Scenario 11
Defining a BAPI and Its Interface 13
Determining the SAP Business Object and Its Key Fields 14
Defining the Interface Structure of the BAPI 15
Naming Parameters in the Function Module 16
Specifying the Required Objects in ABAP Dictionary 17
Naming the Method in the BOR 18
Naming Parameters in the BOR 18
Creating Individual Programming Objects 20
Conversion Between Internal and External Data Formats 21
Converting Between Internal and External Data Formats 22
Application Example 23
Defining Methods in the BOR Using the BOR/BAPI Wizard 25
Example of a Function Module 27
Testing the BAPI 28
Releasing and Freezing the BAPI 29
Programming BAPIs 30
Programming Change BAPIs 31
Programming Replicate/Clone BAPIs 34
Programming Value Ranges 36
Internal and External Data Formats 37
Reporting Errors 39
Providing Input Help (F4 Help) 42
Improving the Performance of your BAPI 44
Enhancements to Existing BAPIs 45
Customer Modifications of BAPIs 48
Implementing BAPIs in ALE Scenarios 50
BAPI Implementation Checklist 52
_________
2 __________________________________________________________________
A Tutorial on 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).
_________ __________________________________________________________________
3
A Tutorial on Business Application Programming Interface_____________________________
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 Tutorial on Business Application Programming Interface_____________________________
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.
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
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
_________ __________________________________________________________________
5
A Tutorial on Business Application Programming Interface_____________________________
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 Tutorial on Business Application Programming Interface_____________________________
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
_________ __________________________________________________________________
7
A Tutorial on Business Application Programming Interface_____________________________
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 Tutorial on Business Application Programming Interface_____________________________
Definition
Some BAPIs and methods provide basic functions and can be used for most SAP Business
Objects. These BAPIs are:
_________ __________________________________________________________________
9
A Tutorial on Business Application Programming Interface_____________________________
_________
10 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
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
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
_________ __________________________________________________________________
11
A Tutorial on Business Application Programming Interface_____________________________
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 Tutorial on Business Application Programming Interface_____________________________
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
_________ __________________________________________________________________
13
A Tutorial on Business Application Programming Interface_____________________________
1
23
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
_________
14 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
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
_________ __________________________________________________________________
15
A Tutorial on Business Application Programming Interface_____________________________
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:
_________
16 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Purpose
After you have specified the contents and names of the required interface parameters you can
identify and define the required data objects in the ABAP Dictionary.
Note the following:
• You can use individual fields, structures and tables as parameters. Every parameter must
refer to a Dictionary object.
• You have to create your own data structures for the BAPI interface that are independent
of the data structures generally used in the R/3 application. This enables changes to be
made in R/3 applications without affecting BAPIs.
Give meaningful names to the data structures you create. Names should begin with the
prefix BAPI.
• Chose meaningful names in English for the structure fields. Up until Release 4.0 ten
characters were available for naming structures; from Release 4.0 you can use up to 30
characters. You can use alphanumeric characters and underscores.
You can use existing data elements and domains for the fields in the BAPI structures. As
of Release 4.0 it is possible to assign English names to the data elements in the ABAP
Dictionary. Whenever possible use these names for the field and parameter names.
Example
In the example in the previous steps the reference fields/tables shown below were
identified for the parameters.
The first example here uses structures created in Release 3.1. In this Release
structure names had a maximum of 10 characters.
The second example shows how you could name the structures more meaningfully
in Release 4.0.
CREDITORID BAPI1008-VENDOR_NO
COMPANYCODE BAPI1008-COMP_CODE
CREDITORGENERALDATA BAPI1008_4
CREDITORCOMPANYDATA BAPI1008_5
RETURN BAPIRETURN2
CREDITORBANKDATA BAPI1008_6
CREDITORID BAPI1008-VENDOR_NO
COMPANYCODE BAPI1008-COMP_CODE
CREDITORGENERALDATA BAPI1008_CREDITORGENERALDATA
CREDITORCOMPANYDATA BAPI1008_CREDITORCOMPANYDATA
RETURN BAPIRETURN2
CREDITORBANKDATA BAPI1008_CREDITORBANKDATA
_________ __________________________________________________________________
17
A Tutorial on Business Application Programming Interface_____________________________
Purpose
You can now plan the name of the BAPI method in the Business Object Repository (BOR).
Prerequisites
The individual components of BAPI names are identified by the use of upper and lower case
letters, for example, ChangePassword.
BAPI names must be meaningful and be in English, and can only have a maximum of 30
characters. For example:
• ExistenceCheck
• ChangePassword
• GetDetail
If you are implementing one of the frequently used BAPIs use the appropriate generic name.
To get an idea about naming BAPIs take a look at existing BAPIs of an SAP Business Object
in the BOR. Select an SAP Business Object in the application hierarchy in the Business
Object Browser and expand the node Methods.
BAPIs are identified by the API indicator (green circle) to the right of the method name.
Purpose
The parameter names of the methods in the Business Object Repository (BOR) are based on
the parameter names in the function module. You have already named the parameters of the
function module in Naming Parameters in the Function Module.
Caution
From Release 4.0 the names of the BAPI parameters in the BOR and the names of the
parameters in the corresponding function module must be identical. This was not
necessarily the case in earlier releases.
When naming parameters of a BAPI in the BOR take account of the following:
• The parameters must be in English.
• Unlike parameter names in the function module that must be written completely in upper
case, the components of parameter names in the BOR are separated by upper and lower
case letters. Every new word in the parameter name begins with a capital letter, for
example, ChangePassword.
• A parameter name in the BOR cannot have more than 20 characters.
To get an idea about naming BAPI parameters, take a look at the parameters of existing
BAPIs in the BOR. Select an object type in the application hierarchy in the Business Object
Browser. Expand the node for the object's methods, then select a BAPI, then finally select
Parameter.
_________
18 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Example
In the example in the previous steps six parameters for a BAPI were identified and
names given to these parameters in the function module.
The table below shows what the parameter names could look like in the function
module and in the BOR.
Parameters and their Names in the Function Module and in the BOR
_________ __________________________________________________________________
19
A Tutorial on Business Application Programming Interface_____________________________
Purpose
After you have identified the individual programming objects and given them names you
should create them in the R/3 System as required.
Process Flow
To create the required programming objects in R/3 the following steps are required:
• Creating the Dictionary objects, for example, structures, fields and domains, in the ABAP
Dictionary.
• Creating the function group in the Function Builder (if required).
• Creating the function module in the Function Builder.
• Writing documentation for the BAPI.
BAPI documentation is essential because it is very difficult to use a BAPI that has not
been well documented.
The BAPI documentation must be written in the Function Builder for the function module
that the BAPI is based on.
Make sure that the documentation is translated into the required languages.
• Using the program to map the internal data format onto the external data format, as
described in Conversion Between Internal and External Data Formats.
• Writing the program for the function module. Refer to Example of a Function Module.
Also, see Programming BAPIs for more information.
• Defining the function module as a method of the corresponding SAP Business Object in
the BOR, as described in Defining Methods in the BOR Using the BOR/BAPI Wizard.
You should then verify that the parameters and parameter types of the method in the BOR
match the parameters of the underlying function module in the Function Builder.
_________
20 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Use
According to the guidelines BAPI interfaces should only have English field names. However,
in the internal working structures of a BAPI German field names are often used.
Moreover in one of the previous steps you created your own structures for your BAPI which
are different from the structures used in R/3 applications. This is necessary to be able to
freeze the BAPI structure and to maintain a stable BAPI interface, yet at the same time, to
enable further development in the R/3 application. For more information refer to Internal and
External Data Formats.
As a result of these discrepancies the fields of the internal working structure of the BAPI must
be mapped onto the fields of the BAPI interface before the BAPI is called. You can generate
function modules which help to automatically convert and map the data.
You can use the generated function modules in the source code of your BAPI for:
• Mapping the internal working structures of the BAPI onto the external BAPI structures
before the BAPI is called
• Mapping the result onto the internal structures after the BAPI call
• When implementing the BAPI, mapping the inbound parameters onto the internal
structure (structuring import parameters)
• When implementing the BAPI, mapping the result from the internal structure onto the
BAPI (structuring export parameters)
Features
The function modules generated have the following functions:
• They map between German and English field names
• They convert ISO codes
• They convert currency amounts into the required internal or external format
• They convert internal and external keys such as those used by the PSP Element (Project
structure plan)
Any problems that could arise during data conversions are reported back using the RETURN
parameter.
Limitations
Occasionally you may have to manually edit the source code of a function module after it has
been automatically generated.
Existing function modules can not yet be regenerated with this transaction. To regenerate an
existing function module you have to manually delete the function module and then generate it
anew.
Activities
To generate the required function modules see Converting between Internal and External
Data Formats. The Application Example illustrates the use of these function modules.
_________ __________________________________________________________________
21
A Tutorial on Business Application Programming Interface_____________________________
1
23
Converting Between Internal and External Data
Formats
Prerequisites
Before you can generate the function modules to map between the internal working structures
and the external BAPI structures, you must make sure that the internal and external structures
exist.
Result
The function module is stored in the Function Builder in the function group you specified. You
can incorporate it into the source code of your BAPI as required.
_________
22 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Application Example
The BAPI used in this fictitious example can read the standard price of a material:
bapi_material_get_price
importing
material like mara-matnr
exporting
material_price like bapi_material_price.
_________ __________________________________________________________________
23
A Tutorial on Business Application Programming Interface_____________________________
* Call BAPI
call function bapi_material_get_price
exporting
material = matnr
changing
material_price = bapi_preis.
* Map and convert the result to internal format
call function map2i_bapi_material_price_to_mat_preis
exporting
external = bapi_preis
changing
internal = preis.
* exceptions
* error_during_iso_convertion
* error_during_currency_amount_conversion
preis-matnr = matnr.
_________
24 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
1
23
Defining Methods in the BOR Using the
BOR/BAPI Wizard
Prerequisites
If the function module which your BAPI is based on has been fully implemented you can
define it as a method of an SAP Business Object in the Business Object Repository (BOR).
You use the BOR/BAPI-Wizard to do this.
_________ __________________________________________________________________
25
A Tutorial on Business Application Programming Interface_____________________________
Also specify whether the individual table parameters are used for data import or
data export. Table parameters are marked with a tick in the column 'MLine' (multiple
lines).
5. Select Next Step.
To create the method select Yes in the next dialog box.
Result
After the program has been generated and executed, check that all the definitions have been
made correctly by the BOR/BAPI Wizard. To do this look at the method in the BOR.
_________
26 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Source Code:
function bapi_companycode_getdetail.
*"------------------------------------------------------
*"*"Local interface:
*" IMPORTING
*" VALUE(COMPANYCODEID) LIKE BAPI0002_2-COMP_CODE
*" EXPORTING
*" VALUE(COMPANYCODE_DETAIL) LIKE BAPI0002_2
*" STRUCTURE BAPI0002_2
*" VALUE(COMPANYCODE_ADDRESS) LIKE BAPI0002_3
*" STRUCTURE BAPI0002_3
*" VALUE(RETURN) LIKE BAPIRETURN
*" STRUCTURE BAPIRETURN
*"------------------------------------------------------
...
* authority check: S_TABU_DIS V_T001
perform check_authority_t001 changing return.
check return is initial.
* company code
call function 'FI_COMPANY_CODE_DATA'
exporting
i_bukrs = companycodeid
importing
e_t001 = t001
exceptions
error_message = 1
others = 0.
if sy-subrc ne 0.
perform set_return using '10' changing return.
endif.
check return-code is initial.
...
endfunction.
_________ __________________________________________________________________
27
A Tutorial on Business Application Programming Interface_____________________________
Purpose
After you have implemented the function module your BAPI is based on and you have defined
the BAPI as an SAP Business Object method in the Business Object Repository (BOR) you
should check that the BAPI functions properly.
Prerequisites
Carry out the test together with persons responsible for quality control in your development
group.
Before you start testing make sure that the underlying function module has been completely
implemented and that the BAPI has been correctly defined in the BOR as a Business Object
method.
Process Flow
You can test the BAPI in the following ways:
• By calling the underlying function module
You can individually test the function module in the Function Builder. You can enter the
appropriate test values in the parameters of your function module and by running the test
you can verify that the source code in the function module is processed without errors.
• Testing the BAPI in the BOR
You can test the BAPI by testing the individual method of the Business Object in the
Business Object Builder. You need to know the technical name of the Business Object
(object type) that you have already specified in Defining a BAPI and Its Interface.
Call the Business Object Builder by selecting Tools → Business Framework → BAPI
Development → Business Object Builder. Specify the appropriate object type and then
start running the test by selecting Test. To test the BAPI implementation, you need to
specify appropriate test values in the parameters of the BAPI.
Note that for an instance-dependent BAPI you have to first specify an instance before you
can run the BAPI test. Select Create instance and specify the required instance.
• By calling the BAPI in a Visual Basic program
If possible write a program in Visual Basic to call the BAPI.
- Check that the BAPI can be called by BAPI ActiveX Control.
- Check that the BAPI can be called by making RFC calls to the underlying function
module.
• Check the availability of documentation in the different logon languages.
Result
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.
_________
28 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
1
23
Releasing and Freezing the BAPI
After you have completed the function module and BAPI tests and you are satisfied that they
function properly, the implementation is complete.
You can now release the function module the BAPI is based on and the method in the
Business Object Repository (BOR), and freeze the BAPI as a method in the BOR.
Once the BAPI has been released and frozen, it becomes available as a fully implemented
Business Object method.
Releasing and freezing also prevents anyone making incompatible changes to the BAPI,
because all changes made to a released and frozen BAPI are automatically checked for
compatibility in the BOR and the ABAP Dictionary, and incompatible changes are rejected.
For more information about what to look out for when making changes to existing BAPIs see
Enhancements to Existing BAPIs.
Releasing and freezing the BAPI should be done in cooperation with the persons responsible
for the development objects involved and those responsible for quality control.
To release and freeze a BAPI follow the steps below:
• First release the function module in the Function Builder. Select
Function module → Release → Release.
• Set the status of the method to 'released' in the Business Object Builder. Select the
relevant SAP Business Object in the Business Object Builder and expand the node
Methods. Place the cursor on your BAPI and select Edit → Change status → Released.
• Freeze the method. Place the cursor again on your BAPI in the Business Object Builder
and select Utilities → API methods → Freeze method.
Check the new status of the function module in the Function Builder and the method in the
BOR.
_________ __________________________________________________________________
29
A Tutorial on Business Application Programming Interface_____________________________
Programming BAPIs
Use
This section describes how to program the BAPI you defined in the previous sections.
It is not easy to formalize the functional scope of a BAPI. Every BAPI has a different functional
content, even those that perform similar functions, such as the frequently used BAPIs. The
differences are mainly due to the different characteristics and contents of SAP Business
Objects.
Prerequisites
To ensure that BAPIs, as interfaces of SAP Business Objects, provide access to R/3 data and
processes in a consistent way, you must follow certain rules when programming BAPIs. These
are:
Mandatory Rules
• A BAPI must not contain any dialogs; in other words, the BAPI must not return any R/3
screen dialogs to the calling application. This is true for the BAPI itself and for any
function module that may be indirectly called by the BAPI.
• BAPIs must not produce any screen output, for example, display a list on the screen.
• Database changes can only be made through updates.
• Set and Get parameters and the global memory must not be used to transfer values.
• If required every BAPI must be able to carry out its own authorization checks.
Recommendations
• Minimize interface complexity. Use the object/method model when choosing parameters
and combining them in structures. In other words, select the most important parameters
and combine them in structures in a meaningful way.
• Application servers might not support ASCII, but use a different character set instead. If
this is the case a problem may arise when you select quantities or ranges or when these
are sorted. Because of this a BAPI should always select a range between A-Z, a-z and 0-9.
Other Features
Also pay attention to the following when you program BAPIs:
• Programming Change BAPIs
• Programming Replicate/Clone BAPIs
• Programming Value Ranges
• Internal and External Data Formats
• Reporting Errors
• Providing Input Help (F4 Help)
• Improving the Performance of your BAPI
_________
30 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Use
The BAPI Change modifies an existing instance of a SAP Business Object, for example, one
specific purchase order.
As the Change BAPI can carry out changes to existing data, a Change BAPI must be able to
identify fields that have been modified and fields that have stayed the same.
Using an initial value is no solution because an initial value could also represent a valid new
value. Moreover, in the ABAP programming language or on other development platforms you
cannot assign the value "null" to all data types in order to mark fields and thus indicate that the
remaining fields contain update values.
Features
Two different approaches can be used to identify fields containing values that have been
modified in a Change BAPI:
• Flagging fields to identify those fields containing modified values
• Comparing fields to identify those fields containing modified values
In this approach parameter fields containing modified values are identified by a suitable
flag in an additional "change parameter".
• An additional change parameter must be created with the same number of fields and
the same field names for every parameter in the BAPI containing modified field
values.
• When the BAPI is called, the fields in the additional change parameter whose
counterparts in the corresponding parameter contain modifications, must be marked
with an update flag.
That way the BAPI can identify both modified and unmodified fields in the parameter.
Follow the conventions below when you create change parameters to identify modified
fields:
• The name of the additional change parameter consists of the parameter name with
the suffix "X". For instance, if the parameter is called EquiSales, the name of the
additional change parameter is EquiSalesX.
• The additional change parameter must contain exactly the same number of fields and
the same field names as the parameter. You must use the data element
BAPIUPDATE as the data element for the update fields. This can have the following
values:
- 'X'
This value means that the corresponding parameter field contains a modified
value.
- ' ' (no value)
This means that the corresponding parameter field does not have to be updated.
• If the parameter is a table, the additional change parameter must also be a table.
_________ __________________________________________________________________
31
A Tutorial on Business Application Programming Interface_____________________________
Example
A Change BAPI is used to change the value of the existing distribution channel
(Distr_Chan) to Distr_Chan="US". The program objects in the R/3 System affected by
this change are:
Parameter EquiSales
Fields in parameter EquiSales SalesOrg='abcd'
Distr_Chan='US'
Division='efgh'
In the parameter EquiSalesX the value in the field Distr_Chan is 'X'. This indicates
that the field Distr_Chan of the parameter EquiSales contains a modified value.
The BAPI Change then overwrites the existing value in the field Distr_Chan with the
current value in the field Distr_Chan in the parameter EquiSales.
In this approach parameter fields containing modified values are identified by comparing
them with the fields in an additional "compare parameter":
• An additional compare parameter must be created with the same structure for each
BAPI parameter containing update values.
• When the Change BAPI is called all relevant fields in the compare parameter must be
filled with the data at the time the database is read. This data could be, for example,
the result of a previous GetDetail BAPI call.
The fields of the corresponding parameter may contain modified values.
• The data in the compare parameter can first be checked against the current database
contents to ascertain whether it has changed in the meantime. This way any database
changes made between the time the data was read and the time the database is
updated can be identified.
• Then, the data in the compare parameter can be compared field by field with the data
in the corresponding parameter. If data in any field is different then the field contains
data that must be changed.
• The name of the additional compare parameter consists of the parameter name with
the suffix "X". For instance, if the parameter is called EquiSales, the name of the
additional compare parameter is EquiSalesX.
• The additional compare parameter must contain exactly the same fields and the same
structure as the parameter.
_________
32 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Area Advantage
Performance Approach 1: Flag table can be compressed. Compare data does
not have to be read.
Check facilities Approach 2: Can carry out check against current database to
identify and prevent inconsistencies.
_________ __________________________________________________________________
33
A Tutorial on Business Application Programming Interface_____________________________
Use
To replicate a business object you can implement Replicate/Clone BAPIs. The interface of
these BAPIs depends on the characteristics and contents of the business object that is to be
cloned. For this reason these BAPIs must be implemented for each business object.
The objective of replication is to make specific instances of a business object available on one
or more additional systems. The cloned business objects are created under the same object
key.
Business objects can be cloned in two ways:
• By request ("Pull")
System "A" requests clones from system "B". Then system "B" replicates the requested
business objects on system "A".
• Using subscription lists ("Push")
System "B" maintains a list of systems requiring clones. At regular intervals system "B"
replicates the business objects on all the systems in the list.
Features
Both of the above cloning methods can be implemented with the following BAPIs:
• Replicate
A client system uses the Replicate BAPI to request clones of business objects from a
server system. This method must be implemented for each business object to be cloned.
The BAPI's import parameters have to identify the business objects to be cloned. You can
do this by using a range table for the key fields of the business object. You can also add
other import parameters, for example, to request all the materials belonging to a material
group or to delimit the amount of data in the business object to be cloned (for example,
material with or without plant data).
Each Replicate BAPI must contain the parameter CloneReceivers which specifies the
systems on which the business objects are to be replicated.
Only create the Parameter RETURN as an export parameter.
The BAPI Replicate requests the replication of a business object. The actual replication is
carried out when the server system invokes one of the Clone BAPIs described below on
the client system. You can specify whether the replication is carried out immediately or at
a later time and in a separate step, depending on what is most practical for the business
object.
Moreover, at least one of the BAPIs below must be implemented for each business object to
be cloned. You should decide to implement one of these BAPIs, depending on the specific
requirements of your BAPI:
• 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.
All the data required for cloning an individual business object must be provided in the
import parameters. Each Clone BAPI must contain the import parameter Sender which
identifies the system that sends or owns the business object. If only parts of an object are
to be cloned rather than the whole object, you can use other optional import parameters.
Only create the Parameter RETURN as an export parameter.
_________
34 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
This BAPI should be used for more complex objects that will not be cloned in large
numbers.
• 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 clone or modify several instances of
an object at the same time.
All the relevant data for cloning several business objects must be provided in the import
parameters. Each CloneMultiple BAPI must contain the import parameter Sender which
identifies the system that sends or owns the business objects. If only parts of objects are
to be cloned rather than whole objects, you can use other optional import parameters.
Only create the Parameter RETURN as an export parameter.
This BAPI should be used for objects with small amounts of data. Although the BAPI
CloneMultiple is more efficient than the BAPI Clone, it does require a far more complex
interface and error handling process.
_________ __________________________________________________________________
35
A Tutorial on Business Application Programming Interface_____________________________
Use
The parameters in BAPIs that can be used to search for specific instances of a business
object, for example, BAPI CustomerCode.GetList, have to enable BAPI users to specify
appropriate selection criteria.
Prerequisites
To enable the use of selection criteria you have to create the relevant selection parameters of
the BAPI as a structure or table with the following fields:
You can use the function module BALW_RANGES_CHECK to check the values entered in
SIGN and OPTION.
_________
36 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Use
BAPIs are programming interfaces used in the most diverse application areas, for instance, to
connect non-SAP systems or PC products to the R/3 System.
To meet the requirements of this diverse range of applications, a shared strategy for
representing data in the BAPI interface must be used. In particular, the use of values that
affect Customizing or are language dependent must be avoided.
BAPIs are programming interfaces, not application interfaces. Fields such as a date field,
should not be used in the BAPI interface in any other format than the format used in the
database, i.e. YYYYMMDD, where YYYY is the year, MM the month and DD the day.
Exceptions
Because of the reasons above, BAPIs should only carry out data conversions between the
data format used in the database and external formats used by the calling program in
exceptional circumstances.
These exceptions are listed below. To convert data formats in these exceptional
circumstances, you can use the transaction described in Converting Between Internal and
External Data Formats.
These exceptions are:
• Currency amount fields
In an R/3 System a currency amount field is only useful when a currency code
accompanies it, so that the decimal point in the amounts can be set correctly. Accordingly,
a field for the currency code must be assigned to each currency amount field. For
example, if two Yen are stored in the field of data type CURR as 0.02, a non-SAP system
cannot reasonably be expected to understand these semantics.
All R/3 currency data types have two digits after the decimal point, even though
currencies do exist with three digits after the decimal point.
For these reasons, the data type CURR cannot be used in the BAPI interface. Adhere to
the following guidelines when using currency amount fields in BAPIs:
- You must not use parameters and fields of data type CURR in the interface
- All parameters and fields for currency amounts must use the domain BAPICURR
- The position of the decimal point in currency amount fields must be converted
correctly
You can use two function modules for this conversion. The function module
BAPI_CURRENCY_CONV_TO_EXTERNAL converts currency amounts from R/3
internal data formats into external data formats. The function module
BAPI_CURRENCY_CONV_TO_INTERNAL converts currency amounts from external
data formats into internal data formats.
• Quantity fields
Like currency amount fields, the decimal point in quantity fields must be converted
correctly. A unit of measure field must be assigned to every quantity field. Quantity fields
have no general domain that can be used for BAPI structures.
• Internal keys
In some situations an internal technical key is maintained in the database alongside the
external key. Examples are work breakdown structure plans or networks in project
systems.
_________ __________________________________________________________________
37
A Tutorial on Business Application Programming Interface_____________________________
You must always use the external key in the BAPI interface.
• ISO codes
In R/3 Systems ISO codes are currently supported for language, country, currency, and
unit of measure fields.
If you use one or more of these fields in your BAPI you have to make two fields available
for each of these fields in the BAPI interface: one field containing the SAP code and
another containing its corresponding ISO code. Use the naming convention,
Fieldname_for_SAPCode_ISO for the field containing the ISO code.
For example, the field LANGU contains the country codes used internally in R/3, for
instance E. The corresponding field for the ISO code would then be named LANGU_ISO
and would contain the corresponding ISO code EN.
Implement the BAPI as follows:
- When you export data from the BAPI both fields must contain corresponding values.
- When you import data into the BAPI the ISO code is only significant if no value was
given in the SAP code.
BAPIs for Converting Between Internal and External Data Formats (Converting
Domains)
BAPIs are programming interfaces in which, with a few exceptions, only the internal data
format should be used. However, application programmers calling a BAPI from within their
program may sometimes require the external format, for example, to display data on the
screen. In such cases the calling program must be able to convert between the internal and
external data formats.
The following conversion BAPIs exist for this purpose. The calling program uses them to
obtain the required data formats:
• BapiService.DataConversionInt2Ext
This BAPI converts the internal data format into the required external data format.
• BapiService.DataConversionExt2Int
This BAPI converts the external data format into the required internal data format.
Conversion routines are maintained in the ABAP Dictionary for the domains on which the data
to be converted are based. If this is not the case, no conversion takes place and the values
are returned unconverted.
_________
38 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Reporting Errors
Use
A BAPI should be able to record and classify all possible errors that may occur. You have to
create a parameter named RETURN for every BAPI. This parameter returns exception
messages or success messages to the calling program.
All error messages or indeed any message that may be returned by the BAPI must be defined
in table T100. A general error message has to be sent for those error situations that cannot
sufficiently be identified and distinguished. This message can then be processed by the calling
program in a different program branch.
The parameter RETURN can either be implemented as an export parameter and thus as a
structure, or as a table parameter. Before filling the RETURN parameter you should either
initialize the structure with CLEAR or the table with REFRESH and CLEAR.
If the RETURN parameter is not set or is set to an initial value this means that an error has
occurred.
Caution
From Release 4.0 you must not use Exceptions in a BAPI interface.
Features
The structure of the parameter RETURN is dependent on the R/3 Release the BAPI is
developed for.
Structure of BAPIRETURN
CODE CHAR 5 The first two characters are used for the message
class and the remaining ones for the message
number (key fields from table T100).
MESSAGE CHAR 220 Full message text from table T100. All variables
have been replaced with text.
LOG_NO CHAR 20 Number of application log. This is empty if no log
used.
LOG_MSG_NO NUMC 6 Current number of message in application log.
From Release 4.0 the return parameter must be based on one of the two reference structures
described below.
_________ __________________________________________________________________
39
A Tutorial on Business Application Programming Interface_____________________________
Both structures take into account the name space extension of the message ID made in
Release 4.0. However, if you want messages to be compatible with earlier R/3 Releases, use
only the first two characters of the message ID.
Both structures must be filled in the logon language.
The two structures are:
• BAPIRETURN1
This structure is filled via the function module BALW_BAPIRETURN_GET1. It contains
the following fields:
Field Type Description
TYPE CHAR 1 S = success message
E = error message
W = warning message
I = information message
A = termination message (abort)
ID CHAR 20 Message ID
NUMBER NUMC 3 Message number
MESSAGE CHAR 220 Full message text from table T100. All variables
have been replaced with text
LOG_NO CHAR 20 Number of application log. This is empty if no log
is used
• BAPIRET2
This reference structure contains the additional fields PARAMETER, ROW and FIELD in
which error messages can be assigned to a specific field.
If a BAPI ascertains that an invalid value has been entered in a field, it can identify the
field containing this value in the returned error message using the additional fields in the
structure BAPIRET2.
Only use this structure if you need the functionality of the additional fields to minimize the
complexity of the parameter.
The structure BAPIRET2 is filled via the function module BALW_BAPIRETURN_GET2. It
contains the following fields:
Field Type Description
TYPE CHAR 1 S = success message
E = error message
W = warning message
I = information message
A = termination message (abort)
ID CHAR 20 Message ID
NUMBER NUMC 3 Message number
MESSAGE CHAR 220 Full message text from table T100. All variables
have been replaced with text
LOG_NO CHAR 20 Number of application log. This is empty if no
log is used
_________
40 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
_________ __________________________________________________________________
41
A Tutorial on Business Application Programming Interface_____________________________
Features
In order to enable the HelpValues.GetList method to obtain the valid input values for a field in
your BAPI and return them to the calling program, you must create or specify the appropriate
check table, matchcodes or domain fixed values for that field in the field's reference structure.
For information about check tables, matchcodes and domain fixed values see the ABAP
Dictionary.
This is necessary because the HelpValues.GetList method refers to the help view for the
check table, matchcodes or domain fixed values linked to the field in the ABAP Dictionary.
Note
Whenever possible, you should therefore specify the appropriate check table,
matchcodes or domain fixed values in the reference structure of a field in order to
enable a calling program to access the valid input values for the field.
Authorization Check
In some situations it will be necessary to only allow those persons with a particular user profile
to access to information in F4 possible entries. To do this you can carry out authorization
checks within your BAPI:
Table BAPIF4T is provided for this purpose. This table comprises the following fields which
you have to fill with the corresponding entries of your BAPI.
• OBJTYPE (object type)
The technical name of the SAP Business Object, for example, BUS1065.
• METHOD (verb)
The name of a BAPI for the Business Object named above, for example, GetList.
• DTEL (data element)
The name of a data element for which a possible entry is specified. For example, an
elementary input help could be specified for the data element PERNR_D and be protected
from unauthorized access.
• FNAM (name of function module)
The name of the function module you have to create and that carries out the authorization
check for the data element. This function module must have the following predefined
interface:
_________
42 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
*"-------------------------------------------------------
*"*"Local interface:
*" IMPORTING
*" VALUE(OBJTYPE) LIKE BAPIF4F-OBJTYPE
*" VALUE(METHOD) LIKE BAPIF4F-METHOD
*" VALUE(DTEL) LIKE BAPIF4F-DTEL
*" VALUE(SHLPNAME) LIKE BAPIF4F-SHLPNAME
*" VALUE(TABNAME) LIKE BAPIF4F-TABNAME
*" EXPORTING
*" VALUE(RETURN) LIKE BAPIF4F-RETURN
*"---------------------------------------------------------
As the template for your function module you can use the function module
BF_BAPI_F4_AUTHORITY which provides exactly this interface. Copy this function
module and follow the documentation provided with it.
The additional parameter SHLPNAME contained in the function module interface provides
the name of the active input help for the table or for the data element. The parameter
TABNAME contains the name of the value table.
The return code of the parameter RETURN is:
- 'X' if the user of the BAPI is not authorized to call up the valid input values for a field.
- ' ' (no value) if the user of the BAPI is authorized to display the input values for a field.
During runtime the function module is called dynamically by the BAPI HelpValues.GetList.
An authorization check can be carried out at Business Object, method or data element
level:
To carry out authorization check at this ...the following fields in table BAPIF4T must
level... be filled.
Business Object OBJTYPE, FNAM
BAPI OBJTYPE, METHOD, FNAM
Data element OBJTYPE, METHOD, DTEL, FNAM
_________ __________________________________________________________________
43
A Tutorial on Business Application Programming Interface_____________________________
_________
44 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Note
Enhancements to BAPIs only take effect when you have defined the changes in the
BOR, that is, changes have been saved and generated. The BOR also provides
version control for your BAPIs.
Example
Example
An additional input field for the applicant's educational background is added to the
BAPI Applicant.CreateFromData.
_________ __________________________________________________________________
45
A Tutorial on Business Application Programming Interface_____________________________
Process Flow
When continuing the development of your BAPI, you should attempt to make compatible
changes in order to limit the impact of your modifications on existing programs which use the
BAPI. When adding a new import parameter, consider whether the interface would function
without the parameter. If so, the new parameter can be added as a compatible interface
enhancement. Otherwise you will have to make an incompatible interface enhancement, as
described in this section.
Example
_________
46 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
_________ __________________________________________________________________
47
A Tutorial on Business Application Programming Interface_____________________________
Process Flow
There are four ways the standard R/3 System can be adapted to meet customer needs:
Customizing, enhancements, modifications and customers' own developments. The following
sections describe how BAPIs can be adapted within the framework of each of these four
ways.
Customizing
There are no special Customizing settings for BAPIs.
Enhancements
At present there are no customer exits or application-specific exits for BAPIs.
Changes can be made, however, in the ABAP Dictionary. New fields can be added at the end
of a BAPI interface structure. See also Enhancements to Existing BAPIs.
Modifications
You can modify an existing BAPI interface provided that only new optional parameters are
involved. See also Enhancements to Existing BAPIs.
You can also modify the BAPI source code but do follow the "Guidelines for Modifying the
SAP Standard System". Keep in mind that an improved mechanism for making customer
modifications of the SAP Standard System will be introduced in a later R/3 Release. For this
reason SAP recommends that, for the time being you use one of the procedures described
below to make modifications to a BAPI's source code so as not to change the SAP Standard
System in the process:
Creating a BAPI for an existing Business Object
You can copy an existing BAPI and add it to an existing Business Object as a new BAPI. To
do this:
• Copy the function module the BAPI is based on into the customer name space. For
example, you could copy the function module BAPI_CUSTOMERCODE_GETLIST into
Y_BAPI_CUSTOMERCODE_GETLIST.
• Make the required changes to the new function module by changing the interface and the
source code as required.
• When you have changed and tested the function module and its interface you can define
it as a new method of the appropriate business object, as described in Defining Methods
in the BOR Using the BOR/BAPI Wizard
Make sure you give the method a name taken from the customer name space. For
example, if you have modified the BAPI GetList of the Business Object CustomerCode,
you should define your development as the method YGetList.
Creating a BAPI for a new Business Object
You can create a subtype for an existing object type. This way all methods of the object are
_________
48 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
inherited by the subtype. You can then make changes to the copied method. To do this:
• Copy an existing Business Object type into the customer name space. This object type
(subtype) acquires all methods of the existing object type. For example, you could copy
the Business Object SalesOrder into YSalesOrder.
• You can now change the required BAPI of the Business Object YSalesOrder by creating a
new function module for the BAPI and assigning it to the method using the BOR/BAPI-
Wizard.
_________ __________________________________________________________________
49
A Tutorial on Business Application Programming Interface_____________________________
Purpose
Since Release 3.0 ALE (Application Link Enabling) technology has enabled data to be
exchanged between individual distributed SAP Systems and non-SAP systems.
In distributed environments it is particularly important that the individual systems are loosely
coupled together and are independent of each other. Even if one of the systems fails, or a
communications link is interrupted, the remaining systems must be able to continue to
function. Loose coupling means that the individual systems for the most part communicate
asynchronously with each other. For these reasons asynchronous messaging is used for
data communication between the participating systems in ALE distribution scenarios.
From Release 4.0 you can implement an asynchronous BAPI interface by generating an IDoc
from the BAPI and using it in an appropriate ALE distribution scenario.
For further information on ALE technology and using BAPIs in the context of ALE see ALE
Programming.
This section provides a general overview of points you should keep in mind when
implementing a BAPI to exchange data asynchronously.
Process Flow
When a BAPI is used to exchange data asynchronously within the context of ALE the
following processes are involved:
• When the BAPI is called in the sending system, a function module fills the corresponding
IDoc with the data from the BAPI call.
• This IDoc is dispatched to the target system.
• In the target system another function module is used to call the BAPI with the data from
the IDoc.
You can use a transaction to create the additional objects required for the BAPI in this
process, that is, the associated IDoc and the two function modules. This transaction is
described in detail in ALE Programming.
Prerequisites
Before you can implement a BAPI used to transfer data asynchronously in ALE, make sure
that a BAPI of this type is actually required for the task in hand. If one of the following
conditions applies then you should implement your BAPI as an asynchronous interface:
• Consistent database changes in both systems
Data must be updated consistently on both the local system and on the remote system.
• Loose coupling
A synchronous interface would constitute too narrow a coupling between the client and
the server system. If the connection is interrupted the client system would not be able to
function properly.
• Performance
The interface is frequently used or it deals with large volumes of data. In this situation a
synchronous interface cannot be used because performance would be too low.
Additional Guidelines
If you are sure you want to implement your BAPI as an asynchronous interface you should
_________
50 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
keep in mind the following points in addition to the usual BAPI programming guidelines:
• The BAPI must not issue a Commit Work command.
• The BAPI Return parameter must use the reference structure BAPIRETURN1 or
BAPIRET2.
• All BAPI export parameters with the exception of the Return parameter are ignored and
are not included in the IDoc that is generated.
• After the function module which converts the IDoc into the corresponding BAPI in the
receiving system has been called, status records are written for the IDoc in which
messages sent in the Return parameter are logged.
If the field type is filled with E (error) or A (abort) in at least one of the transferred Return
parameter entries, the status 51 (application document has not been posted) is assigned
to all the status records of the IDoc. Otherwise status 53 is assigned (application
document posted).
_________ __________________________________________________________________
51
A Tutorial on Business Application Programming Interface_____________________________
1
23
BAPI Implementation Checklist
This checklist summarizes the individual steps you need to complete when implementing a
BAPI.
Print this checklist and use the printout during the entire implementation phase of your BAPI.
Ensure that you answer "yes" to each item on the list.
OK? Task
Defining the scenario in which the BAPI will be used
Have you defined the relationship between the BAPI you are planning to
implement and other, related BAPIs?
Have you identified the SAP Business Object in the Business Object
Repository to which the BAPI will be added as a method?
Have you included the key fields of the SAP Business Object in the BAPI
interface?
Have you identified the name of the function group or have you planned a
_________
52 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Have you planned the name of the function module on which the BAPI is
based, using the format
BAPI_<Business Object name>_<method name>?
Have you defined the function module interface using only EXPORTING,
IMPORTING and TABLES parameters?
Have you included the key fields of the SAP Business Object as parameters of
the function module (i.e. depending on whether the BAPI is instance-
dependent or instance-independent)?
Have you assigned correct names to the parameters in the function module?
Do the function module parameters for the Business Object's key fields have
the same name as the key fields of the Business Object in the BOR?
Have you avoided the use of abbreviations in the names of function module
parameters?
Did you ensure that none of the parameters in the function module is
customizing-relevant or affects system settings in any other way?
Are all IMPORTING parameters independent from each other, i.e. did you
ensure that none of the parameters is derived from another?
Have you defined the formats in which the values must be transferred in the
function module interface?
Are you using the Dictionary structure BAPIRETURN1 or BAPIRET2 for the
Return parameter (as of Release 4.0)?
_________ __________________________________________________________________
53
A Tutorial on Business Application Programming Interface_____________________________
Have you assigned a corresponding currency code field to each field with
currency amounts?
Have you assigned a field for the unit of measure to each quantity field?
Have you defined Dictionary structures for each function module parameter?
Have you defined Help views or fixed values for the fields in order to enable
your BAPI to provide input help (F4 help) for each field?
Have you used English names for the fields, preferably those names that have
been assigned to the corresponding data elements in the ABAP Dictionary?
Can the user of your BAPI access the values for each import field either by
referring to the documentation, by obtaining input help (F4 help), or by using a
GetDetail BAPI?
Have you used a structure with the fields SIGN, OPTION, LOW and HIGH for
the corresponding BAPI parameter that selects values (for example,
Material.GetList)?
Are the names of the parameters of the method in the BOR and the names of
the parameters in the function module the same?
_________
54 __________________________________________________________________
A Tutorial on Business Application Programming Interface_____________________________
Did you ensure that there are no underscores in the parameter names?
Did you start each new word in a method name with a capital letter?
Did you create the documentation for the BAPI in the Function Builder?
Did you use the program to map between internal and external data formats?
Did you use the BOR/BAPI wizard to define the BAPI as a method in the
BOR?
Are the parameter names and types of the method in the BOR and of the
function module in the Function Builder the same?
Documentation
Did you write appropriate documentation for the BAPI in the Function Builder?
Did you test the function module using the test environment of the Function
Builder?
Did you test the BAPI using the test environment of the Business Object
Builder?
Did you test the BAPI by calling the method via the BAPI ActiveX Control?
_________ __________________________________________________________________
55
A Tutorial on Business Application Programming Interface_____________________________
Did you test the BAPI by making an RFC call to the underlying function
module?
Did you test the documentation for its completeness, correctness and
availability in the required logon languages?
_________
56 __________________________________________________________________