CustomerSync Collaboration Template

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

The CustomerSync collaboration, in conjunction with the other collaborations that compose the Customer Manager collaboration-object group, specifies a common process for maintaining and synchronizing customer information across all systems that use it. This synchronization enables a common view of customer information throughout the organization.

The Customer Manager collaboration-object group synchronizes customer 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 a duplicate entry.

The Customer Manager collaboration-object group

Customer information is often stored in a hierarchy with the SoldTo customer, which is referenced in Sales Order Processing, at the top. Supporting customer information, such as BillTo and ShipTo data, is stored in relationship to the SoldTo Customer.

IBM stores data about the SoldTo Customer in the generic Customer business object. It stores data about related customers or addresses in the generic CustomerPartner business object. IBM also uses the Customer business object to store the relationships between the SoldTo Customer and its related customers.

The Customer Manager collaboration-object group uses these two generic business objects and three collaborations to synchronize SoldTo Customers and their related data. The three collaborations are:

CustomerSync

CustomerSync uses the generic Customer business object to synchronize a SoldTo customer and its relationships to related customers.

The collaboration can be configured (VERIFY_SYNC_CUSTOMERPARTNERS) to cause the synchronization or verification of all customer data related to the SoldTo Customer. If so configured, CustomerSync creates a generic CustomerPartner business object for each related customer or address and sends it to the CustomerPartnerWrapper collaboration. The only value specified for the CustomerPartner is the unique key; in other words, CustomerSync sends a reference-valued business object to CustomerPartnerSync. CustomerSync uses the value of its VERIFY_SYNC_CUSTOMERPARTNERS property to determine whether to send CustomerPartner with the Sync or Exists verb, specifying either synchronization or verification.

Another of CustomerSync's configuration properties (SYNC_PARENT_FIRST) determines whether the collaboration synchronizes the related customer before or after it synchronizes the SoldTo Customer. The choice depends on how the destination application stores the data. The two storage options are:

Relationship stored on the child

Some applications (such as Baan, Oracle, and Vantive) store the relationship at the child level (that is, in the address or related customer role). The related customer data does not exist independently of its parent SoldTo record and cannot be associated with more than one SoldTo customer. The SoldTo customer must exist before these related records can be created.

For example, when CustomerSync is bound to Oracle as the destination application, configuring SYNC_PARENT_FIRST to "true" causes the collaboration to:

  1. Create the parent object (that is, the SoldTo customer).
  2. Create a CustomerPartner business object for each child object (that is, each related address) and send it to CustomerPartnerWrapper.
  3. Update the parent Customer to create the links to its related CustomerPartners

Notes: Because IBM stores the link to the child on the parent (generic Customer) business object:

Relationship stored on the parent

Some applications (such as Clarify, PeopleSoft, and SAP) store the relationships between the SoldTo customer and its related customers at the parent level. These applications store the customer's related customer data (such as BillTo customer and ShipTo customer) as separate objects. These objects exist independently of their parent SoldTo object and can be associated with more than one SoldTo customer. These related customer partners should exist before the SoldTo customer is created.

For example, when CustomerSync is bound to SAP as the destination application, configuring SYNC_PARENT_FIRST to "false" causes the collaboration to:

  1. Create a CustomerPartner business object for each child object (that is, each related customer) and send it to CustomerPartnerWrapper.
  2. Create the parent Customer business object. The Customer business object stores the links to its related CustomerPartners.

Note: In the IBM WebSphere Business Integration Server Express Plus system, a SoldTo can not serve as a customer partner for another SoldTo. Therefore, even applications that allow this relationship may require customization to represent a SoldTo as the BillTo for another SoldTo.

For information about all of CustomerSync's configuration properties, see Configuration properties.

CustomerPartnerSync

CustomerPartnerSync synchronizes related customers or addresses in the destination application. CustomerPartnerSync can be run independently of CustomerSync, in which case it is triggered directly by a source application. If triggered by CustomerSync, CustomerPartnerSync returns a status to it.

For information on CustomerPartnerSync's configuration options, see Checklist for setting configuration properties.

CustomerPartnerWrapper

CustomerPartnerWrapper either verifies the existence of related customer data in the destination application or causes the data to be synchronized in the destination.

In either case, CustomerPartnerWrapper returns a status to its calling collaboration.

For information on CustomerPartnerWrapper's configuration options, see Checklist for setting configuration properties.

Your installation requires the following collaboration objects:

Collaboration object Description
CustomerSync The source application triggers a synchronize-Customer event that is processed by a CustomerSync collaboration object. CustomerSync gets the unique key of each related customer from the Customer business object. The collaboration creates a CustomerPartner business object for each related customer, populating each business object only with its unique key. CustomerSync then calls a CustomerPartnerWrapper collaboration object to synchronize this CustomerPartner in the destination application.

