ContractSync Collaboration Template

Contract information is typically duplicated in systems that support different business functions or different businesses, such as Order Entry, Planning, Finance, and Support. Because Contract information may be distributed across multiple systems, maintaining integrity and ensuring that all systems are synchronized is a key business challenge.

The ContractSync collaboration template, in conjunction with other objects and collaborations, specifies a common process for maintaining and synchronizing Contract information across all systems that use it. This synchronization enables a common view of Contract information throughout the organization.

The Contract Manager collaboration-object group synchronizes Contract information between a Customer Interaction Management (CIM) application and an Enterprise Resource Planning (ERP) application. Either of these applications can serve as the source or destination for the synchronized information.

This replication of data allows separate applications to use information consistently whenever data is added, changed, or deleted in the enterprise. The collaboration assures the accuracy of duplicate information in the destination application without duplicate entry.

Synchronization of related business objects

Although it synchronizes only Contracts, ContractSync can be configured to call the appropriate collaborations to verify or synchronize the following related business objects:

Business object Related collaboration properties Called collaborations
Contact FAIL_ON_CONTACT_ERROR VERIFY_SYNC_CONTACT

ContactSync

Contact Wrapper

Customer

VERIFY_SYNC_CUSTOMERS CustomerSync

CustomerWrapper

Item

Item Basic

ItemOrder

ItemPlanning

ITEM_TYPE VERIFY_SYNC_ITEM

ItemSync

ItemWrapper

Collaboration object setup

This section includes information on port bindings and required steps for setting up collaboration objects based on ContractSync. For information on standard features, ports, and configuration properties for collaboration templates, see the Collaboration Development Guide. For general information on creating collaboration objects, see the System Implementation Guide.

Port information

Figure 1 illustrates the relationship of ContractSync to its source and destination ports.

Figure 1. ContractSync 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
Contract The destination application's connector Sends a reference-valued business object to retrieve the full-valued business object. The result determines the verb to use when synchronizing the Contract.

Retrieve


Port name: From
Business object Bound to Function Verbs used
Contract Source application's connector or calling collaboration. Receives the triggering business object. At the end of a synchronous call, this port also returns the triggering business object to the source application when the collaboration ends successfully.

Create Retrieve Update Delete


Port name: To
Business object Bound to Function Verbs used
Contract The destination application's connector

Sends the triggering business object out of the collaboration.

Create Update Delete


Port name: ToContactWrapper
Business object Bound to Function Verbs used
Contact
  • The From port of ContactWrapper (if verifying or synchronizing)
  • Destination application's connector or the Port connector (if not verifying or synchronizing Contacts).
Used to send a Contact business object for verification or synchronization.

Sync Exists


Port name: ToCustomerWrapper
Business object Bound to Function Verbs used
Customer
  • The From port of CustomerWrapper (if verifying or synchronizing)
  • Destination application's connector or the Port connector (if not verifying or synchronizing Customers).
Used to send a Customer business object for verification or synchronization.

Sync Exists


Port name: ToItemWrapper
Business object Bound to Function Verbs used
Any of the generic item business objects, such as Item, ItemBasic, or ItemPlanning
  • The From port of ItemWrapper (if VERIFY_SYNC_ITEM = "verify" or "sync")
  • Destination application's connector or the Port connector (if not verifying or synchronizing)

Sends a reference-valued Item business object for verification or synchronization

Sync Exists

Setting up the collaboration object

Using ContractSync as stand-alone

To set up ContractSync as a stand-alone collaboration object, follow these steps:

  1. Create the ContractSync collaboration object.
  2. Bind each of the collaboration object's ToBusObjWrapper ports to the Port connector.
  3. Bind the remaining ports as described in Port information.
  4. Retain the default value of "neither" for the ContractSync collaboration object's VERIFY_SYNC_BusObj configuration property.
  5. Set the remaining collaboration properties. For more information, see Configuration properties.  

Using ContractSync in a collaboration-object group

To verify or synchronize related Customers, Contacts, or Items as part of the ContractSync process, you can create any combination of the following collaboration-object groups:


Verify Synchronize Required collaborations
Contacts   ContractSync, ContactWrapper
  Contacts ContractSync, ContactWrapper, ContactSync
Customers   ContractSync, CustomerWrapper
  Customers ContractSync, CustomerWrapper, CustomerSync
Items   ContractSync, ItemWrapper
  Items ContractSync, ItemWrapper, ItemSync

Using ContractSync in a collaboration-object group

