Distribution Using BAPIs

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

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 more information see the R/3 Implementation Guide under:

IDoc Interface/Application Link Enabling
    Modeling and Implementing Business Processes
    Configure Master Data Distribution
          Specify Scope of Data for Distribution
                Message Reduction

Field conversion

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.

IDoc Interface/Application Link Enabling
    Modeling and Implementing Business Processes
          Partner Profiles  
                Generate partner profiles


(or: TransactionWE20 – 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.

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.

 
IDoc Interface/Application Link Enabling
      Modeling and Implementing Business Processes
            Configure Master Data Distribution
                  Converting Data Between Sender and Receiver
                        Serializing by Business Object

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.