Understanding BAPI

Understanding BAPI: The most powerful tool in the SAP consultant's kitBy Scott RobinsonNovember 1, 2002, 8:00am PST

SAPR/3 is typical of enterprise platforms in that it forces its users to reconceptualize the way information is used in a company.Integrationanddata transportbecome the keywords, and data ceases to be treasure in the vaultit becomes a living thing, flowing through the company like water.

Think of the pre-ERP universe as a series of small lakes, some connected, some not. Each lake (company) is filled with data. Occasionally, boats venture from the shore to the middle of the lake for some data. Occasionally, one of these boats transfers data from one lake to another.

With the advent of ERP, a canal systemSAP R/3is installed. A vast network of bidirectional waterways takes the place of the lakes. Small, powerful ships and barges populate these waterways, keeping data in constant motion.

For the SAP consultant,IDocsare the barges. And Business Application Programming InterfacesBAPIsare the small, powerful ships that keep these barges of data moving.

First in a seriesThis is the first installment in a series that examines the significance of Business Application Programming Interfaces, how to use them, and their role in designing applications.

Building canals for the clientAn understanding of how SAP changes the structure of a business is the first conceptual step in becoming an effective SAP consultant. A solid knowledge of SAPs data-handling mechanisms, of which BAPI is the most central, is the first practical step.

BAPI is the most powerful tool in the SAP consultants toolkit. Think of a BAPI as a business objectsay, a master record, such as a client profile, or a transactional record, such as an invoice. Its easy to confuse a BAPI with an IDoc (another central SAP data transport feature). The difference is that IDocs are about moving data between systems or modules; BAPIs are about calling data in and out of SAP in the first place.

Their place in SAP and your toolboxSAP R/3 arrives with a bundle of BAPIs ready for your immediate use. There are several hundred of them, in categories such as accounting, human resources, and logistics. They perform a vast array of functions, from creating jobs in SAP to launching IDocs, from posting sales orders to changing passwords, from listing employee benefits to tracking a shipment. They can be used out of the box or modified to create new business objects specific to your clients needs.

BAPI is one of a set of tools at your disposal for interfacing with an SAP R/3 system. Its important to understand its role among them, and to have an idea of what each does in relation to the other.

SAP AssistantThis stand-alone program is, in essence, the toolbox you carry with you as a hands-on SAP consultant. Its contents give you access to SAP R/3s objects. All the information you need for setting up remote function calls from outside SAP is found here. Most importantly, SAP Assistant holds your set of keys to SAPs business objects, allowing you access to whats there, and enabling you to create what you need (seeFigure A).

Figure A

Where BAPI fits in among SAP automation components

Remote Function CallsBAPI is ultimately a mechanism for getting data out of SAP R/3. If a BAPI is a ship pushing a barge (data), the engine of that ship is a Remote Function Call (RFC). An RFC is a function module in a system that is called from some other system. This, of course, covers a great deal of ground. The two systems can both be SAP, or they can be different platforms, or an RFC may be used on the spot in real time by any party making an inquiry of an SAP system from the outside (including you, sitting at your laptop).

How do RFCs relate to BAPIs? An RFC is the means by which the business object represented by a BAPI is implemented. A BAPI is a business object; an RFC is functional code.

The Business Object RepositoryA great deal goes on in the Business Object Repository (BOR), and you must know it well. Its not overstating the case to say that the BOR is the core of SAP. If an SAP R/3 system can be described as the animation of otherwise lifeless data, the BOR describes the living cells of this new body. Cells come in many different types, and thats what the BOR holds: all the different types of data comprising an SAP system of databases.

The BORs contents essentially define the implementing companys business model. The information it holds includes the definitions of all business objects internal to the company, as well as the defining information of all interfaces to other companies.

Another new languageBAPI is, like many aspects of SAP R/3, another new lexicon of concepts, terms, and tools a consultant must absorb to be effective. However, it will rapidly be clear to even a less experienced consultant that these concepts are firmly rooted in the object-oriented methodology that is now every IT professionals stock-in-trade.