The following procedure describes the steps for setting up ContractSync as part of a collaboration-object group: For the sake of example, these steps assume you want to synchronize Contracts and only their referenced Items.

  1. Create collaboration objects from the templates for ContractSync and for each wrapper and synchronization collaboration required. In this example, create collaboration objects for ContractSync, ItemWrapper, and ItemSync.
  2. Edit the ContractSync collaboration object to bind its ToBusObjWrapper ports to the appropriate wrapper collaboration object or to the Port connector. In this example, bind the ToItemWrapper port to the From port of the ItemWrapper collaboration. See the Port information section for appropriate destinations.
  3. Bind the remaining ports for the ContractSync collaboration object as described in this document's Port information section.
  4. Set the ContractSync collaboration object's VERIFY_SYNC_BusObj properties. In this example, set or retain these suggested values for the following properties.
  5. Set the ContractSync collaboration object's ITEM_TYPE to the desired item type.
  6. Configure the ItemWrapper collaboration object to bind its To port to ItemSync's From port.
  7. Bind the ItemWrapper collaboration object's remaining ports. For more information, see Port information in the Wrapper collaboration reference page. Note: System Manager will have already bound the ItemWrapper collaboration object's From port to ContractSync's To port.
  8. Edit the ItemSync collaboration object to bind its ports. For more information, see Port information in the ItemSync Collaboration reference page.
  9. Set the configuration properties for each collaboration object. For more information, see:

If synchronizing Contacts or Customers, configure their associated collaborations in the same manner as shown in the steps above.

Collaboration template processes

This section illustrates the process logic for this collaboration template:

Overall process logic

Figure 2 illustrates ContractSync's process logic.

Figure 2. ContractSync collaboration: process logic

NOTE: Some applications do not physically delete records. The source application may update the contact's status to inactive, rather than delete it. In this case, the collaboration receives a Contact business object with the Update verb. Refer to the connector documentation for information on how a specific application processes deletes.

Inherited process logic

This collaboration template uses the following standard collaboration business processes:

For information on these processes, see the Collaboration Development Guide.

Verification or synchronization of Customers and CustomerPartners

Figure 3 illustrates ContractSync's process for verifying or synchronizing Customers, Header Contacts, and Line Item Contacts.

ContractSync calls its wrapper collaborations in the following order: Customer, Contact (for header contacts), Item, Contact (for line-item contacts).

Figure 3. Verification or synchronization of Customers, Header Contacts, and Line Item Contacts

Verification or synchronization of Items

Figure 4 illustrates ContractSync's process for verifying or synchronizing related items.

Figure 4. Verification or synchronization of Items

Note: For a collaboration to process ItemBasic, ItemOrder, and ItemPlanning successfully, your installation's repository must contain the Utility business object. This business object is referenced in the collaboration code, which uses it to instantiate temporary iterator variables. The collaboration fails if this object is not present in the repository.

Compensation processing

InterChange Server Express Plus rolls back a transaction when any step in a transactional collaboration fails. For example, when ContractSync is a member of a collaboration-object group that participates in a transactional collaboration, its actions are one subtransactional step of a larger transaction. If any step in the collaboration-object group's business process fails, the transactional collaboration details how InterChange Server Express Plus rolls back the processing of every collaboration in the group.

When a ContractSync collaboration object is used independently of other collaboration objects or the collaboration object's From port is bound to a source application rather than to another collaboration, its process comprises a single transactional step. In such a situation, it is not necessary to perform rollback.

To cause a collaboration object or a collaboration-object group to perform rollback requires modification of the collaboration template. For information about these processes, see the System Implementation Guide. For information about adding transaction processing to the collaboration template, see the Collaboration Development Guide.

To extend the collaboration object to handle transaction processing, complete the following steps:

  1. Add this capability to the collaboration template and to every other collaboration template in the collaboration-object group.
  2. Set the minimum transaction level of the collaboration object and all members of the collaboration-object group to a value higher than None. If a failure occurs in any subtransaction step, settings of Minimal Effort or higher cause this collaboration object and other collaboration objects in the group to execute compensation for Create, Update, and Delete operations performed on all business objects.
  3. Set the USE_RETRIEVE property of the collaboration object and all other members of the collaboration-object group to "true". Forcing the collaboration objects to retrieve values before changing them allows the collaboration objects to restore the original values in an Update or Delete process.

Checklist for setting configuration properties

Because the Contract Manager collaboration-object group represents four collaborations, configuring all collaborations is critical for causing desired behavior. The following checklist specifies the configuration properties for all four collaborations.


Goal Property Setting
Retrieve a Contract from the destination application before attempting to synchronize it USE_RETRIEVE "true"
Verify items, contacts, or customers related to the triggering Contract VERIFY_SYNC_ITEM VERIFY_SYNC_CONTACT VERIFY_SYNC_CUSTOMERS "verify"
Synchronize items, contacts, or customers related to the triggering Contract VERIFY_SYNC_ITEM VERIFY_SYNC_CONTACT VERIFY_SYNC_CUSTOMERS "sync"
Convert a Create request to an Update request if ContractSync's triggering business object exists in the destination CONVERT_CREATE "true"
Stop the collaboration from processing when it encounters an invalid contact FAIL_ON_CONTACT_ERROR "true"
Convert an Update request to a Create request if ContractSync's triggering business object does not exist in the destination CONVERT_UPDATE "true"

How to set properties of ContractWrapper


Goal Property Setting
Specify that the ContractWrapper collaboration logs a warning and returns a success status to the calling collaboration if a verification or synchronization of related Contract data fails CONTINUE_WITH_WARNING "true"

Configuration properties

This section describes the standard properties and collaboration template-specific properties for this collaboration template:

