BAPIs
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 of SAP Business Object Types
BAPIs are defined as API methods of SAP business object types. These business object types and their BAPIs are described and stored in the Business Object Repository (BOR). A BAPI is implemented as a function module, that is stored and described in the Function Builder.
BAPIs of SAP Interface Types
As of Release 4.5A BAPIs can also describe interfaces, implemented outside the R/3 System that can be called in external systems by R/3 Systems. These BAPIs are known as BAPIs used for outbound processing. The target system is determined for the BAPI call in the distribution model of Application Link Enabling (ALE).
BAPIs used for outbound processing are defined in the Business Object Repository (BOR) as API methods of SAP Interface Types. Functions implemented outside the R/3 System can be standardized and made available as BAPIs. For further information see BAPIs Used For Outbound Processing.
Integration
BAPIs can be called within the R/3 System from external application systems and other programs. BAPIs are the communication standard for business applications. BAPI interface technology forms the basis for the following developments:
• Connecting:
• New R/3 components, for example, Advanced Planner and Optimizer (APO) and Business Information Warehouse (BW).
• Non-SAP software
• Legacy systems
• Isolating components within the R/3 System in the context of Business Framework
• Distributed R/3 scenarios with asynchronous connections using Application Link Enabling (ALE)
• Connecting R/3 Systems to the Internet using Internet Application Components (IACs)
• PC programs as front-end to the R/3 System, for example, Visual Basic (Microsoft) or Visual Age for Java (IBM).
• Workflow applications that extend beyond system boundaries
• Customers' and partners' own developments
BAPIs - Interfaces to the R/3 System
BOR
Definition
The Business Object Repository (BOR) is the object-oriented repository in the R/3 System. It contains the SAP business object types and SAP interface types as well as their components, such as methods, attributes and events.
BAPIs are defined as methods of SAP business object types (or SAP interface types) in the BOR. Thus defined, the BAPIs become standard with full stability guarantees as regards their content and interface.
For general information on creating business objects see the documentation on SAP Business Workflow.
Use
The BOR has the following functions for SAP business object types and their BAPIs:
• 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.
This finds the functionality searched for 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
A BAPI is implemented as a function module that is stored and described in the Function Builder. You should only define a BAPI as a method of an SAP business object type in the BOR, if the function module that the BAPI is based on has been fully implemented.
Access to the BOR is restricted at SAP.
BOR/BAPI Wizard
The BOR/BAPI Wizard helps you to create new BAPIs in the BOR. It takes you through the process step by step.
Defining and Implementing the BAPI
Purpose
Various components of the ABAP Workbench are used when you define and implement a BAPI. These are shown in the graphic below.
BAPIs are defined in the Business Object Repository (BOR) as API methods of SAP business object types. BAPIs are implemented in the Function Builder as RFC-enabled function modules. The definitions and descriptions of the data structures used by the BAPI are stored in the ABAP Dictionary.
BOR, Function Builder and ABAP Dictionary
Prerequisites
For function modules that implement BAPIs, certain standards and rules must be adhered to over and above the standard programming rules for function modules.
The following sections guide you through the steps involved in developing a BAPI. The sections contain information about the guidelines and conventions that you should adhere to when defining and implementing a BAPI. When implementing BAPIs follow the requirements below to ensure you achieve consistent behavior and representation of BAPIs as object-oriented methods of SAP business object types or SAP interface types.
Showing posts with label BAPI'S IN SAP ABAP. Show all posts
Showing posts with label BAPI'S IN SAP ABAP. Show all posts
Thursday, January 8, 2009
ABAP BAPI II
BAPI Explorer
Definition
The BAPI Explorer is the R/3 System working environment for developing BAPIs themselves and for developing with BAPIs.
Use
Prerequisites
The BAPI Explorer is available as of Release 4.6A and enhances or replaces the BAPI Browser used in earlier releases. The BAPI Explorer uses the latest HTML control technology. For this reason to work with the BAPI Explorer, you must be using a SAPgui of version 4.6A.
If you are using a SAPgui from an earlier release, the BAPI Browser (Transaction BAPI45) is automatically called instead of the BAPI Explorer. For information about working in the BAPI Browser see BAPI Browser in the BAPI User Guide.
Purpose
In the BAPI Explorer, application developers can get an overview of the status of BAPIs in the BOR. The BAPIs can be determined either by the position of the associated object or interface type in the component hierarchy in the BOR, or from an alphabetical list. All information required to use a particular BAPI is provided in the BAPI Explorer.
The BAPI Explorer is used internally in SAP to develop BAPIs, but can also be used by customers and partners. The BAPI Explorer provides all the tools used to create BAPIs and the required development objects in an integrated programming environment. The entire development process of a BAPI takes place in the framework of form-controlled "projects" to achieve maximum quality, stability and usability of the BAPI.
Structure
The BAPI Explorer is divided into two areas:
• Hierarchy display
Here all the business object types or interface types for which BAPIs have been defined are displayed. For further information see Working with Display Functions.
• Work area
Here the details and documentation of the development object selected in the hierarchy display can be viewed.
The tools used to develop BAPIs are also available in the work area. For further information see Working with Tools and Projects.
Integration
To call the BAPI Explorer choose Tools Business Framework BAPI Explorer. To call it directly use Transaction BAPI.
Working with Display Functions
Use
In the hierarchy display of the BAPI Explorer all the business object types or interface types for which BAPIs have been defined are displayed.
Using the tabs Alphabetical and Hierarchical in the hierarchy display, you can select whether the business object types or interface types are displayed alphabetically or as they are assigned in the component hierarchy in the BOR.
By expanding the relevant nodes you can navigate up to the parameter level of individual BAPIs.
Features
The following display functions are also provided which enable you to directly access BAPIs and their details in the BOR.
• Displaying details
Under the Detail view of the work area all the technical details of the development object selected in the hierarchy are displayed.
In most cases you can double-click on a field in the Detail display to get to the development environment or to display further information. For example, in the detail display for a particular method, by double clicking on the name of the function module, it will be displayed in the Function Builder.
• Displaying and Printing Documentation
In the Documentation view of the work area the documentation for the development object selected in the hierarchy is displayed.
The data element documentation for each parameter field is contained in the documentation for structured BAPI parameters.
If you have installed Microsoft Internet Explorer Version 4.0 on the front-end computer, you can print the documentation using the standard SAPgui print function.
• Changing the level of the hierarchy display
The component hierarchy may have many hierarchy levels. To make it easier to find a business object type and its BAPIs, you can use the function Goto Change hierarchy level to limit the display to two hierarchy levels.
• Specifying the BAPIs to be displayed
The default is to display only released BAPIs of business object types. By choosing Goto BAPIs to display, you can display all the BAPIs contained in the BOR, that is BAPIs of SAP interface types and BAPIs that have not yet been released.
Business object types and interface types are identified by different symbols. To display these, choose Goto Display legend.
• Searching for BAPIs
Using the standard functions Find and Find next you can search the displayed business object types or interface types using specified criteria (placeholders such as ' * ' can be used):
• Object name, e.g. Business Process
• Object type (technical object name) e.g. SAP0001
• Object description, e.g. Plan*
• Method name, e.g. GetList
• Method description, e.g. object list*
Working with Tools and Projects
Use
The views Tools and Projects in the work area are mainly used for developing BAPIs.
Features
Depending on the development object selected in the hierarchy display, in the Tools view, the following tools and navigation options are provided:
• Direct access to the Business Object Builder, Function Builder and ABAP Dictionary.
• List generator to create lists of BAPIs using specified selection criteria.
In the Project view you can create projects to assist you with following and documenting the development procedures below:
• Implementing new BAPIs (for internal SAP use, BAPI developments must be carried out and documented using a project in the BAPI Explorer)
• Changing released BAPIs (only for SAP internal use)
• Requesting a new business object type (only for SAP internal use)
For each of these projects there is a project form that takes you step by step through the entire development process and provides direct navigation options to the required development tools and information.
Within the project management you can save and delete your projects and you can edit the projects managed by other users by selecting other users.
If you have installed Microsoft Internet Explorer Version 4.0 on the front-end computer, you can print the project form using the standard SAPgui print function.
Defining the Scenario
Purpose
Before you program a BAPI you should clearly define the processes and situations the BAPI will be used for. BAPIs should only be implemented within the context of a meaningful business scenario.
For examples of BAPI scenarios refer to Overview of ALE Integration Scenarios in the Library of ALE Business Processes. SAP developers will also find templates for defining and documenting BAPI scenarios.
Process Flow
To define the scenario the BAPI is to be used in, 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.
Keep in mind whilst you are planning the scenario that COMMIT WORK commands must not be used in BAPIs. COMMIT WORK commands can adversely effect the process flow of the scenario and how the BAPIs in the scenario work together.
• Which SAP business object types are required and do they exist?
From the scenario definition you can get information about the SAP business object types relevant to the BAPI scenario. If the business object types required do not exist, they must be created. For information about creating SAP business object types see the documentation, SAP Business Workflow. For SAP internal development you have to complete a business object request form in the BAPI Explorer.
A BAPI is required to read the data of a company code. First of all, a list of all company codes is to be displayed. From this list a company code can be selected, and then using another BAPI, details about this company code are to be displayed.
The relevant SAP business object type for this scenario is Company Code.
• What functionality should the BAPI provide and how does it affect related BAPIs, especially the other BAPIs of the SAP business object type in question?
In line with the scenario concept, BAPIs must complement each other to create a complete scenario. Their relationships with each other must be clearly defined.
To read the details of a company code as described in the above example scenario, two BAPIs are required:
• To display all the company codes
• To display a specific company code
The interdependency between these two BAPIs is evident because first the list of company codes is displayed to obtain the ID of the specific company code sought. From this ID details of the company code can be displayed.
However, the two BAPIs remain functionally independent of each other, because if the company code ID is known, the BAPI "Display details of a specific company code" can be used without first calling the BAPI "Display list of all company codes".
• 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 type. If the data of a different SAP business object type is to be read or updated then the appropriate interface for this object type must be used. The functions or methods of these other object types are used implicitly.
The BAPIs required to read the details of a company code in the above example scenario are only able to access data in the SAP business object type Company Code. Other object types are not involved.
• Is the BAPI assigned to the SAP business object type 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 object types relevant to the BAPI scenario.
Definition
The BAPI Explorer is the R/3 System working environment for developing BAPIs themselves and for developing with BAPIs.
Use
Prerequisites
The BAPI Explorer is available as of Release 4.6A and enhances or replaces the BAPI Browser used in earlier releases. The BAPI Explorer uses the latest HTML control technology. For this reason to work with the BAPI Explorer, you must be using a SAPgui of version 4.6A.
If you are using a SAPgui from an earlier release, the BAPI Browser (Transaction BAPI45) is automatically called instead of the BAPI Explorer. For information about working in the BAPI Browser see BAPI Browser in the BAPI User Guide.
Purpose
In the BAPI Explorer, application developers can get an overview of the status of BAPIs in the BOR. The BAPIs can be determined either by the position of the associated object or interface type in the component hierarchy in the BOR, or from an alphabetical list. All information required to use a particular BAPI is provided in the BAPI Explorer.
The BAPI Explorer is used internally in SAP to develop BAPIs, but can also be used by customers and partners. The BAPI Explorer provides all the tools used to create BAPIs and the required development objects in an integrated programming environment. The entire development process of a BAPI takes place in the framework of form-controlled "projects" to achieve maximum quality, stability and usability of the BAPI.
Structure
The BAPI Explorer is divided into two areas:
• Hierarchy display
Here all the business object types or interface types for which BAPIs have been defined are displayed. For further information see Working with Display Functions.
• Work area
Here the details and documentation of the development object selected in the hierarchy display can be viewed.
The tools used to develop BAPIs are also available in the work area. For further information see Working with Tools and Projects.
Integration
To call the BAPI Explorer choose Tools Business Framework BAPI Explorer. To call it directly use Transaction BAPI.
Working with Display Functions
Use
In the hierarchy display of the BAPI Explorer all the business object types or interface types for which BAPIs have been defined are displayed.
Using the tabs Alphabetical and Hierarchical in the hierarchy display, you can select whether the business object types or interface types are displayed alphabetically or as they are assigned in the component hierarchy in the BOR.
By expanding the relevant nodes you can navigate up to the parameter level of individual BAPIs.
Features
The following display functions are also provided which enable you to directly access BAPIs and their details in the BOR.
• Displaying details
Under the Detail view of the work area all the technical details of the development object selected in the hierarchy are displayed.
In most cases you can double-click on a field in the Detail display to get to the development environment or to display further information. For example, in the detail display for a particular method, by double clicking on the name of the function module, it will be displayed in the Function Builder.
• Displaying and Printing Documentation
In the Documentation view of the work area the documentation for the development object selected in the hierarchy is displayed.
The data element documentation for each parameter field is contained in the documentation for structured BAPI parameters.
If you have installed Microsoft Internet Explorer Version 4.0 on the front-end computer, you can print the documentation using the standard SAPgui print function.
• Changing the level of the hierarchy display
The component hierarchy may have many hierarchy levels. To make it easier to find a business object type and its BAPIs, you can use the function Goto Change hierarchy level to limit the display to two hierarchy levels.
• Specifying the BAPIs to be displayed
The default is to display only released BAPIs of business object types. By choosing Goto BAPIs to display, you can display all the BAPIs contained in the BOR, that is BAPIs of SAP interface types and BAPIs that have not yet been released.
Business object types and interface types are identified by different symbols. To display these, choose Goto Display legend.
• Searching for BAPIs
Using the standard functions Find and Find next you can search the displayed business object types or interface types using specified criteria (placeholders such as ' * ' can be used):
• Object name, e.g. Business Process
• Object type (technical object name) e.g. SAP0001
• Object description, e.g. Plan*
• Method name, e.g. GetList
• Method description, e.g. object list*
Working with Tools and Projects
Use
The views Tools and Projects in the work area are mainly used for developing BAPIs.
Features
Depending on the development object selected in the hierarchy display, in the Tools view, the following tools and navigation options are provided:
• Direct access to the Business Object Builder, Function Builder and ABAP Dictionary.
• List generator to create lists of BAPIs using specified selection criteria.
In the Project view you can create projects to assist you with following and documenting the development procedures below:
• Implementing new BAPIs (for internal SAP use, BAPI developments must be carried out and documented using a project in the BAPI Explorer)
• Changing released BAPIs (only for SAP internal use)
• Requesting a new business object type (only for SAP internal use)
For each of these projects there is a project form that takes you step by step through the entire development process and provides direct navigation options to the required development tools and information.
Within the project management you can save and delete your projects and you can edit the projects managed by other users by selecting other users.
If you have installed Microsoft Internet Explorer Version 4.0 on the front-end computer, you can print the project form using the standard SAPgui print function.
Defining the Scenario
Purpose
Before you program a BAPI you should clearly define the processes and situations the BAPI will be used for. BAPIs should only be implemented within the context of a meaningful business scenario.
For examples of BAPI scenarios refer to Overview of ALE Integration Scenarios in the Library of ALE Business Processes. SAP developers will also find templates for defining and documenting BAPI scenarios.
Process Flow
To define the scenario the BAPI is to be used in, 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.
Keep in mind whilst you are planning the scenario that COMMIT WORK commands must not be used in BAPIs. COMMIT WORK commands can adversely effect the process flow of the scenario and how the BAPIs in the scenario work together.
• Which SAP business object types are required and do they exist?
From the scenario definition you can get information about the SAP business object types relevant to the BAPI scenario. If the business object types required do not exist, they must be created. For information about creating SAP business object types see the documentation, SAP Business Workflow. For SAP internal development you have to complete a business object request form in the BAPI Explorer.
A BAPI is required to read the data of a company code. First of all, a list of all company codes is to be displayed. From this list a company code can be selected, and then using another BAPI, details about this company code are to be displayed.
The relevant SAP business object type for this scenario is Company Code.
• What functionality should the BAPI provide and how does it affect related BAPIs, especially the other BAPIs of the SAP business object type in question?
In line with the scenario concept, BAPIs must complement each other to create a complete scenario. Their relationships with each other must be clearly defined.
To read the details of a company code as described in the above example scenario, two BAPIs are required:
• To display all the company codes
• To display a specific company code
The interdependency between these two BAPIs is evident because first the list of company codes is displayed to obtain the ID of the specific company code sought. From this ID details of the company code can be displayed.
However, the two BAPIs remain functionally independent of each other, because if the company code ID is known, the BAPI "Display details of a specific company code" can be used without first calling the BAPI "Display list of all company codes".
• 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 type. If the data of a different SAP business object type is to be read or updated then the appropriate interface for this object type must be used. The functions or methods of these other object types are used implicitly.
The BAPIs required to read the details of a company code in the above example scenario are only able to access data in the SAP business object type Company Code. Other object types are not involved.
• Is the BAPI assigned to the SAP business object type 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 object types relevant to the BAPI scenario.
ABAP BAPI III
Defining a BAPI and Its Interface
Purpose
After you have carried out the review of the BAPI concept and it has been accepted, you can start defining the BAPI itself.
In this step, you will decide on the names, parameters, and characteristics of the BAPI and determine the structures in the ABAP Dictionary, which the BAPI will be based on. Only after you have planned and defined these required details can you start to implement the BAPI and create the required programming objects.
The table below illustrates where the planned information is written and how it fits together.
Information in the BOR, Function Builder and ABAP Dictionary
Standardized BAPIs
Use
Some BAPIs and methods provide basic functions and can be used for most SAP business object types. Such BAPIs are known as "standardized" BAPIs.
Features
With object methods and especially with BAPIs, you can differentiate between instance methods and class methods. Instance methods refer to precisely one instance (one specific occurrence) of an SAP Business Object type, for example, to one explicitly specified customer order. Whereas class methods are instance-independent.
BAPIs for Reading Data
The following BAPIs provide you with read-only access to data in the associated business object type:
GetList()
With the BAPI GetList() you can select a range of object key values, for example, company codes and material numbers. The BAPIs GetList() is a class method.
Programming GetList() BAPIs
Use
With the BAPI GetList() you can select a range of object key values, for example, company codes and material numbers. The key values returned by this BAPI can be passed on to another BAPI for further processing, for example, the BAPI GetDetail().
The BAPIs GetList() is a class method (instance-independent).
Features
Provide all the relevant fields in the interface of the GetList() BAPI. How complex and extensive you structure the interface, depends on the requirements the BAPI is to fulfill.
Import Parameters
The interface of a GetList() BAPI must provide selection parameters, in which the required selection criteria can be passed on by the calling program. The structure of selection parameters is described in the section Selection Parameters.
You must also create the parameter MaxRows that enables you to limit the number of entries selected. This parameter prevents too large a value set from being selected, if the selection parameter specification is not very precise. Use the data element BAPIMAXROW as the reference type for the MaxRows parameter.
Export Parameters
The key values selected by the BAPI GetList() are returned to the calling program in a table, together with other useful information, for example, short texts.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see
Return Parameters (Error Handling).
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
GetDetail()
The BAPI GetDetail() uses a key to retrieve details about an instance (one specific occurrence) of a business object type and returns this data to the calling program. Then this information is reported back to the calling program. The BAPI GetDetail() is an instance method.
Programming GetDetail() BAPIs
Use
The BAPI GetDetail() is used to read details of specific object instances.
The BAPI GetDetail() is an instance method.
Features
Import Parameters
The import parameters of the GetDetail() BAPI must contain the key fields of the business object type.
For the associated method definition in the BOR, the key fields must not also be specified as method parameters. For this reason, the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition, when it creates a BAPI.
Export Parameters
The export parameters of a BAPI contain details of the instance. According to the amount of information, this should be structured in several parameters with meaningful names.
To report messages from the method call back to the calling program, you should create the export parameter Return. For more information about this parameter see Return Parameters (Error Handling).
Extension Parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
GetStatus()
The BAPI GetStatus() is used to query the status of an SAP business object instance, for example, the processing status of a sales order. This BAPI is used only for displaying the status of an object and does not retrieve full details like the BAPI GetDetail(). The BAPI GetStatus() is an instance method.
Programming GetStatus() BAPIs
Use
With the BAPI GetStatus() you can retrieve information about the status of a particular object instance.
The BAPI GetStatus() is an instance method.
Features
Import Parameters
The import parameters of the GetStatus() BAPI must contain the key fields of the business object type.
For the associated method definition in the BOR, the key fields must not also be specified as parameters. For this reason, the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition, when it creates a BAPI.
Export Parameters
The export parameters of the BAPI contain information about the status of an object instance.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see Return Parameters (Error Handling).
Extension Parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
ExistenceCheck()
The BAPI ExistenceCheck() checks whether an entry exists for a business object instance, for example, whether the customer master has been created. The ExistenceCheck() BAPI is an instance method.
Programming ExistenceCheck() BAPIs
Use
The BAPI ExistenceCheck() checks whether an entry exists in the database for an SAP business object type, for example, whether the customer master has been created.
The ExistenceCheck() BAPI is an instance method.
Features
You can implement this method as a BAPI and/or as a method of SAP Business Workflow. If you implement this method as a BAPI, it only has to be implemented once, because an ExistenceCheck() BAPI can also be used by SAP Business Workflow.
To get the highest possible performance from the BAPI ExistenceCheck(), you should reduce the number of columns to as few as possible before selecting the table rows.
select single bukrs from bkpf into lv_bukrs
where bukrs = bkpf-bukrs
and belnr = bkpf-belnr
and gjahr = bkpf-gjahr.
instead of
select single * from bkpf
where bukrs = bkpf-bukrs
and belnr = bkpf-belnr
and gjahr = bkpf-gjahr.
Import Parameters
The BAPI's import parameters in the function module only contain the key fields of the business object type.
Export Parameters
To report messages from the method call back to the calling program, you should create only the export parameter Return . For more information about this parameter see Return Parameters (Error Handling).
Activities
When a business object type is created, as the default, it inherits a definition of the method ExistenceCheck() through the interface IFSAP. For this reason, you can create an ExistenceCheck() BAPI using the BOR/BAPI Wizard, as the method name ExistenceCheck() already exists for the business object type.
We recommend therefore, that you redefine the existing method ExistenceCheck() manually in the BOR, via the menu path Edit Redefine.
• Enter the function module that implements the ExistenceCheck() BAPI.
• Create the method parameter RETURN (the key fields of the business object type are not included in the method definition in the BOR).
BAPIs for Creating or Changing Data
The following BAPIs can create, change or delete instances of a business object type:
Create() or CreateFromData()
The BAPI Create() or CreateFromData() creates an instance of an SAP business object type, for example, a purchase order. These BAPIs are class methods.
Programming Create() BAPIs
Use
The BAPI Create() creates one instance of an SAP business object type. Likewise, the BAPI CreateMultiple() creates several instances of a business object type simultaneously.
If a workflow method called Create already exists for the business object type in question, you can use the name CreateFromData() for your BAPI. Create() is the preferred name for this BAPI.
The BAPIs Create() and CreateMultiple() are class methods (instance-independent).
For each Create() BAPI a method must be provided with which the created business object instance can be deleted or cancelled. To do this, depending on the business application practice, you should implement one of the BAPIs below:
• Delete(), which deletes a business object instance from the database. For more information see Programming Delete() BAPIs.
• Cancel() which cancels a business object instance. For more information see Programming Cancel() BAPIs.
Features
Import Parameters
The BAPI's import parameters in the function module contain the data required to uniquely identify an instance. For this you can either enter all object keys or else you must ensure that these can be derived.
If required, you can also use a test run parameter to check the entry for an object instance before actually creating the instance in the database. For further information see Test Run Parameters.
You can create a change parameter to identify the values to create the instance with and to tell differentiate these values from the initial values when the BAPI is called. We recommend that you identify the change-relevant fields by flagging them.
For more information see Change Parameters.
Export Parameters
To make the object key available to the calling program, the entire key fields must be returned in the export parameters.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see Return Parameters (Error Handling).
Extension parameters
You can create extension parameters to enable customers to enhance the functionality
of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
Avoiding Incompatibilities with Customizing Settings
It could be possible that certain values set by Customizing appear differently in the BAPI interface. These values cannot be overwritten by a Create() BAPI.
To avoid any incompatibility with Customizing settings, you should implement a Create() BAPI in the following way:
• The BAPI should transfer all the fields and check them against the Customizing settings. If the Customizing settings write-protect a field, the data in this field cannot be overwritten by data in the BAPI interface.
• For every incidence of incompatibility an error message must be returned to the calling program. For example, "Customizing settings do not allow the field 'MyAsset-AssetName' to be modified ".
• All the fields that are assigned default values by Customizing and are therefore write-protected, must be documented.
External Key Assignment
For Create() BAPIs with an external key assignment the caller transfers the key (ID) to the object instance to be created, for example, to a document number.
Keep in mind that you have to convert the specified keys explicitly in upper case letters in the source code of this type of Create() BAPIs. Otherwise keys are created that cannot be used in dialog applications. This is because with dialog applications external keys are always converted implicitly in upper case letters.
Locking
We recommend that you implement Create() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.
Change()
The BAPI Change() changes an existing instance of a SAP business object type, for example, a purchase order. The Change() BAPI is an instance method.
Programming Change() BAPIs
Use
The BAPI Change() changes an existing instance of an SAP business object type, for example, a sales order.
The BAPI Change() is an instance method, whereas the BAPI ChangeMultiple() is a class method (instance-independent).
Features
Import Parameters
The import parameters of the Change() BAPI must contain the key fields of the business object type.
If required, you can create also create these parameters:
• A test run parameter for checking the entry for an object instance before actually creating/changing the instance in the database.
• A change parameter to identify parameter fields containing modified values and parameter fields that have not been modified.
For more information about these parameters see Standardized Parameters.
Export Parameters
To make the object key available to the calling program, the entire key fields must be returned in the export parameters.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see Return Parameters (Error Handling).
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
Avoiding Incompatibilities with Customizing Settings
It could be possible that certain values set by Customizing appear differently in the BAPI interface. These values cannot be overwritten by a Change() BAPI.
To avoid incompatibility with Customizing settings, you should implement a Change() BAPI in the following way:
• The BAPI should transfer all the fields and check them against the Customizing settings. If the Customizing settings write-protect a field, the data in this field cannot be overwritten by data in the BAPI interface.
• For every incidence of incompatibility an error message must be returned in the return parameter to the calling program. For example, "Customizing settings do not allow the field 'MyAsset-AssetName' to be modified ".
• All the fields that are assigned default values by Customizing and are therefore write-protected, must be documented.
Locking
We recommend that you implement Change() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.
Delete() and Undelete()
The BAPI Delete() deletes an instance of an SAP business object type from the database, for example, a purchase order.
The BAPI Undelete() removes a deletion flag.
These BAPIs are instance methods.
Programming Delete() BAPIs
Use
The BAPI Delete() deletes an instance of an SAP business object type from the database. Likewise, the BAPI DeleteMultiple() deletes several instances of a business object type. Delete() BAPIs must always delete entire instances, for example, a whole material master.
(Whereas the BAPI Cancel() cancels an instance of a business object, that is the instance to be cancelled remains in the database and an additional instance is created that is canceled. For more information see Programming Cancel() BAPIs).
A delete() BAPI can delete immediately or at a later time by setting the deletion flag. The type of deletion you use in your BAPI is irrelevant to the caller, so you do not have to include these details in the BAPI interface.
The BAPI Undelete() is used to reset a deletion flag that has been set for a specific object.
The BAPIs Delete() and Undelete() are instance methods, whereas the BAPIs DeleteMutliple() and UndeleteMutliple() are class methods (instance-independent).
Features
The interfaces of the Delete() and Undelete() BAPIs should be identical.
Import Parameters
The BAPI's import parameters have to identify the business object instances to be deleted.
• If an instance is to be deleted, you have to create a parameter for each key field in the business object type.
• If several instances are to be deleted, you must create a table for the key fields of the business object type. You can do this using a range table.
If required, you can create also create these parameters:
• A test run parameter for checking the entry for an object instance before actually deleting the instance from the database.
• When the BAPI DeleteMultiple() is used, it must be possible to use the selection criteria to select the object instances to be deleted. To do this you can create selection parameters.
Implement the interface of a Delete() BAPI so that it is not possible to delete all the instances simply by parameterizing the interface, for example by specifying default settings.
Export Parameters
To report messages from the method call back to the calling program, you should create only the export parameter Return . For more information about this parameter see Return Parameters (Error Handling).
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
Locking
We recommend that you implement Delete() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.
Cancel()
Unlike the BAPI Delete () the BAPI Cancel() cancels an instance of a business object, that is the instance to be cancelled remains in the database and an additional instance is created that is canceled).
The Cancel() BAPI is an instance method.
Programming Cancel() BAPIs
Use
The Cancel() BAPI cancels one instance of a business object.
Unlike the BAPI Delete(), which deletes an object instance from the database, with the BAPI Cancel():
• The canceled instance of the business object is not deleted
• An additional instance is created with which the instance of the business object is deleted
The Cancel() BAPI is used to cancel business processes such as goods movements or invoice receipts.
The Cancel() BAPI is an instance method.
Features
Import Parameters
The data of the instance to be created comes from the data of the business object instance to be cancelled.
You can also create further parameters to specify information relevant for the actual cancellation process, for example, the name of the user performing the cancellation.
If required, you can also create a test run parameter, which can check the details of the object instance before it is actually canceled. For more information about this parameter see Test Run Parameters.
Export Parameters
To report messages from the method call back to the calling program, you should create the parameter Return. For more information about this parameter see Return Parameters (Error Handling).
You have to put the key of the created instance in another export parameter.
Locking
We recommend that you implement Cancel() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.
Add and Remove
The BAPI Add adds a sub-object to an existing object instance and the BAPI and Remove removes a sub-object from an object instance. These BAPIs are instance methods.
Purpose
After you have carried out the review of the BAPI concept and it has been accepted, you can start defining the BAPI itself.
In this step, you will decide on the names, parameters, and characteristics of the BAPI and determine the structures in the ABAP Dictionary, which the BAPI will be based on. Only after you have planned and defined these required details can you start to implement the BAPI and create the required programming objects.
The table below illustrates where the planned information is written and how it fits together.
Information in the BOR, Function Builder and ABAP Dictionary
Standardized BAPIs
Use
Some BAPIs and methods provide basic functions and can be used for most SAP business object types. Such BAPIs are known as "standardized" BAPIs.
Features
With object methods and especially with BAPIs, you can differentiate between instance methods and class methods. Instance methods refer to precisely one instance (one specific occurrence) of an SAP Business Object type, for example, to one explicitly specified customer order. Whereas class methods are instance-independent.
BAPIs for Reading Data
The following BAPIs provide you with read-only access to data in the associated business object type:
GetList()
With the BAPI GetList() you can select a range of object key values, for example, company codes and material numbers. The BAPIs GetList() is a class method.
Programming GetList() BAPIs
Use
With the BAPI GetList() you can select a range of object key values, for example, company codes and material numbers. The key values returned by this BAPI can be passed on to another BAPI for further processing, for example, the BAPI GetDetail().
The BAPIs GetList() is a class method (instance-independent).
Features
Provide all the relevant fields in the interface of the GetList() BAPI. How complex and extensive you structure the interface, depends on the requirements the BAPI is to fulfill.
Import Parameters
The interface of a GetList() BAPI must provide selection parameters, in which the required selection criteria can be passed on by the calling program. The structure of selection parameters is described in the section Selection Parameters.
You must also create the parameter MaxRows that enables you to limit the number of entries selected. This parameter prevents too large a value set from being selected, if the selection parameter specification is not very precise. Use the data element BAPIMAXROW as the reference type for the MaxRows parameter.
Export Parameters
The key values selected by the BAPI GetList() are returned to the calling program in a table, together with other useful information, for example, short texts.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see
Return Parameters (Error Handling).
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
GetDetail()
The BAPI GetDetail() uses a key to retrieve details about an instance (one specific occurrence) of a business object type and returns this data to the calling program. Then this information is reported back to the calling program. The BAPI GetDetail() is an instance method.
Programming GetDetail() BAPIs
Use
The BAPI GetDetail() is used to read details of specific object instances.
The BAPI GetDetail() is an instance method.
Features
Import Parameters
The import parameters of the GetDetail() BAPI must contain the key fields of the business object type.
For the associated method definition in the BOR, the key fields must not also be specified as method parameters. For this reason, the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition, when it creates a BAPI.
Export Parameters
The export parameters of a BAPI contain details of the instance. According to the amount of information, this should be structured in several parameters with meaningful names.
To report messages from the method call back to the calling program, you should create the export parameter Return. For more information about this parameter see Return Parameters (Error Handling).
Extension Parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
GetStatus()
The BAPI GetStatus() is used to query the status of an SAP business object instance, for example, the processing status of a sales order. This BAPI is used only for displaying the status of an object and does not retrieve full details like the BAPI GetDetail(). The BAPI GetStatus() is an instance method.
Programming GetStatus() BAPIs
Use
With the BAPI GetStatus() you can retrieve information about the status of a particular object instance.
The BAPI GetStatus() is an instance method.
Features
Import Parameters
The import parameters of the GetStatus() BAPI must contain the key fields of the business object type.
For the associated method definition in the BOR, the key fields must not also be specified as parameters. For this reason, the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition, when it creates a BAPI.
Export Parameters
The export parameters of the BAPI contain information about the status of an object instance.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see Return Parameters (Error Handling).
Extension Parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
ExistenceCheck()
The BAPI ExistenceCheck() checks whether an entry exists for a business object instance, for example, whether the customer master has been created. The ExistenceCheck() BAPI is an instance method.
Programming ExistenceCheck() BAPIs
Use
The BAPI ExistenceCheck() checks whether an entry exists in the database for an SAP business object type, for example, whether the customer master has been created.
The ExistenceCheck() BAPI is an instance method.
Features
You can implement this method as a BAPI and/or as a method of SAP Business Workflow. If you implement this method as a BAPI, it only has to be implemented once, because an ExistenceCheck() BAPI can also be used by SAP Business Workflow.
To get the highest possible performance from the BAPI ExistenceCheck(), you should reduce the number of columns to as few as possible before selecting the table rows.
select single bukrs from bkpf into lv_bukrs
where bukrs = bkpf-bukrs
and belnr = bkpf-belnr
and gjahr = bkpf-gjahr.
instead of
select single * from bkpf
where bukrs = bkpf-bukrs
and belnr = bkpf-belnr
and gjahr = bkpf-gjahr.
Import Parameters
The BAPI's import parameters in the function module only contain the key fields of the business object type.
Export Parameters
To report messages from the method call back to the calling program, you should create only the export parameter Return . For more information about this parameter see Return Parameters (Error Handling).
Activities
When a business object type is created, as the default, it inherits a definition of the method ExistenceCheck() through the interface IFSAP. For this reason, you can create an ExistenceCheck() BAPI using the BOR/BAPI Wizard, as the method name ExistenceCheck() already exists for the business object type.
We recommend therefore, that you redefine the existing method ExistenceCheck() manually in the BOR, via the menu path Edit Redefine.
• Enter the function module that implements the ExistenceCheck() BAPI.
• Create the method parameter RETURN (the key fields of the business object type are not included in the method definition in the BOR).
BAPIs for Creating or Changing Data
The following BAPIs can create, change or delete instances of a business object type:
Create() or CreateFromData()
The BAPI Create() or CreateFromData() creates an instance of an SAP business object type, for example, a purchase order. These BAPIs are class methods.
Programming Create() BAPIs
Use
The BAPI Create() creates one instance of an SAP business object type. Likewise, the BAPI CreateMultiple() creates several instances of a business object type simultaneously.
If a workflow method called Create already exists for the business object type in question, you can use the name CreateFromData() for your BAPI. Create() is the preferred name for this BAPI.
The BAPIs Create() and CreateMultiple() are class methods (instance-independent).
For each Create() BAPI a method must be provided with which the created business object instance can be deleted or cancelled. To do this, depending on the business application practice, you should implement one of the BAPIs below:
• Delete(), which deletes a business object instance from the database. For more information see Programming Delete() BAPIs.
• Cancel() which cancels a business object instance. For more information see Programming Cancel() BAPIs.
Features
Import Parameters
The BAPI's import parameters in the function module contain the data required to uniquely identify an instance. For this you can either enter all object keys or else you must ensure that these can be derived.
If required, you can also use a test run parameter to check the entry for an object instance before actually creating the instance in the database. For further information see Test Run Parameters.
You can create a change parameter to identify the values to create the instance with and to tell differentiate these values from the initial values when the BAPI is called. We recommend that you identify the change-relevant fields by flagging them.
For more information see Change Parameters.
Export Parameters
To make the object key available to the calling program, the entire key fields must be returned in the export parameters.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see Return Parameters (Error Handling).
Extension parameters
You can create extension parameters to enable customers to enhance the functionality
of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
Avoiding Incompatibilities with Customizing Settings
It could be possible that certain values set by Customizing appear differently in the BAPI interface. These values cannot be overwritten by a Create() BAPI.
To avoid any incompatibility with Customizing settings, you should implement a Create() BAPI in the following way:
• The BAPI should transfer all the fields and check them against the Customizing settings. If the Customizing settings write-protect a field, the data in this field cannot be overwritten by data in the BAPI interface.
• For every incidence of incompatibility an error message must be returned to the calling program. For example, "Customizing settings do not allow the field 'MyAsset-AssetName' to be modified ".
• All the fields that are assigned default values by Customizing and are therefore write-protected, must be documented.
External Key Assignment
For Create() BAPIs with an external key assignment the caller transfers the key (ID) to the object instance to be created, for example, to a document number.
Keep in mind that you have to convert the specified keys explicitly in upper case letters in the source code of this type of Create() BAPIs. Otherwise keys are created that cannot be used in dialog applications. This is because with dialog applications external keys are always converted implicitly in upper case letters.
Locking
We recommend that you implement Create() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.
Change()
The BAPI Change() changes an existing instance of a SAP business object type, for example, a purchase order. The Change() BAPI is an instance method.
Programming Change() BAPIs
Use
The BAPI Change() changes an existing instance of an SAP business object type, for example, a sales order.
The BAPI Change() is an instance method, whereas the BAPI ChangeMultiple() is a class method (instance-independent).
Features
Import Parameters
The import parameters of the Change() BAPI must contain the key fields of the business object type.
If required, you can create also create these parameters:
• A test run parameter for checking the entry for an object instance before actually creating/changing the instance in the database.
• A change parameter to identify parameter fields containing modified values and parameter fields that have not been modified.
For more information about these parameters see Standardized Parameters.
Export Parameters
To make the object key available to the calling program, the entire key fields must be returned in the export parameters.
To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see Return Parameters (Error Handling).
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
Avoiding Incompatibilities with Customizing Settings
It could be possible that certain values set by Customizing appear differently in the BAPI interface. These values cannot be overwritten by a Change() BAPI.
To avoid incompatibility with Customizing settings, you should implement a Change() BAPI in the following way:
• The BAPI should transfer all the fields and check them against the Customizing settings. If the Customizing settings write-protect a field, the data in this field cannot be overwritten by data in the BAPI interface.
• For every incidence of incompatibility an error message must be returned in the return parameter to the calling program. For example, "Customizing settings do not allow the field 'MyAsset-AssetName' to be modified ".
• All the fields that are assigned default values by Customizing and are therefore write-protected, must be documented.
Locking
We recommend that you implement Change() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.
Delete() and Undelete()
The BAPI Delete() deletes an instance of an SAP business object type from the database, for example, a purchase order.
The BAPI Undelete() removes a deletion flag.
These BAPIs are instance methods.
Programming Delete() BAPIs
Use
The BAPI Delete() deletes an instance of an SAP business object type from the database. Likewise, the BAPI DeleteMultiple() deletes several instances of a business object type. Delete() BAPIs must always delete entire instances, for example, a whole material master.
(Whereas the BAPI Cancel() cancels an instance of a business object, that is the instance to be cancelled remains in the database and an additional instance is created that is canceled. For more information see Programming Cancel() BAPIs).
A delete() BAPI can delete immediately or at a later time by setting the deletion flag. The type of deletion you use in your BAPI is irrelevant to the caller, so you do not have to include these details in the BAPI interface.
The BAPI Undelete() is used to reset a deletion flag that has been set for a specific object.
The BAPIs Delete() and Undelete() are instance methods, whereas the BAPIs DeleteMutliple() and UndeleteMutliple() are class methods (instance-independent).
Features
The interfaces of the Delete() and Undelete() BAPIs should be identical.
Import Parameters
The BAPI's import parameters have to identify the business object instances to be deleted.
• If an instance is to be deleted, you have to create a parameter for each key field in the business object type.
• If several instances are to be deleted, you must create a table for the key fields of the business object type. You can do this using a range table.
If required, you can create also create these parameters:
• A test run parameter for checking the entry for an object instance before actually deleting the instance from the database.
• When the BAPI DeleteMultiple() is used, it must be possible to use the selection criteria to select the object instances to be deleted. To do this you can create selection parameters.
Implement the interface of a Delete() BAPI so that it is not possible to delete all the instances simply by parameterizing the interface, for example by specifying default settings.
Export Parameters
To report messages from the method call back to the calling program, you should create only the export parameter Return . For more information about this parameter see Return Parameters (Error Handling).
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
Locking
We recommend that you implement Delete() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.
Cancel()
Unlike the BAPI Delete () the BAPI Cancel() cancels an instance of a business object, that is the instance to be cancelled remains in the database and an additional instance is created that is canceled).
The Cancel() BAPI is an instance method.
Programming Cancel() BAPIs
Use
The Cancel() BAPI cancels one instance of a business object.
Unlike the BAPI Delete(), which deletes an object instance from the database, with the BAPI Cancel():
• The canceled instance of the business object is not deleted
• An additional instance is created with which the instance of the business object is deleted
The Cancel() BAPI is used to cancel business processes such as goods movements or invoice receipts.
The Cancel() BAPI is an instance method.
Features
Import Parameters
The data of the instance to be created comes from the data of the business object instance to be cancelled.
You can also create further parameters to specify information relevant for the actual cancellation process, for example, the name of the user performing the cancellation.
If required, you can also create a test run parameter, which can check the details of the object instance before it is actually canceled. For more information about this parameter see Test Run Parameters.
Export Parameters
To report messages from the method call back to the calling program, you should create the parameter Return. For more information about this parameter see Return Parameters (Error Handling).
You have to put the key of the created instance in another export parameter.
Locking
We recommend that you implement Cancel() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.
Add
ABAP BAPI IV
Programming Methods for Sub-Objects
Use
If a business object type consists of sub-objects, you can implement the following standardized BAPIs to add or remove sub-objects:
Add
This method adds a sub-object to an object type.
Remove
This method removes a sub-object from an object.
For example, to add or remove the sub-object purchase order item to the business object type purchase order, the BAPIs AddItem() and RemoveItem() could be implemented for the object type, purchase order.
The BAPIs Add and Remove are instance methods.
Features
Import Parameters
Both BAPIs' import parameters must contain in the function module the data that uniquely identifies the sub-object as well as the key fields of the business object.
If required, you can create also create these parameters:
A test run parameter for checking the entry for an object instance before actually creating the instance in the database.
A change parameter to identify parameter fields containing modified values and parameter fields that have not been modified.
For more information about these parameters see Standardized Parameters.
Export Parameters
You should only create the export parameter RETURN in the BAPI Remove to return messages from the method call to the calling program. For more information about this parameter see Return Parameters (Error Handling).
To make the object key available to the calling program, the key fields of the object type must also be returned in the export parameters of the BAPI Add as well as in the export parameter Return.
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.
Locking
We recommend that you implement methods of sub-objects without the locking function and create your own BAPIs instead that lock the relevant data.
If you are implementing BAPIs that create or change data you should consider using buffering. For further information see Buffering for Write BAPIs.
BAPIs for Mass Processing
The BAPIs listed in the above section, "BAPIs for Creating or Changing Data", can also be used for mass processing. Here, when a BAPI is called, several business object instances are processed at the same time.
With BAPIs for mass processing, the suffix "Multiple" is added to the method name, for example, ChangeMultiple(), CreateMultiple(), DeleteMultiple(). The BAPIs here are always class methods.
We strongly recommend that you create instance-dependent BAPIs with buffering instead of Multiple() BAPIs. For further information see Buffering with Write BAPIs.
BAPIs for Replicating Business Object Instances
The following BAPIs are used 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.
Buffering with Write BAPIs
Use
To save external systems each having to define their own data, predefined buffering mechanisms should be implemented in all write BAPIs (i.e. BAPIs that create and change data).
For SAP internal use this is particularly relevant for BAPIs developed as of Release 4.6A. If you want to implement a buffer for BAPIs in an earlier release, you should first contact a colleague in the central BAPI development group.
For BAPIs standard R/3 System mechanisms can be used to buffer application data. Data to be created or changed by a BAPI is not created in the update buffer, it is first collected in the global buffer of the BAPI function module group. Then the whole buffer is updated at a specified time.
This has the following advantages:
Improvement in performance of the whole system.
The updating of individual operations is delayed and they can all be updated together. Techniques such as "array insert" improve system performance. If buffering is not used, each change must be updated separately.
Several changes to an application instance
With the first change the data is read from the database into the buffer and the change is made in the buffer. With the next change, the system recognizes that the data already exists in the buffer and also makes the change in the buffer. If buffering were not used, the first change would have to be updated before a second change could be made.
Using in Application Link Enabling
BAPIs with buffering are especially suited in situations where mass data is exchanged between systems via Application Link Enabling (ALE).
The buffering mechanism enables application instances to be processed separately in the ALE layer, while still enabling the instances to be updated together. Unlike multiple BAPIs, such as, SaveReplicaMultiple(), this procedure allows error handling of individual instances.
BAPIs with buffering mean that there is no need to use or implement multiple BAPIs.
Integration
The Transaction Model for BAPIs Without Commit in use since Release 4.0 can be enhanced on the basis of these advantages:
Within one Logical Unit of Work (LUW) several changes or detailed changes can be carried out for one instance.
All changes (to one or more instances) are updated together by the BAPI BapiService.TransactionCommit().
Prerequisites
The buffering mechanism for BAPIs must be implicit, that is, the caller must not have to control the buffering. A calling program must be able to use, for example, a Create()or Change() BAPI with buffering as well as it can use a BAPI without buffering. The buffer is updated implicitly in R/3.
If buffering has been implemented for a business object type, all write BAPIs of this business object type must also be implemented with buffering.
If write BAPIs with buffering have been implemented for a business object type, this affects the read BAPIs of this object type. Refer to the information in the Activities section below.
Features
For BAPIs with buffering, in addition to the standard guidelines, the following implementation steps and characteristics described below are required.
Function Modules for Updating the Contents of the Buffer
As BAPIs with buffering can only create or change instances in the buffer, you have to provide one or more function modules to carry out the final update of the buffer contents. These update modules transfer the entire contents of the buffer to the update program.
These function modules should not be implemented as BAPIs, as these are only used in the system in which the buffer is also used.
The naming convention for these function modules is:
_SAVEBUFFER.
Exceptions must not be defined for the update modules, as these are not run until the end of the program, when error handling is no longer possible.
Function Modules for Deleting the Contents of the Buffer
To ensure that the buffer is empty at the start of a transaction, you must provide a function module that deletes the contents of the buffer. This delete function module deletes the entire contents of the buffer and removes any locks on the instances. Neither should you implement this function module as a BAPI, because it is only used in the system in which the buffer is also used.
The naming convention for this function module is:
_CLEARBUFFER.
No exceptions can be defined for delete modules because these are not run until the end of the transaction, when error handling is no longer possible (see Special Characteristics below).
Special Characteristics
BAPIs with buffering need to have special characteristics. For example, these BAPIs must be able to deal with errors because a caller cannot reprocess data in the buffer. As data is buffered implicitly, no administration BAPIs are provided for callers.
Consistency of the Buffer Contents
A BAPI with buffering must carry out all the processing steps, except for updating. The consistency of all instances created or changed in the buffer must be guaranteed by the application.
This means that:
Only operations that can be updated with consistency guaranteed can be carried out in the buffer. The update module itself cannot perform consistency checks.
All other steps required before updating, such as assigning numbers or creating application blocks, must be carried out before calling the update module.
For operations that cannot be updated consistently, no action can take place. In these cases the error situation must be reported in the BAPI return parameter.
Calling Update Modules
After the buffer operations have been successfully carried out, using the command
PERFORM ON COMMIT
call a form routine which then calls the update module(s).
The update modules must be called using the command
CALL _SAVEBUFFER IN UPDATE TASK
to flag the execution in the update program.
By adding 'ON COMMIT' to the command PERFORM ON COMMIT, updating is not carried out immediately,it is carried out in the next COMMIT WORK. This way any number of BAPI calls can be collected together. The final COMMIT WORK command that is executed via the BAPI BapiService.TransactionCommit(), executes the form routine and also each update module once only. For this reason error handling cannot be performed in this form routine or in the function module.
Subscribing the Delete Module
At the start of each LUW the buffer must be empty. Any instances that may exist in the buffer, which were updated in an earlier LUW, are no longer blocked and may be older than the versions in the database. If this instance is updated again, inconsistencies would result.
At the end of each LUW, the buffer contents must be deleted by calling the delete module. This can only be done by the BAPIs BapiService.TransactionCommit() and BapiService.TransactionRollback(). To supply these BAPIs with the necessary information, BAPIs with buffering must subscribe their delete module for the BAPI BapiService.TransactionCommit() bow. BapiService.TransactionRollback().
The delete module is subscribed by calling the central function module BUFFER_SUBSCRIBE_FOR_REFRESH, whereby the parameter NAME_OF_DELETEFUNC must contain the name of the delete module.
No COMMIT WORK or ROLLBACK WORK Command
BAPIs with buffering must not execute COMMIT WORK or ROLLBACK WORK commands.
Documentation
Each BAPI with buffering must be explicitly documented as such.
Activities
Keep in mind the following important information about how write BAPIs with buffering interact with read BAPIs of the same business object.
Write BAPIs with Buffering and Read BAPIs for the Same Business Object
No Buffering for Read BAPIs
If write BAPIs with buffering are implemented for the same business object type, read BAPIs are not allowed to use the buffer for the same business object type, so that data read from the database can be stored, thereby avoiding further database accesses.
As the imported data is not locked, the corresponding data in the buffer would become outdated over time. Subsequent read operations would first access the buffer and read the potentially out-of-date data, as data in the database can only be read, if this data is not in the buffer.
Buffer Instances Are "Real" Instances
All instances created or changed by write BAPIs in the buffer are consistent. They can be used by other change BAPIs for further processing within the same LUW.
To guarantee the consistent behavior, all read BAPIs must handle existing instances that are in the buffer, and not yet in the database, as valid instances. Read BAPIs must be implemented in such a way that they first try to read an instance in the buffer and only start searching the database, if the instance is not found in the buffer.
A buffer instance is therefore "real" instance. For example, a BAPI ExistenceCheck() must search for the existence of an instance in the buffer also.
Documenting Read BAPIs
Each read BAPI that handles the buffering of corresponding write methods must be documented.
Prerequisites
The buffering mechanism for BAPIs must be implicit, that is, the caller must not have to control the buffering. A calling program must be able to use, for example, a Create()or Change() BAPI with buffering as well as it can use a BAPI without buffering. The buffer is updated implicitly in R/3.
If buffering has been implemented for a business object type, all write BAPIs of this business object type must also be implemented with buffering.
If write BAPIs with buffering have been implemented for a business object type, this affects the read BAPIs of this object type. Refer to the information in the Activities section below.
Features
For BAPIs with buffering, in addition to the standard guidelines, the following implementation steps and characteristics described below are required.
Function Modules for Updating the Contents of the Buffer
As BAPIs with buffering can only create or change instances in the buffer, you have to provide one or more function modules to carry out the final update of the buffer contents. These update modules transfer the entire contents of the buffer to the update program.
These function modules should not be implemented as BAPIs, as these are only used in the system in which the buffer is also used.
The naming convention for these function modules is:
_SAVEBUFFER.
Exceptions must not be defined for the update modules, as these are not run until the end of the program, when error handling is no longer possible (see Special Characteristics below).
Function Modules for Deleting the Contents of the Buffer
To ensure that the buffer is empty at the start of a transaction, you must provide a function module that deletes the contents of the buffer. This delete function module deletes the entire contents of the buffer and removes any locks on the instances. Neither should you implement this function module as a BAPI, because it is only used in the system in which the buffer is also used.
The naming convention for this function module is:
_CLEARBUFFER.
No exceptions can be defined for delete modules because these are not run until the end of the transaction, when error handling is no longer possible (see Special Characteristics below).
Special Characteristics
BAPIs with buffering need to have special characteristics. For example, these BAPIs must be able to deal with errors because a caller cannot reprocess data in the buffer. As data is buffered implicitly, no administration BAPIs are provided for callers.
Consistency of the Buffer Contents
A BAPI with buffering must carry out all the processing steps, except for updating. The consistency of all instances created or changed in the buffer must be guaranteed by the application.
This means that:
• Only operations that can be updated with consistency guaranteed can be carried out in the buffer. The update module itself cannot perform consistency checks.
• All other steps required before updating, such as assigning numbers or creating application blocks, must be carried out before calling the update module.
• For operations that cannot be updated consistently, no action can take place. In these cases the error situation must be reported in the BAPI return parameter.
Calling Update Modules
After the buffer operations have been successfully carried out, using the command
PERFORM ON COMMIT
call a form routine which then calls the update module(s).
The update modules must be called using the command
CALL _SAVEBUFFER IN UPDATE TASK
to flag the execution in the update program.
By adding 'ON COMMIT' to the command PERFORM ON COMMIT, updating is not carried out immediately,it is carried out in the next COMMIT WORK. This way any number of BAPI calls can be collected together. The final COMMIT WORK command that is executed via the BAPI BapiService.TransactionCommit(), executes the form routine and also each update module once only. For this reason error handling cannot be performed in this form routine or in the function module.
Subscribing the Delete Module
At the start of each LUW the buffer must be empty. Any instances that may exist in the buffer, which were updated in an earlier LUW, are no longer blocked and may be older than the versions in the database. If this instance is updated again, inconsistencies would result.
At the end of each LUW, the buffer contents must be deleted by calling the delete module. This can only be done by the BAPIs BapiService.TransactionCommit() and BapiService.TransactionRollback(). To supply these BAPIs with the necessary information, BAPIs with buffering must subscribe their delete module for the BAPI BapiService.TransactionCommit() bzw. BapiService.TransactionRollback().
The delete module is subscribed by calling the central function module BUFFER_SUBSCRIBE_FOR_REFRESH, whereby the parameter NAME_OF_DELETEFUNC must contain the name of the delete module.
No COMMIT WORK or ROLLBACK WORK Command
BAPIs with buffering must not execute COMMIT WORK or ROLLBACK WORK commands.
Documentation
Each BAPI with buffering must be explicitly documented as such.
Activities
Keep in mind the following important information about how write BAPIs with buffering interact with read BAPIs of the same business object.
Write BAPIs with Buffering and Read BAPIs for the Same Business Object
No Buffering for Read BAPIs
If write BAPIs with buffering are implemented for the same business object type, read BAPIs are not allowed to use the buffer for the same business object type, so that data read from the database can be stored, thereby avoiding further database accesses.
As the imported data is not locked, the corresponding data in the buffer would become outdated over time. Subsequent read operations would first access the buffer and read the potentially out-of-date data, as data in the database can only be read, if this data is not in the buffer.
Buffer Instances Are "Real" Instances
All instances created or changed by write BAPIs in the buffer are consistent. They can be used by other change BAPIs for further processing within the same LUW.
To guarantee the consistent behavior, all read BAPIs must handle existing instances that are in the buffer, and not yet in the database, as valid instances. Read BAPIs must be implemented in such a way that they first try to read an instance in the buffer and only start searching the database, if the instance is not found in the buffer.
A buffer instance is therefore "real" instance. For example, a BAPI ExistenceCheck() must search for the existence of an instance in the buffer also.
Documenting Read BAPIs
Each read BAPI that handles the buffering of corresponding write methods must be documented.
Use
If a business object type consists of sub-objects, you can implement the following standardized BAPIs to add or remove sub-objects:
Add
Subscribe to:
Posts (Atom)