It is critical that you, as an SAP consultant, understand the dynamic nature of data handling in an SAP environment, the manner in which this mutates business processes, and most importantly, the way in which BAPI and related tools interface with this new, living database. Once you understand these concepts, the hands-on skills to create applications become simple.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 Addand Removeare 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 Removeto 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 Addas 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 InstancesThe 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 instanceWith 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 EnablingBAPIs 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 commandPERFORMON COMMITcall a form routinewhich then calls the update module(s).The update modules must be called using the commandCALL_SAVEBUFFER IN UPDATE TASKto flag the execution in the update program.

By adding 'ON COMMIT' to the command PERFORMON 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 CommandBAPIs 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 ObjectNo 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 BAPIsEach 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 BufferAs 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 commandPERFORMON COMMITcall a form routinewhich then calls the update module(s).The update modules must be called using the commandCALL_SAVEBUFFER IN UPDATE TASKto flag the execution in the update program.

By adding 'ON COMMIT' to the command PERFORMON 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 ModuleAt 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 ObjectNo 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.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 seeReturn Parameters (Error Handling).



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


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 ParametersThe 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


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_bukrswhere bukrs = bkpf-bukrsand belnr = bkpf-belnrand gjahr = bkpf-gjahr.instead ofselect single * from bkpfwhere bukrs = bkpf-bukrsand belnr = bkpf-belnrand 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).


You can create extension parameters to enable customers to enhance the functionalityof BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs.Avoiding Incompatibilities with Customizing SettingsIt 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 AssignmentFor 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 ParametersTo 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 parametersYou 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 SettingsIt 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 ParametersThe 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).



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() BAPIsUseThe 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 deletedThe 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.LockingWe recommend that you implement Cancel() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.

Addand RemoveThe BAPI Addadds a sub-object to an existing object instance and the BAPI and Removeremoves a sub-object from an object instance. These BAPIs are instance methods.

http://careerabap.blogspot.in/2010/12/real-time-example-on-using-bapi.htmlBAPI Step by Step ExampleWritten by Henrik Frank See our ABAP Tips and Tricks DatabaseContributed byHenrik Frank1. About the Example2. STEP 1 - Define a structures for the BAPI3. STEP 2 - Write Function Module4. STEP 3 - Create the API Method Using the BAPI WIZARD5. STEP 4 - Final stepsAbout the exampleThis BAPI reads system status for a production order from table JEST and system status text from table TJ02TNameZGetOrderStatus

Function groupZBAPISTATUS

Function module:Z_BAPI_GET_ORDER_STATUS

Import parameters:ORDER_STATUS_IMPORT type ZBAPI_ORDER_STATUS_IMPORT: AUFNROrder number (Keyfield) SPRASLanguage ExcludeInactive- Checkbox - Exclude inactive status

TablesT_BAPISTAT type ZBAPISTAT: OBJNRlike JEST-OBJNR STATlike JEST-STAT INACTlike JEST-INACT TXT04like TJ02T-TXT04 TXT30likeTJ02T-TXT30

Export parametersRETURNlike BAPIRETURN

STEP 1 - DEFINE A STRUCTURES FOR THE BAPIIn this step a structures for the parameters and tables of the function module used for the BAPI are defined.UseData type -> StructureDefine the following structures:ZBAPI_ORDER_STATUS_IMPORT which contains the following fields: ORDERID Order number (Keyfield) SPRAS Language ExcludeInactive - Checkbox - Exclude inactive statusZBAPISTAT:OBJNR like JEST-OBJNR STAT like JEST-STAT INACT like JEST-INACT TXT04 like TJ02T-TXT04 TXT30 likeTJ02T-TXT30Important note:You will have to define a structure foreveryparameter in the BAPI. You cannot use the same structures used in existing applications because BAPI structures are frozen when BAPIs are released and then there are restrictions on changing them.ZBAPI_ORDER_STATUS_IMPORTZBAPISTAT