CustomerPartnerWrapper

Called by CustomerSync, CustomerPartnerWrapper retrieves the full-valued CustomerPartner business object from the source application and sends it to a CustomerPartnerSync collaboration object.

CustomerPartnerSync

Called by CustomerPartnerWrapper (to which its From port is bound), CustomerPartnerSync synchronizes the CustomerPartner in the destination application.

CustomerPartnerSync The source application triggers a synchronize-CustomerPartner event that is processed by a second CustomerPartnerSync collaboration object. This collaboration object's From port is bound directly to the source application. The collaboration synchronizes CustomerPartners independently of their related SoldTo Customers.

Figure 1 illustrates the collaborations and generic business objects required in the scenario described above. The three-dimensional objects represent business objects. The ovals represent collaboration objects.

Figure 1. Relationship of required collaborations in the usage example

Note: To specify your own requirements and conditions, you must separately configure each collaboration in the group. For more information, see the Checklist for setting configuration properties.

Collaboration object setup

This section includes information on port bindings and required steps for setting up collaboration objects based on CustomerSync. 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 2 illustrates CustomerSync's ports, as they are displayed in System Manager.

Figure 2. CustomerSync collaboration's 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
Customer 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 Customer.

Retrieve


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

Sends the triggering business object out of the collaboration.

Create Update Delete


Port name: ToCustomerPartnerWrapper
Business object Bound to Function Verbs used
CustomerPartner
  • The From port of CustomerPartnerWrapper (if verifying or synchronizing)
  • Destination application's connector or the Port connector (if not verifying or synchronizing CustomerPartners).

Used to send a reference-valued CustomerPartner business object to the CustomerPartnerWrapper collaboration.

  • If the triggering verb is Sync, CustomerPartnerWrapper calls CustomerPartnerSync to create the related customer in the destination and then return a status to CustomerSync.
  • If the triggering verb is Exists, CustomerPartnerWrapper verifies the related customers in the destination application and then returns a status to CustomerSync.

Sync Exists

Setting up the collaboration object

Using CustomerSync as stand-alone

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

  1. Create the CustomerSync collaboration object.
  2. Bind the collaboration object's ToCustomerPartnerWrapper port to the destination application's connector or to the Port connector.
  3. Bind the remaining ports as described in Port information.
  4. Retain the default value of "neither" for CustomerSync's VERIFY_SYNC_CUSTOMERPARTNERS configuration property.
  5. Set the remaining Configuration properties for CustomerSync.  

Using CustomerSync in a collaboration-object group

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


Verify Synchronize Required collaborations
CustomerPartners   CustomerSync, CustomerPartnerWrapper
  CustomerPartners CustomerSync, CustomerPartnerWrapper, CustomerPartnerSync

The following steps describe the setup procedure, providing alternatives steps for handling CustomerPartner verification or synchronization:

  1. Create collaboration objects from the CustomerSync, CustomerPartnerWrapper, and (optionally) CustomerPartnerSync templates.
  2. Edit the CustomerSync collaboration object to bind its ToCustomerPartnerWrapper port to the From port of the CustomerPartnerWrapper collaboration object.
  3. Bind the remaining ports for the CustomerSync collaboration object as described in this document's Port information section.
  4. Set the CustomerSync collaboration object's VERIFY_SYNC_CUSTOMERPARTNERS configuration property. For customer partner verification, set it to "verify"; for customer partner synchronization, set it to "sync".
  5. Edit the CustomerPartnerWrapper collaboration object to bind its To port.
  6. Bind the CustomerPartnerWrapper 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 CustomerPartnerWrapper collaboration object's To port to CustomerSync's From port. For customer partner verification, skip to step #8.
  7. For CustomerPartner synchronization, edit the CustomerPartnerSync collaboration object to bind its ports. System Manager will have already bound its From port to CustomerPartnerWrapper's To port. Bind its remaining ports. For more information, see Port information in the CustomerPartnerSync Collaboration reference page.
  8. Set the configuration properties for each collaboration. For more information, see:

Collaboration template processes

This section illustrates the process logic for this collaboration template:

Overall process logic

Figure 3 illustrates CustomerSync's process logic.

Figure 3. CustomerSync collaboration process logic

Inherited process logic

This collaboration template uses the following standard collaboration business processes:

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

Create and update processes

Figure 4 illustrates CustomerSync's Create and Update processes.

Figure 4. CustomerSync collaboration: create and update processes

Note: CustomerSync uses CustomerPartnerWrapper to send the CustomerPartner business object to CustomerPartnerSync. Wrapper collaborations always send the business object with the Create verb. To cause CustomerPartnerSync to convert the Create to an Update when the business object already exists in the destination application, set its CONVERT_CREATE property to "true".

