BAPIs can be called by applications synchronously or asynchronously. ALE functions such as BAPI maintenance in the distribution model and receiver determination can be used for both types of call.
Note that synchronously-called BAPIs are only used for reading external data to avoid database inconsistencies arising from communication errors.
Example
The application synchronously calls a BAPI in the external system to create an FI document. The document is correctly created but the network crashes whilst the BAPI is being executed. An error message is reported to the application asking you to create the FI document again. The document has been duplicated in the system called.
An application program can implement a two-phase commit by thoroughly checking the data in the external system. An easier solution is to call the BAPI asynchronously, as Error Handling assures that the data remains consistent.
A BAPI should be implemented as an asynchronous interface, if one of the criteria below applies:
Consistent database changes in both systems
Data must be updated in the local system as well as on a remote system
Loose coupling
An asynchronous interface would represent too narrow a coupling between the client and the server systems. If the connection fails the client system can no longer operate properly.
Performance load
If the interface is used often or handles large volumes of data, a synchronous interface cannot be used because performance would be low. A synchronous interface cannot be used in this situation because performance would be too low.
If you want to implement a BAPI as an asynchronous interface, you have to generate a BAPI-ALE interface for an existing BAPI. For more information see Generating BAPI-ALE Interfaces.
Data distribution using BAPIs is illustrated in the graphic below:
The processes in the application layer and the ALE layer are completed on both the inbound and outbound processing sides. The communication layer transfers the data by transactional Remote Function Call (tRFC) or by EDI file interface.
The process can be divided into the following sub-processes:
Outbound Processing
Receiver Determination
Calling the Generated Outbound Function Module
Conversion of BAPI Call into IDoc
Segment Filtering
Field Conversion
IDoc Version Change
Dispatch Control
Dispatching the IDoc
IDocs are sent in the communication layer by transactional Remote Function Call (tRFC) or by other file interfaces (for example, EDI).
tRFC guarantees that the data is transferred once only.
Inbound Processing
Segment Filtering
Field Conversion
Transfer Control
Conversion of IDoc into BAPI Call
BAPI Function Module Call
Determination of IDoc status
Posting of Application Data and IDoc Status
Error Handling
The sub-processes in inbound and outbound processing are described below:
On the outbound side first of all the receiver is determined from the distribution model. Then the outbound function module that has been generated from a BAPI as part of the BAPI-ALE interface is called in the application layer (see also Example Programs with Asynchronous BAPI Calls). In the ALE layer the associated IDoc is filled with the filtered data from the BAPI call.
The volume of data and time of the data transfer is controlled by the dispatch control.
The outbound processing consists of the following steps:
Receiver Determination
The receivers of a BAPI call are defined in the distribution model in same way as with synchronous BAPI calls.
Before the BAPI or generated BAPI-ALE interface can be called, the receiver must be determined. When the receiver is determined, the filter objects are checked against the specified conditions and the valid receivers are reported back.
If the distribution of the data is also dependent on conditions, these dependencies between BAPIs or between BAPIs and message types are defined as receiver filters.
For each of these receiver filters, before the distribution model is defined, a filter object is created whose value at runtimes determines whether the condition is satisfied or not.
For more information see Determining the Receiver of a BAPI.
Calling the Generated Outbound Function Module
If the receivers have been determined, you have to differentiate between local and remote receivers. The BAPI can be called directly for local receivers. For remote calls the generated ALE outbound function module must be executed so that processing is passed to the ALE layer. The data for the BAPI call and the list of allowed logical receiver systems are passed to this function module.
Note
Programming Notes:
After calling the generated function module the application program must contain the command COMMIT WORK. The standard database COMMIT at the end of the transaction is not sufficient. The COMMIT WORK must not be executed immediately after the call, it can be executed at higher call level safter the function module has been called several times.
The IDocs created are locked until the transaction has been completed. To unlock them earlier, you can call the following function modules:
EDI_DOCUMENT_DEQUEUE_LATER releases individual IDocs whose numbers are transferred to the function module as parameter values.
DEQUEUE_ALL releases all locked objects
Caution
The dequeue_all
function module can only be used if the application cannot be used in the Workflow environment, since this function module deletes locks required by work items.
Data Filtering
Two filtering services can be used - parameter filtering with conditions and unconditional interface reduction.
If entire parameters have been deactivated for the interface reduction, they are not included in the IDoc. If, on the other hand, only individual fields are not to be included for structured paramers, the entire parameters are still included in the IDoc.
With parameter filtering, table rows that have been filtered out are not included in the IDoc.
For more information, see Filtering Data.
Conversion of BAPI Call into IDoc
Once the data has been filtered, an IDoc containing the data to be transferred, is created from the BAPI call by the outbound function module
Segment Filtering
Once the IDoc has been created, IDoc segments can be filtered again. This filtering is rarely used for BAPIs.
For details, from the SAP IMG screen choose:
.
Field Conversion
You can define field conversions for specific receivers in the IMG:
.
Standard rules can be specified for field conversions. This function is especially important for converting the field format during data exchange between R/2 systems and more recent SAP systems. For example, the field plant can be converted from a two character field to a four character field.
Standard Executive Information System (EIS) tools are used to convert fields.
IDoc Version Change
To guarantee that ALE works correctly between different releases of the SAP systems, IDoc formats can be converted to modify message types to suit different release statuses.
If version change has been completed, the IDocs are stored in the database and the dispatch control is started which decides which of these IDocs are sent immediately.
SAP uses the following rules to convert existing message types:
Fields can be appended to a segment type
New segments can be added
ALE Customizing records the version of each message type used in each receiver. The IDoc is created in the correct version in outbound processing.
Dispatch Control
Scheduling the dispatch time:
IDocs can either be sent immediately or in the background. This setting is made in the partner profile.
If the IDoc is sent in the background, a job has to be scheduled. You can choose how often background jobs are scheduled.
Controlling the amount of data sent:
IDocs can be dispatched in packets. The packet size is assigned in ALE Customizing in accordance with the partner profile.
.
Note
This setting is only effective if you process the IDocs in the background.
On the receiver side the ALE layer continues with the inbound processing.
On the application side when the generated inbound function module is executed, the BAPI call is generated from the IDoc, the BAPI function module is called and the IDoc status is determined.
After the BAPI or the entire packet has been processed, the IDoc status records of all IDocs and the application data created from successfully completed BAPIs, are posted together.
The inbound processing consists of the following steps:
Segment Filtering
On the inbound side IDoc segments can be filtered the same as they can on the outbound side. This filtering on the inbound side is also rarely used for BAPIs.
Field Conversion
As with outbound processing, fields can be converted if the field format is different in the receiving and sending systems.
After the fields have been converted, the IDoc is saved on the database and it is passed to the transfer control for further processing.
Transfer Control
The transfer control decides when the application BAPIs are to be called. This may be either immediately when the IDoc arrives or at a later time in background processing.
If several mutually dependent objects are distributed, serialization can be used during the transfer control. IDocs can be created, sent and posted in a specified order by distributing message types serially. Errors can then be avoided when processing inbound IDocs. If BAPIs are used object serialization is used exclusively. This assures that the message sequence of a particular object is always protected.
For more information about used object serialization see ALE Customizing.
.
When the time arrives for processing the BAPI, the generated inbound function module is called.
Conversion of IDoc into BAPI Call
When the BAPI is called, the entire data from the IDoc segments is written to the associated parameters of the BAPI function module. If an interface reduction has been defined for the BAPI, the hidden fields are not filled with the IDoc data.
BAPI Function Module Call
Next the BAPI function module with the filled parameters is executed synchronously. As the BAPI does not execute a COMMIT WORK command, the application data that it has created, modified ot deleted is not yet saved in the database.
IDoc Status Determination
If the function module has been executed, the IDoc status is determined in the inbound function module from the result of the call.
Posting of Application Data and IDoc Status
If each IDoc or BAPI is processed individually, the data is written immediately to the database.
If several IDocs are processed within one packet, the following may happen:
The application data of the successfully completed BAPI together with all the IDoc status records is updated, provided that no BAPI call has been terminated within the packet.
As soon as a BAPI call is terminated within the packet, the status of the associated IDoc will indicate an error. Application data will not be updated. Then inbound processing is run again for all the BAPI calls that had been completed successfully. Provided that there is no termination during this run, the application data of BAPIs and all the IDoc status records are updated. This process is repeated if there are further terminations.
Note
Packet processing is only carried out if there is no serialization.
Error Handling
You can use SAP Workflow for ALE error handling:
The processing of the IDoc or BAPI data causing the error is terminated.
An event is triggered. This event starts an error task (work item).
Once the data of the BAPI or IDoc has been successfully updated, an event is triggered that terminates the error task. The work task then disappears from the inbound system.
For more information see Error Handling.