STEP 2 - WRITE FUNCTION MODULEImportant notes: Each BAPI must have its own function group. Under the attributes tab remember to select Processing TypeRemote Enabled module, otherwise the function module cannot be invoked via RFC and used as a BAPI Import/Export parameters can only be BY VALUE for an RFC enabled function module We are only creating one BAPI in this example, but you can create related BAPIs in the same function pool, so they will be able to share global data.AttributesImport Parameters

Export ParametersTablesCodeNotes: The subroutine SET_RETURN_MESSAGE is a standard routine used for BAPIs that use the BAPIRETURN structure In form Z_BAPI_GET_ORDER_SYSTEM_STATUS there is a testIF 1 = 2. If the test is true a message is displayed. The condition will obviously never be true, and we will never want to display a message in a BAPI. The reason why it is included is, that it create a reference for the message, so that the WHERE USED functionality can be used for the message. This is the SAP standard way to handle it, copied from the Company Code GetList BAPI.INCLUDE LZBAPISTATUSUXX************************************************* THIS FILE IS GENERATED BY THE FUNCTION LIBRARY.** NEVER CHANGE IT MANUALLY, PLEASE! ***************************************************INCLUDE LZBAPISTATUSU02. "Z_BAPI_GET_ORDER_SYSTEM_STATUSINCLUDE LZBAPISTATUSTOP - Global dataFUNCTION-POOL ZBAPISTATUS. "MESSAGE-ID Z3Types: begin of Type_tj02t, istat like tj02t-istat, txt04 like tj02t-txt04, txt30 like tj02t-txt30, end of type_tj02t.DATA:* Declarations for TABLE parameter T_BAPISTAT like ZBAPISTAT occurs 0, G_BAPISTAT like ZBAPISTAT,* Table for object texts t_tj02t type type_tj02t occurs 0, g_tj02t type type_tj02t.* Structure for return messagesDATA: BEGIN OF MESSAGE, MSGTY LIKE SY-MSGTY, MSGID LIKE SY-MSGID, MSGNO LIKE SY-MSGNO, MSGV1 LIKE SY-MSGV1, MSGV2 LIKE SY-MSGV2, MSGV3 LIKE SY-MSGV3, MSGV4 LIKE SY-MSGV4, END OF MESSAGE.INCLUDE LZBAPISTATUSF01 - Subroutines***INCLUDE LZBAPISTATUSF01 .*----------------------------------------------------------------------**&---------------------------------------------------------------------**& Form SET_RETURN_MESSAGE*&---------------------------------------------------------------------** This routine is used for setting the BAPI return message.* The routine is a standard routine for BAPIs that handles the message* structure for the BAPIRETURN structure. It has been copied from the* BAPI Company Code Getlist*----------------------------------------------------------------------** -->P_MESSAGE text* P_V_SPONO text*----------------------------------------------------------------------*FORM f_pdf_conversion TABLES it_compressed_list structure soli it_pdf_list structure tline using lv_spooln type tsp01-rqident.

clear: it_compressed_list, it_pdf_list.refresh: it_compressed_list, it_pdf_list.

*-- Call the FM "RSPO_RETURN_SPOOLJOB" to read the spool by passing the spool number call function 'RSPO_RETURN_SPOOLJOB' exporting rqident = lv_spooln desired_type = v_type importing real_type = v_type tables buffer = it_compressed_list buffer_pdf = it_pdf_list exceptions no_such_job = 1 job_contains_no_data = 2 selection_empty = 3 no_permission = 4 can_not_access = 5 read_error = 6 type_no_match = 7 others = 8. if sy-subrc 0. message I000 with 'Error in spool reading'(017). endif.

*-- If the List type is ALI call the FM "CONVERT_ABAPSPOOLJOB_2_PDF"* to convert list into PDF Format if v_type = c_ali. " for List it is ALI call function 'CONVERT_ABAPSPOOLJOB_2_PDF' exporting src_spoolid = lv_spooln tables pdf = it_pdf exceptions err_no_abap_spooljob = 1 err_no_spooljob = 2 err_no_permission = 3 err_conv_not_possible = 4 err_bad_destdevice = 5 user_cancelled = 6 err_spoolerror = 7 err_temseerror = 8 err_btcjob_open_failed = 9 err_btcjob_submit_failed = 10 err_btcjob_close_failed = 11 others = 12. if sy-subrc 0. message e000 with'Error in convertion of list into PDF format'(018). endif.

