Programming Replicate()/SaveReplica() BAPIs

Use

To replicate a business object instance, for example, to transfer data between two distributed systems in the context of Application Link Enabling (ALE), you can implement specific standardized BAPIs.

The objective of replicating business object types is to make specific instances of an object type available on one or more additional systems. The replicated instances are usually created under the same object key.

The interface of these BAPIs depends on the characteristics and contents of the business object that is to be replicated. For this reason replicate BAPIs must be implemented for each business object.

Business objects instances can be replicated in two ways:

  • Upon request ("Pull)
    System "A" requests replicates from system "B". Then system "B" replicates the requested business object instances on system "A".
  • Via subscription list ("Push")
    In this approach system "B" maintains a list of systems requiring replicates. At regular intervals, system "B" replicates the business object instances to all the systems in the list.

Both of the above replication methods can be implemented with the BAPIs Replicate(), SaveReplica() and SaveReplicaMultiple(). These BAPIs are both class methods (instance-independent).

Features

Replicate()

The BAPI Replicate() is called in the system which contains the originals of the business object instances to be replicated. The BAPI Replicate() is used for:

  • Identifying the business object instances to be replicated and to organize the required data
  • Calling the SaveReplica() methods in the receiving system

The BAPI Replicate() can only request the replication of instances of a business object. The actual replication is carried out when the server system calls one of the SaveReplica() BAPIs described below on the client system.

You must follow the steps below:

  1. Select the data to be replicated.
  1. Determine the receiver.

This is done in the ALE distribution model using the function module ALE_SYNC_BAPI_GET_RECEIVER. For information about this function module, see the Section Distribution Using BAPIs in the ALE Programming Guide. You can also restrict the number of receivers in the parameter Recipients of the Replicate() BAPI.

  1. Loop via the receiver and call the relevant SaveReplica() BAPI.
  1. Enter a value in the Return parameter and complete the Replicate() BAPI.

Import Parameters

The interface of the Replicate() BAPI must contain the following parameters:

  • Parameters which identify the business object instances to be replicated

You could implement these, for example, using a range table for the key fields of the business object types or using selection parameters that enable you to select instances to be replicated. (See also Selection Parameters).

  • Parameter Recipients

This parameter identifies the logical systems in which the business object instances are to be replicated. This parameter is based on the data element BAPILOGSYS. If this parameter is set to "initial", the receiver is determined using the ALE distribution model.

  • If customers are to be enabled to enhance the import parameters of the BAPI without modifications being necessary, you must create the parameter ExtensionIn.

For information about extension parameters and recommendations on how the customer enhancement concept should be implemented in a Replicate() BAPI, see Customer Enhancements to BAPIs.

The interface of the Replicate() BAPI can also contain the following parameters:

  • Parameter RequestChanges

This parameter enables modifications of object instances already replicated to be copied directly from engineering change management and forwarded to the receiving system. You should only use this parameter if the business object type in question provides engineering change management.

Structure this parameter on the data element RQSTCHNG. This can have the following values:

    • ‘ ‘ (no value):
      No value is the standard setting and means that engineering change management will not be accessed.
    • ‘X’:
      This value means that the modified data is replicated directly from engineering change management.

The parameter RequestChanges must not be used together with the Recipients parameter, because the change pointers in change management are reset, if the receiver accesses change management. Other receivers may then not be allowed access. Documentation on this parameter must refer explicitly to this connectivity.

  • Other BAPI-specific import parameters, for example to specify the data range of the instances to be replicated (for example, material with or without plant data).

Export Parameters

The BAPI Replicate() should contain the following export parameters:

  • The Return parameter in which messages from the method call are returned to the calling program.

For more information about this parameter, see Return Parameters (Error Handling).

  • A table containing information on the object instances to be replicated.
  • If customers are to be allowed to extend the export parameters of the BAPI without modifications being necessary, you must create the parameter ExtensionOut.

For information about extension parameters and recommendations on how the customer enhancement concept should be implemented in a Replicate() BAPI, see Customer Enhancements to BAPIs.

SaveReplica() and SaveReplicaMultiple()

The class method SaveReplica() and the method SaveReplicaMultiple() generate replicates of business object instances. They are used to replicate objects in different systems that are semantically identical. For technical reasons these objects may be created with different objects keys (object IDs).

The BAPI SaveReplica() is used by a system to replicate one business object instance on a target system or to modify one business object that has already been replicated. Whilst the SaveReplicaMultiple() BAPI can replicate several business object instances on the target system or modify several instances that have already been replicated.

For each business object type to be replicated you have to implement one or both of these methods, according to your requirements.

Import Parameters

You should keep the following points in mind when defining the import parameters:

  • For the SaveReplica() BAPI, all the data required for replicating an individual business object instance must be provided in the import parameters. For the SaveReplicaMultiple() BAPI, all the relevant data for replicating several instances must be provided in the import parameters. All business object information may be provided, it must, however, be able to be derived. Since these are class methods, none of the BOR key fields may be a parameter in the function module or of the BAPI.
  • If only parts of objects are to be replicated rather than whole objects, you can use other optional import parameters.
  • If instances that have already been replicated are to be changed when a SaveReplica() or SaveReplicaMultiple() BAPI is called, the fields that are to be changed (that is, receive new values) and the fields that are to remain the same must be identified. You can do this by flagging the fields, as described in Change Parameters.
  • The BAPI must also have a TestRun parameter that enables it to execute test runs. If this parameter contains the value "X", the BAPI executes normally, but does not write the results to the update task. In this way, after the BAPI BapiService.TransactionCommit executes, all results can be evaluated, (such as the application log, for example), but the BAPI has not modified the database.

For more information, see Test Run Parameters.

Export Parameters

You should keep the following points in mind when defining the export parameters:

  • If customers are to be allowed to extend the export parameters of the BAPI without modifications being necessary, you must create the parameter ExtensionOut.

For information about extension parameters and recommendations on how the customer enhancement concept should be implemented in a SaveReplica() BAPI, see Customer Enhancements to BAPIs.

  • To report messages from the method call back to the calling program, you should create the parameter Return. To ensure the results of a SaveReplica() BAPI, called either synchronously or asynchronously, are monitored extensively, the following conventions for filling the Return parameter must be observed:
    • If the SaveReplica() BAPI executes successfully, the following standardized T100 message must be passed in the Return parameter:

You should keep the following points in mind:

      • The field MESSAGE_V1 contains the external name of the business object type, such as SalesOrder.
      • The information identifying the replicated object is returned in MESSAGE_V2.

If this information exceeds the maximum capacity of MESSAGE_V2 (that is, 50 characters), the remaining characters can be entered in the field MESSAGE_V3.

    • If an error occurs during the execution of the SaveReplica() BAPI, in addition to the application-specific error messages the following standardized message must be passed in the Return parameter:

The meaning of the various fields is the same as for successful execution.

    • In addition to the standardized message, further messages can be written in the Return parameter. It is of particular importance when errors occur that messages describing the errors in detail are returned. You should, therefore, use all of the fields of the structure BAPIRET2. You should, in particular, fill the fields Parameter, Row and Field.

For more information about this parameter, see Return Parameters (Error Handling).

See also:

Example of a SaveReplica() BAPI