ContactSync collaboration template

The ContactSync collaboration synchronizes data about specific customer contacts between a source application and a destination application. This collaboration uses the generic Contact business object, which contains profile information about the people at each customer site who contact your organization. The synchronization of contact information allows separate applications to share information consistently whenever data is added, changed, or deleted in the enterprise. Although ContactSync synchronizes only Contacts, you can configure it to call the appropriate collaborations to verify or synchronize the following related business objects:

Business object Related collaboration properties Called collaborations
Customer VERIFY_SYNC_CUSTOMERS CustomerSync CustomerWrapper

CustomerPartner

VERIFY_SYNC_CUSTOMERPARTNERS CustomerPartnerWrapper CustomerPartnerSync

This document describes how to create and configure the collaboration template and describes its business processes.

Collaboration object setup

This section includes information on port bindings and required steps for setting up collaboration objects based on ContactSync. 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 ContactSync's ports as they are displayed in System Manager. The tables that follow the figure provide information about each port.

Figure 1. ContactSync 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
Contact 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 Contact.

Retrieve


Port name: From
Business object Bound to Function Verbs used
Contact 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
Contact The destination application's connector

Sends the triggering business object out of the collaboration.

Create Update Delete


Port name: ToCustomerWrapper
Business object Bound to Function Verbs used
Customer
  • The From port of CustomerWrapper (if VERIFY_SYNC_CUSTOMERS = "verify" or "sync").
  • Destination application's connector or the Port connector (if not verifying or synchronizing Customers).
Sends a reference-valued Customer business object for verification or synchronization.

Sync Exists


Port name: ToCustomerPartnerWrapper
Business object Bound to Function Verbs used
CustomerPartner
  • The From port of CustomerPartnerWrapper (if VERIFY_SYNC_CUSTOMERPARTNERS = "verify" or "sync").
  • Destination application's connector or the Port connector (if not verifying or synchronizing CustomerPartners).
Sends a reference-valued CustomerPartner business object for verification or synchronization.

Sync Exists

Setting up the collaboration object

Using ContactSync as stand-alone

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

  1. Create the ContactSync collaboration object.
  2. Bind each of the collaboration object's ToBusObjWrapper ports to the destination application's connector or to the Port connector. For example, bind the ToCustomerWrapper port to the Port connector.
  3. Bind the remaining ports as described in Port information.
  4. Retain the default value of "neither" for the collaboration object's VERIFY_SYNC_BusObj configuration properties.
  5. Set the remaining Configuration properties for ContactSync.  

Using ContactSync in a collaboration-object group

To verify or synchronize related Customers and CustomerPartners as part of the ContactSync process, you can create any combination of the following collaboration-object groups:


Verify Synchronize Required collaborations
Customers   ContactSync, CustomerWrapper
  Customers ContactSync, CustomerWrapper, CustomerSync
CustomerPartners   ContactSync, CustomerPartnerWrapper
  CustomerPartners ContactSync, CustomerPartnerWrapper, CustomerPartnerSync

The following procedure describes setting up ContactSync as part of a collaboration-object group. In this example, the steps assume you want to synchronize Contacts and their referenced SoldTo Customers, but not their referenced CustomerPartners.

  1. Create collaboration objects from the templates for ContactSync and for each wrapper and synchronization collaboration required. In this example, create collaboration objects for ContactSync, CustomerWrapper, and CustomerSync.
  2. Edit the ContactSync collaboration object to bind its ToBusObjWrapper ports to the appropriate wrapper collaboration object or to the Port connector. In this example, bind the ToCustomerWrapper port to CustomerWrapper's From port . See the Port information section for appropriate destinations.
  3. Bind the remaining ports for the ContactSync collaboration object as described in this document's "Port Information" section.
  4. Set the ContactSync collaboration object's VERIFY_SYNC_BusObj properties. In this example, set or retain these suggested values for the following properties.
  5. Configure the CustomerWrapper collaboration object to bind its To port to CustomerSync's From port.
  6. Bind the CustomerWrapper 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 CustomerWrapper collaboration object's From port to the ContactSync collaboration object.
  7. Edit the CustomerSync collaboration object to bind its ports. For more information, see Port information in the CustomerSync collaboration reference page.
  8. Set the configuration properties for each collaboration. Note: To synchronize referenced CustomerPartners as well as referenced Customers, follow this procedure to bind the port (ToCustomerPartnerWrapper), to set the configuration property (VERIFY_SYNC_CUSTOMERPARTNERS), and to create and configure the required collaboration objects (CustomerPartnerWrapper and CustomerPartnerSync).