*-- Logic to convert the given format into 255 character format in IT_PDF describe table it_pdf lines v_lines. describe field it_pdf length v_lineslen IN character MODE. describe field it_temp length v_mimelen IN character MODE. LOOP AT it_pdf. v_tabix = sy-tabix. MOVE it_pdf TO v_temp+v_offset. IF v_tabix = v_lines. v_lineslen = strlen( it_pdf ). ENDIF.

v_offset = v_offset + v_lineslen. IF v_offset GE v_mimelen. CLEAR it_temp. it_temp = v_temp(v_mimelen). APPEND it_temp. SHIFT v_temp BY v_mimelen PLACES. v_offset = v_offset - v_mimelen. ENDIF.

IF v_tabix = v_lines. IF v_offset GT 0. CLEAR it_temp. it_temp = v_temp(v_offset). APPEND it_temp. ENDIF. ENDIF. ENDLOOP.

LOOP AT it_temp. it_mime(255) = it_temp-line. APPEND it_mime. ENDLOOP.

*-- Final Data to send to EMail it_html[] = it_mime[]. endif.

ENDFORM. " f_pdf_conversion

*&---------------------------------------------------------------------**& Form f_send_mail*&---------------------------------------------------------------------** Send EMail Logic*----------------------------------------------------------------------*FORM f_send_mail .

data : wa_tsp01sys type tsp01sys.

*-- Populate Mail Id's WA_RECLIST-REC_TYPE = P_MODE. WA_RECLIST-EXPRESS = C_X.

*-- Loop through the Emial select options LOOP AT S_EMAIL INTO X_EMAIL. WA_RECLIST-RECEIVER = X_EMAIL-LOW.*-- append receiver table APPEND WA_RECLIST TO IT_RECLIST. ENDLOOP.

*-- If receiver table is not initial CHECK IT_RECLIST[] IS NOT INITIAL.*--To check Mail ID's internal table should not be Empty.*--populate document attributes

*-- Mail subject line CLEAR: X_DOC_CHNG. X_DOC_CHNG-OBJ_NAME = 'HEADING'. CONCATENATE 'Automatic Vendor Dedit Postings'(005) SY-DATUM INTO X_DOC_CHNG-OBJ_DESCR SEPARATED BY SPACE.

*-- Mail body CONCATENATE 'Automatic Vendor Dedit Postings'(005) ' is attached.'(006) INTO WA_OBJTXT SEPARATED BY SPACE. APPEND WA_OBJTXT TO IT_OBJTXT.

*-- Append Date and Time into Body of email. MOVE 'File is generated on'(007) TO V_INFO. V_TIME = SY-UZEIT. CONCATENATE V_TIME+0(2) V_TIME+2(2) V_TIME+4(2) INTO V_TIME2 SEPARATED BY ':'. CONCATENATE SY-DATUM+4(2) '/' SY-DATUM+6(2) '/' SY-DATUM+0(4) INTO V_DATE2. CONCATENATE V_INFO V_DATE2 'At' V_TIME2 INTO V_INFO SEPARATED BY SPACE. WA_OBJTXT = V_INFO. APPEND WA_OBJTXT TO IT_OBJTXT.

*-- Document size CLEAR : V_TABLE_LINES. DESCRIBE TABLE IT_OBJTXT LINES V_TABLE_LINES. READ TABLE IT_OBJTXT INTO WA_OBJTXT INDEX V_TABLE_LINES . X_DOC_CHNG-DOC_SIZE = ( V_TABLE_LINES - 1 ) * 255 + STRLEN( WA_OBJTXT ).

*-- Populate packing list for body text WA_OBJPACK-HEAD_START = 1. WA_OBJPACK-HEAD_NUM = 0. WA_OBJPACK-BODY_START = 1. WA_OBJPACK-BODY_NUM = V_TABLE_LINES. WA_OBJPACK-DOC_TYPE = 'RAW'. APPEND WA_OBJPACK TO IT_OBJPACK. CLEAR WA_OBJPACK.

