Wrapper collaboration template

IBM WebSphere Business Integration Server Express Plus collaboration templates synchronize business objects across applications in an enterprise system. In their processing, collaboration often synchronize or verify business objects associated with their own triggering business object.

For example, the CustomerSync collaboration is triggered when a source application or another IBM WebSphere Business Integration Server Express Plus collaboration sends the generic Customer business object to it. In addition to synchronizing the primary customer data, CustomerSync may be configured to verify or synchronize related customer data, such as Billing and Shipping addresses, using the generic CustomerPartner business object.

Because it is common for IBM WebSphere Business Integration Server Express Plus collaboration templates to verify or synchronize business objects associated with their triggering business object, IBM has isolated the processing logic for verifying and synchronizing such associated business objects into separate, intermediate collaboration.

These intermediate collaborations are never triggered directly by an application connector. Instead, they subscribe to a specific business object that their calling collaboration sends with either a Sync or an Exists verb. The calling collaboration references the associated business object through a foreign key stored in its triggering business object. Therefore, the intermediate collaboration receives its triggering business object with values only in the key attributes.

The intermediate collaborations are designed to perform one of two operations:

Because the calling collaboration delegates the synchronization of a business object to the intermediate collaboration, which calls the appropriate synchronization collaboration, these intermediate collaborations are said to wrap the synchronization collaboration. Therefore, the intermediate collaborations are called Wrappers. They are named specifically for the type of business object that triggers them (for example, CustomerPartnerWrapper collaboration, CustomerWrapper collaboration, and ItemWrapper collaboration). Because the logic is identical for each BusinessObjectWrapper collaboration, this reference page serves as their common documentation.

Collaboration object setup

This section includes information on port bindings and required steps for setting up collaboration objects based on Wrapper. For information on standard features, ports, and configuration properties for collaboration templates, and for general information on creating collaboration objects refer to the documents listed in the Collaboration Development Guide.

Port information

Figure 1 illustrates CustomerWrapper's ports, as they are displayed in System Manager. Other wrapper collaborations use the same ports, but with different business objects.

Figure 1. BusinessObjectWrapper collaboration ports

Note: To prevent the collaboration object from using a port, bind that port to the Port connector. Binding the port indicates that the port is unused without causing the collaboration object to provide additional functionality.

Port name: DestinationAppRetrieve
Business object Bound to Function Verbs used
Business object for which the BusinessObjectWrapper is named. For example, CustomerPartnerWrapper sends a reference-valued CustomerPartner business object. A connector Used to retrieve the wrapper collaboration's business object from the destination application

Retrieve


Port name: To
Business object Bound to Function Verbs used
Business object for which the BusinessObjectWrapper is named. For example, CustomerPartnerWrapper sends a reference-valued CustomerPartner business object. Triggering port of another collaboration Used to send the wrapper collaboration's business object

Create


Port name: SourceApp
Business object Bound to Function Verbs used
Business object for which the BusinessObjectWrapper is named. For example, CustomerPartnerWrapper is triggered by a CustomerPartner business object. A connector

Used to retrieve the triggering business object from the source application

Retrieve


Port name: From
Business object Bound to Function Verbs used
Business object for which the BusinessObjectWrapper is named. For example, CustomerPartnerWrapper is triggered by a CustomerPartner business object.

A calling collaboration

Used to receive the triggering business object

Sync Exists

Collaboration template processes

This section describes the Synchronization and Verification processes.

Synchronization process

Figure 2 illustrates BusinessObjectWrapper's synchronization process.

Figure 2. BusinessObjectWrapper collaboration synchronization process

When BusinessObjectWrapper receives its triggering business object with the Sync verb, it sends the business object to the source application with the Retrieve verb.

If the Retrieve operation is successful, BusinessObjectWrapper sends the returned business object with the Create verb to its associated synchronization collaboration. For example, ItemWrapper sends the Item business object to the ItemManager collaboration.

If the Retrieve operation is unsuccessful, BusinessObjectWrapper returns a status of failure to the calling collaborations and logs error #4.

Notes:

Verification process

Figure 3 illustrates BusinessObjectWrapper's verification process.

Figure 3: BusinessObjectWrapper collaboration verification process

When BusinessObjectWrapper receives its triggering business object with the Exists verb, it sends the business object to the destination application with the Retrieve verb.

If the Retrieve operation is successful, BusinessObjectWrapper returns a success status to its calling collaboration. If the Retrieve operation is unsuccessful, BusinessObjectWrapper evaluates the setting of its CONTINUE_WITH_WARNING property.

Note: For details on the messages for BusinessObjectWrapper, refer to the following collaboration message file: \collaborations\messages\BusinessObjectWrapper.txt.

Configuration properties

Property name and explanation Possible values Default value

CONTINUE_WITH_WARNING

Set to true to cause BusinessObjectWrapper to issue a warning instead of failing the event when either:

  • The wrapper collaboration has failed to verify the business object in the destination application or
  • The synchronization collaboration has failed to synchronize the business object that it had received from the wrapper collaboration with the Create verb.

BusinessObjectWrapper returns a status of success to the calling collaboration. If the trace level has been set to 3 or higher, BusinessObjectWrapper issues warning messages.

Set to false to cause the collaboration to log error messages and return a status of failure to the calling collaboration.

true, false false

Collaboration messages

Note: Messages that provide information appear at the trace destination only if the trace level has been set to 3 or higher.

To view an explanation of the messages of this collaboration template, launch the Log Viewer and open the collaboration template's message file. To launch the Log Viewer and open the collaboration template's message file:

  1. In the Start menu, click Programs > IBM WebSphere Business Integration Express > Toolset Express > Administrative > Log Viewer.
  2. In the File menu, click Open.
  3. Use the Look In field to change the current folder to ProductDir\collaborations\messages, and then select the message file for this collaboration template.

Copyright IBM Corp. 1997, 2004