Collaboration template processes

This section illustrates the process logic for this collaboration template:

Overall process logic

Figure 2 illustrates ContactSync's process logic.

Figure 2. ContactSync 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 ContactSync's process for verifying or synchronizing related Customers and CustomerPartners.

Note: Each Contact business object contains a ContactCustomer business object with single cardinality. If ContactCustomer's RoleName attribute evaluates to "Customer", ContactSync creates a Customer business object and sends it to CustomerWrapper. If RoleName evaluates to "CustomerPartner", ContactSync creates a CustomerPartner business object and sends it to CustomerPartnerWrapper.

Figure 3: Verification or synchronization of Customers and CustomerPartners

Compensation processing

InterChange Server Express Plus rolls back a transaction when any step in a transactional collaboration fails. For example, when ContactSync 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 ContactSync 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.

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 ContactSync collaboration template

Property name and explanation Possible values Default value

VERIFY_SYNC_CUSTOMERS

Set to "sync" to cause this collaboration to synchronize the related SoldTo Customer in the destination application. The collaboration performs the following process:

  1. Gets the customer's unique key and determines its type (Customer) from Contact's ContactCustomer child business object.
  2. Copies the CustomerId from the triggering business object and uses it as the unique identifier of the newly created generic Customer business object.
  3. Sends the business object with the Sync verb to CustomerWrapper. CustomerWrapper retrieves values for all attributes from the source application and sends the business object with the Create verb to CustomerSync.
  4. If the synchronization collaboration fails to create the Customer, this collaboration handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

Set to "verify" to cause this collaboration to verify the related Customer in the destination application. The collaboration performs the following process:

  1. Gets the customer's unique key and determines its type (Customer) from Contact's ContactCustomer child business object.
  2. Copies the CustomerId from the triggering business object and uses it as the unique identifier of the newly created generic Customer business object.
  3. Sends the business object with the Exists verb to CustomerWrapper. CustomerWrapper retrieves the business object from the destination application.
  4. If the wrapper collaboration fails to retrieve the Customer, this collaboration handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

Set to "neither" to cause this collaboration to synchronize its triggering business object without first synchronizing or verifying the related Customer in the destination application. VERIFY_SYNC_CUSTOMERPARTNERS

verify, sync, neither neither

VERIFY_SYNC_CUSTOMERPARTNERS

Set to "sync" to cause this collaboration to synchronize supporting customer information, such as BillTo and ShipTo data, that is stored in relationship to the SoldTo Customer. The collaboration performs the following process:

  1. Gets the customer's unique key and determines its type (CustomerPartner) from Contact's ContactCustomer child business object.
  2. Copies the CustomerPartnerId from the triggering business object and uses it as the unique identifier of the newly created generic CustomerPartner business object.
  3. Sends the business object with the Sync verb to CustomerPartnerWrapper. CustomerPartnerWrapper retrieves values for all attributes from the source application and sends the business object with the Create verb to CustomerPartnerSync.
  4. If the synchronization collaboration fails to create the CustomerPartner, this collaboration handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

Set to "verify" to cause this collaboration to verify the related CustomerPartner in the destination application. The collaboration performs the following process:

  1. Gets the customer's unique key and determines its type (CustomerPartner) from Contact's ContactCustomer child business object.
  2. Copies the CustomerPartnerId from the triggering business object and uses it as the unique identifier of the newly created generic CustomerPartner business object.
  3. Sends the business object with the Exists verb to CustomerPartnerWrapper. CustomerPartnerWrapper retrieves the business object from the destination application.
  4. If the wrapper collaboration fails to retrieve the CustomerPartner, this collaboration handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

Set to "neither" to cause this collaboration to synchronize its triggering business object without first synchronizing or verifying the related CustomerPartner in the destination application.

sync, verify, neither

neither

Collaboration messages

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 ContactManager version x.x.x collaboration.
  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 ContactManager 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