if v_type = c_ali. loop at it_html. wa_objbin-line = it_html-line. APPEND WA_OBJBIN TO IT_OBJBIN. CLEAR WA_OBJBIN. endloop. v_type = 'PDF'. endif.

*-- Get total no.of lines of Object table(attachment) CLEAR : V_TABLE_LINES. DESCRIBE TABLE IT_OBJBIN LINES V_TABLE_LINES.

*-- Populate object header(attachment name) WA_OBJHEAD = 'Automatic Vendor Dedit Postings log'(014). APPEND WA_OBJHEAD TO IT_OBJHEAD. CLEAR WA_OBJHEAD.

*-- Packing list for attachment WA_OBJPACK-TRANSF_BIN = C_X. WA_OBJPACK-HEAD_START = 1. WA_OBJPACK-HEAD_NUM = 1. WA_OBJPACK-BODY_START = 1. WA_OBJPACK-BODY_NUM = V_TABLE_LINES . WA_OBJPACK-DOC_TYPE = v_type .

WA_OBJPACK-OBJ_NAME = 'Auto_Debit'. WA_OBJPACK-OBJ_DESCR = 'attachment'. WA_OBJPACK-DOC_SIZE = V_TABLE_LINES * 255. APPEND WA_OBJPACK TO IT_OBJPACK. CLEAR WA_OBJPACK.

*-- Sending the EMail document in given format CALL FUNCTION 'SO_NEW_DOCUMENT_ATT_SEND_API1' EXPORTING DOCUMENT_DATA = X_DOC_CHNG PUT_IN_OUTBOX = C_X COMMIT_WORK = C_X TABLES PACKING_LIST = IT_OBJPACK OBJECT_HEADER = IT_OBJHEAD CONTENTS_BIN = IT_OBJBIN CONTENTS_TXT = IT_OBJTXT RECEIVERS = IT_RECLIST EXCEPTIONS TOO_MANY_RECEIVERS = 1 DOCUMENT_NOT_SENT = 2 DOCUMENT_TYPE_NOT_EXIST = 3 OPERATION_NO_AUTHORIZATION = 4 PARAMETER_ERROR = 5 X_ERROR = 6 ENQUEUE_ERROR = 7 OTHERS = 8.

IF SY-SUBRC 0. MESSAGE E000 WITH 'Error occurred in sending mail'(015). ELSE.*-- Wait upto 2 secounds wait up to 2 seconds.

*-- Call the RSCONN01 (SAPconnect: Start Send Process) SUBMIT RSCONN01 WITH MODE = 'INT'* WITH output = 'X' AND RETURN.

PERFORM F_DISPLAY_SENT_MAIL_STATUS. ENDIF.

* To delete the spool request wa_tsp01sys-rqident = sy-spono. call function 'RSPO_IDELETE_SPOOLREQ' exporting spoolreq = wa_tsp01sys. if sy-subrc 0. endif.

ENDFORM. " f_send_mail

*&---------------------------------------------------------------------**& Form F_DISPLAY_SENT_MAIL_STATUS*&---------------------------------------------------------------------** Display Mail Sent status to the user*----------------------------------------------------------------------*FORM F_DISPLAY_SENT_MAIL_STATUS .

ULINE AT /1(60). WRITE :/ SY-VLINE, 'Mail sent Successfully to'(016) COLOR 5 INTENSIFIED ON, 60 SY-VLINE.

LOOP AT S_EMAIL INTO X_EMAIL. V_TABLE_LINES = STRLEN( X_EMAIL-LOW ). MOVE X_EMAIL-LOW+0(V_TABLE_LINES) TO V_TEXT2.

WRITE :/ SY-VLINE, 2 SY-TABIX LEFT-JUSTIFIED, 5 ')', V_TEXT2, 60 SY-VLINE. ENDLOOP.

ULINE AT /1(60).

ENDFORM. " F_DISPLAY_SENT_MAIL_STATUS

Documents

Understanding BAPI