Updating references to CustomerPartners

When CustomerSync sends the Customer business object with the Update verb to the destination, the synchronization updates relationships to CustomerPartners, but it does not actually create, update or delete a CustomerPartner.

For example, when a Customer deletes a reference to a CustomerPartner, the application does not delete the CustomerPartner (neither physical nor logical delete). The application simply removes the reference to the CustomerPartner -- it removes the relationship to the CustomerPartner without removing the CustomerPartner.

Figure 5 illustrates data for Customer #100 that has been synchronized by CustomerSync. Both the source and destination applications contain the same primary Customer with the same three related CustomerPartners.

Figure 5. Customer data before deletion of references to CustomerPartners

Figure 6 illustrates the same primary Customer after the source application has deleted one of its related CustomerPartners. The deletion of the child business object triggers the source connector to send the Customer business object with the Update verb to CustomerSync. The graphic illustrates the state of the Customer business object as CustomerSync sends it to the destination application, before the destination application has removed the reference to the related CustomerPartner.

Figure 6. Customer data after the source application has deleted references to CustomerPartners

Figure 7 illustrates the state of the Customer business object after deletion of the reference to the related CustomerPartner in the destination application.

Figure 7. Customer data after synchronization in the destination application

Compensation processing

InterChange Server Express can roll back a transaction when any step in a transactional collaboration fails. For example, when CustomerSync 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 rolls back the processing of every collaboration in the group.

When a CustomerSync 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 Customer Manager collaboration-object group represents three collaborations, configuring all collaborations is critical for causing desired behavior. The following checklist specifies the configuration properties for all three collaborations.


Goal Property Setting
Retrieve a Customer from the destination application before attempting to synchronize it. USE_RETRIEVE "true"
Create the SoldTo Customer in the destination application before creating the related customers or addresses. SYNC_PARENT_FIRST "true"
Verify customers or addresses related to the triggering SoldTo Customer. VERIFY_SYNC_CUSTOMERPARTNERS "verify"
Synchronize customers or addresses related to the triggering SoldTo Customer. VERIFY_SYNC_CUSTOMERPARTNERS "sync"
Convert a Create request to an Update request if CustomerSync's triggering business object exists in the destination. CONVERT_CREATE "true"
Convert an Update request to a Create request if CustomerSync's triggering business object does not exist in the destination. CONVERT_UPDATE "true"

How to set properties of CustomerPartnerSync


Goal Property Setting
Retrieve a CustomerPartner from the destination application before attempting to synchronize it. USE_RETRIEVE "true"
Convert a Create request to an Update request if CustomerPartnerSync's triggering business object exists in the destination. CONVERT_CREATE "true"
Convert an Update request to a Create request if CustomerPartnerSync's triggering business object does not exist in the destination. CONVERT_UPDATE "true"

How to set properties of CustomerPartnerWrapper


Goal Property Setting
Specify that the CustomerPartnerWrapper collaboration log a warning and return a success status to its calling collaboration if a verification or synchronization of related customer 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 CustomerSync collaboration template

Property name and explanation Possible values Default value

SYNC_PARENT_FIRST

Set to "true" to cause CustomerSync to create the SoldTo Customer in the destination application before it creates the related customers or addresses (CustomerPartners). Use this setting when the destination application does not reuse the customer partner, that is, the application stores the parent/child relationship in the child. In this case, the application must create the Customer before it can create any of the CustomerPartner business objects.

Set to "false" to cause CustomerSync to create the related customers or addresses (CustomerPartners) in the destination application before it creates the SoldTo Customer. Use this setting when the destination application reuses the customer partner, that is, the application stores the parent/child relationship in the parent. In this case, the application must create the CustomerPartners before it can create the Customer business object.

true, false

false

VERIFY_SYNC_CUSTOMERPARTNERS

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

Set to "sync" to cause this collaboration to synchronize related customers and addresses in the destination application. The collaboration performs the following process:

  1. Creates a reference-valued CustomerPartner business object, populating it with the unique key contained in the triggering business object.
  2. Sends the business object with the Sync verb to CustomerPartnerWrapper. CustomerPartnerWrapper retrieves values for all attributes from the source application and sends the full-valued business object with the Create verb to CustomerPartnerSync.
  3. 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. Creates a reference-valued CustomerPartner business object, populating it with the unique key contained in the triggering business object.
  2. Sends the business object with the Exists verb to CustomerPartnerWrapper. CustomerPartnerWrapper retrieves the business object from the destination application.
  3. If the wrapper collaboration fails to retrieve the CustomerPartner, this collaboration handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

Note: For descriptions of the messages for CustomerSync, refer to the collaboration message file: \collaborations\messages\CustomerSync.txt.

 

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, perform the following steps:

  1. Stop the current CustomerSync 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 CustomerSync 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