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.
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 returned to the application and the FI document is created 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 function correctly.
- Performance load
The interface is used often or it handles large volumes of data. 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:
1. 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
2. IDoc dispatch
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.
3. 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:
Outbound Processing
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 Receivers of BAPIs.
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.
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 levels after 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:
DEQUEUE_ALL releases all locked objects
EDI_DOCUMENT_DEQUEUE_LATER releases individual IDocs whose numbers are transferred to the function module as parameter values.
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 parameters, 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
Segment filtering
Once the IDoc has been created, IDoc segments can be filtered again. This filtering is rarely used for BAPIs.
For more information see the R/3 Implementation Guide under:
Basis
Application Link Enabling
Modeling and Implementing Business Processes
Master Data Distribution
Scope of Data for Distribution
Message Reduction
Field conversion
You can define field conversions for specific receivers in the R/3 Implementation Guide:
Basis
Application Link Enabling
Modeling and Implementing Business Processes
Converting Data Between Sender and Receiver
Standard rules can be specified for field conversions. These are important for converting data fields to exchange information between R/2 and R/3 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 R/3 System, 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.
Basis
Application Link Enabling
Modeling and Implementing Business Processes
Partner Profiles and Time of Processing
Maintain Partner Profile Manually
or: Generate Partner Profiles
This setting is only effective if you process the IDocs in the background.
Inbound Processing
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.
The inbound processing consists of the following steps:
Segment filtering
Field conversion
As with outbound processing, fields can be converted if the field format is different in the receiving and sending systems.
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.
Basis
Application Link Enabling
Modeling and Implementing Business Processes
Master Data Distribution
Converting Data Between Sender and Receiver
Serialization by Object Type
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 or 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.
Mass processing refers to bundling IDocs into packets that are then dispatched and processing in the receiving R/3 System. Only one RFC call is needed to transfer several IDocs. Performance is considerably better if you dispatch optimal packet sizes.
To set mass processing parameters, in ALE Customizing choose: Modeling and Implementing Business Processes ® Partner Profiles and Time of Processing ® Generate Partner Profiles. For a given message type you can define the outbound parameters, packet size and processing mode.
If the processing mode is set to Collect IDocs and transfer, outbound IDocs of the same message type and receiver are sent in a scheduled background job in an appropriately sized IDoc packet. The IDocs can be dispatched in a scheduled background job or in ALE Administration.
Some distribution scenarios cannot support mass processing of inbound IDoc packets. This is especially true if the application sending the IDocs uses the ABAP command CALL TRANSACTION USING. In this case the outbound parameter PACKETSIZE must be set to "1".
You can find a list of function modules for mass processing in ALE Development by choosing IDocs ® Inbound processing ® Function module ® Define attributes. These function modules have input type 0.
For more information about the required settings see the R/3 Implementation Guide.
Basis ® Application Link Enabling (ALE) ® Error Handling.
Error Handling in ALE Outbound Processing
If an error occurs in the ALE layer, the faulty IDoc is saved and a workflow is generated. The ALE administrator can process the error through the workflow.
Error Handling in ALE Inbound Processing
Any errors that occur during ALE processing are handled as follows:
- The processing of the IDoc causing the error is terminated.
- An event is triggered. This event starts an error task (work item):
- The employees responsible will find a work task in their workflow inboxes.
- An error message is displayed when the work task is processed.
- The error is corrected in another window and the IDoc can then be resubmitted for processing.
- If the error cannot be corrected, the IDoc can be marked for deletion.
- Once the IDoc has been successfully posted, an event is triggered that terminates the error task. The work task then disappears from the inbox.
Reposting IDocs with Errors
If the processing of the inbound IDoc resulted in an error (IDoc status 51 - "Application document not posted", or 63 - "Error passing IDoc to application"), you can use the report RBDMANI2 to resubmit the IDoc.
In this program you can select specific errors.
The program can also be scheduled as a periodic job to collect IDocs that could not be posted because of a lock problem:
R/3 Implementationguide,
Basis
Application Link Enabling (ALE),
Modelling and Implementing Business Processes
Partner Profiles and Time of Processing