Standard properties

This collaboration template uses the following standard configuration properties for collaboration templates:

For information on these configuration properties, see the Collaboration Development Guide.

Properties specific to this collaboration template

In addition to its standard configuration properties, this collaboration template has the configuration properties described below.

Configuration properties specific to the ContractSync collaboration template

Property name and explanation Possible values Default value

FAIL_ON_CONTACT_ERROR If set to false, the collaboration will remove the invalid contact and continue processing.

If set to true, the collaboration will stop processing.

false, true true

ITEM_TYPE The type of the Item business object to be sent to the wrapper.

Item, ItemBasic, ItemOrder, ItemPlanning

Item

VERIFY_SYNC_CONTACT

Set to "sync" to cause ContractSync to synchronize related Contacts in the destination application. ContractSync sends each Contact business object with the Sync verb to ContactWrapper. In turn, ContactWrapper retrieves values for all attributes from the source application and sends the business object with the Create verb to the destination. If ContactWrapper fails to create a Contact business object, ContractSync logs error message #5010 and ends. If ContactWrapper successfully creates all Contact business objects and if the trace level is set to 3 or higher, information message #5020 appears at the trace destination. Set to "verify" to cause ContractSync to verify related Contacts in the destination application. ContractSync sends each Contact business object with the Exists verb to ContactWrapper. In turn, ContactWrapper retrieves the business object from the destination application. If ContactWrapper fails to retrieve a Contact business object, ContractSync logs error message #5010 and ends. If ContactWrapper successfully verifies all Contact business objects and if the trace level is set to 3 or higher, information message #5020 appears at the trace destination.

Set to "neither" to cause ContractSync to synchronize the triggering Contract business object without first synchronizing or verifying related Contacts.

Note: For descriptions of the messages corresponding to the message numbers, refer to the following collaboration message file: \collaborations\messages\ContractSync.txt.

neither, sync, verify sync

VERIFY_SYNC_CUSTOMERS

Set to "sync" to synchronize the related Customer in the destination application. ContractSync sends the business object with the Sync verb to CustomerWrapper. In turn, CustomerWrapper retrieves values for all attributes from the source application and sends the business object with the Create verb to the destination. If the synchronization collaboration fails to create the Customer, ContractSync logs error message #5010 and ends. If CustomerWrapper successfully creates all Customer business objects and if the trace level is set to 3 or higher, information message #5020 appears at the trace destination. Set to "verify" to verify the related Customer in the destination application. ContractSync sends the business object with the Exists verb to CustomerWrapper. In turn, CustomerWrapper retrieves the business object from the destination application. If CustomerWrapper fails to retrieve a Customer business object, ContractSync logs error message #5010 and ends. If CustomerWrapper successfully verifies all Customer business objects and if the trace level is set to 3 or higher, information message #5020 appears at the trace destination.

Set to "neither" to cause ContractSync to create the Contract business object without first synchronizing or verifying the related Customer in the destination application.

Note: For descriptions of the messages corresponding to the message numbers, refer to the following collaboration message file: \collaborations\messages\ContractSync.txt.

neither, sync, verify sync

VERIFY_SYNC_ITEM

Set to "sync" to cause ContractSync to synchronize related items in the destination application. ContractSync sends the business object with the Sync (and values in key fields only) verb to ItemWrapper. In turn, ItemWrapper retrieves values for all attributes from the source application and sends the generic business object with the Create verb to ItemSync. If ItemWrapper fails to create the related item, ContractSync logs error message #5010 and ends. If ItemWrapper successfully creates all of the related items and if the trace level is set to 3 or higher, information message #5020 appears at the trace destination.

Set to "verify" to cause ContractSync to verify related items in the destination application. ContractSync sends the business object with the Exists verb to ItemWrapper. In turn, ItemWrapper retrieves the business object from the destination application. If ItemWrapper fails to retrieve the related item, ContractSync logs error message #5010 and ends. If ItemWrapper successfully verify all of the related items and if the trace level is set to 3 or higher, information message #5020 appears at the trace destination.

Set to "neither" to cause ContractSync to synchronize the triggering Contract business object without first synchronizing related items or verifying existing related items in the destination application.

neither, sync verify sync

Collaboration messages

Note: Messages that provide warnings and those that provide information appear at the trace destination only if the trace level has been set to 3 or higher. The trace level is configurable using the INFORMATIONAL_EXCEPTIONS and SEND_EMAIL properties.

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.

Upgrade information

Upgrade process

To upgrade to a newer version of the collaboration template, perform the following steps:

  1. Stop the ContractSync version x.x.x collaboration template.
  2. Back up the repository. For information about backing up the repository, see the System Implementation Guide.
  3. If you have customized the collaboration template:
  4. Install the new ContractSync collaboration template.
  5. Add your customizations to the new collaboration template.
  6. Create the new collaboration object, binding it to the appropriate connectors. For more information, see Collaboration setup.
  7. Run and test the new collaboration object.
  8. Make changes to the collaboration object based on any problems found during testing.

Copyright IBM Corp. 1997, 2004

Copyright IBM Corp. 2004