InstalledProductSync Collaboration Template

The InstalledProductSync collaboration is part of a larger business process that is often referred to as Service Management or Customer Service. This business process is used by global companies that manage an install base to provide after-sales service to products that have been installed at customer sites.

InstalledProductSync can help a global company represent its install base so that users of its front-office and back-office applications know what products are installed at which customer sites. IBM assumes that global companies that use InstalledProductSync use front-office and back-office applications in the following ways:

When the back-office application creates an installed product that is managed as part of the install base, it triggers InstalledProductSync to create an installed product object in the front-office application. The front-office application handles any cases that are logged against the product. If a case that is logged against the product requires further processing in the back-office system, the front-office application triggers InstalledProductSync to create the installed product object in the back-office application.

If a global company uses a front-office application to manage its install base, case processing, contract management, and service billing and uses a back-office application only for order fulfillment, IBM recommends using its ProductInstallation collaboration in addition to InstalledProductSync.

Whereas InstalledProductSync synchronizes installed products from a source to a destination application, ProductInstallation uses delivery data triggered in the back-office source application to create installed products in the front-office destination application. These collaborations can be used in the following ways:

InstalledProductSync uses the generic InstalledProduct business object to synchronize installed product data.

Synchronization of related business objects

Although it synchronizes only InstalledProducts, InstalledProductSync 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 VERIFY_SYNC_CONTACT FAIL_ON_CONTACT_ERROR

ContactSync

ContactWrapper

Customer

VERIFY_SYNC_CUSTOMERS CustomerSync CustomerWrapper
CustomerPartner VERIFY_SYNC_CUSTOMERPARTNERS CustomerPartnerSync CustomerPartnerWrapper
Item

ItemBasic

ItemOrder

ItemPlanning

VERIFY_SYNC_ITEM

ITEM_TYPE

ItemSync

ItemWrapper

Site

VERIFY_SYNC_SITE

SiteSync

SiteWrapper

Note: If you configure InstalledProductSync to synchronize Contact, Customer, CustomerPartner, Item, or Site data, create and bind the appropriate collaboration objects before you configure InstalledProductSync. For more information, see Collaboration setup.

Connector support

In addition to the filtering that InstalledProductSync can perform, IBM WebSphere Business Integration Server Express Plus connectors can filter out specific types of InstalledProduct. Handling filtering in the source connector rather than in the collaboration can enhance performance. Note: The filtering feature is application-specific. To determine the capability of a specific application, refer to the reference documentation for its business object.

Issues and assumptions

Collaboration object setup

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

Figure 1. InstalledProductSync 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
InstalledProduct 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 InstalledProduct.

Retrieve


Port name: From
Business object Bound to Function Verbs used
InstalledProduct 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: SourceAppRetrieve
Business object Bound to Function Verbs used
InstalledProduct Source application's connector

Retrieves a full-valued parent InstalledProduct business object based on the ID contained in the referencing business object.

Retrieve


Port name: To
Business object Bound to Function Verbs used
InstalledProduct

Destination application's connector

Sends the triggering business object or one of its parent business objects out of the collaboration.

Create Update Delete


Port name: ToContactWrapper
Business object Bound to Function Verbs used
Contact

The From port of ContactWrapper (if VERIFY_SYNC_CONTACT = "verify" or "sync").

Destination application's connector or the Port connector (if not verifying or synchronizing).

Sends a reference-valued 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 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).

Sends a reference-valued CustomerPartner 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


Port name: ToSiteWrapper
Business object Bound to Function Verbs used
Site

The From port of SiteWrapper (if VERIFY_SYNC_SITE = "verify" or "sync").

Destination application's connector or the Port connector (if not verifying or synchronizing).

Sends a reference-valued Site business object for verification or synchronization.

Sync Exists

Setting up the collaboration object

Using InstalledProductSync as stand-alone

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

  1. Create the InstalledProductSync collaboration object.
  2. Bind each of the collaboration object's ToBusObjWrapper ports to the destination application's connector or to the Port connector. Example: bind the SendItemRef port to the Port connector.
  3. Bind the remaining ports as described in Port information.
  4. Retain the default value of "neither" for the InstalledProductSync collaboration object's VERIFY_SYNC_BusObj configuration properties. Example: keep the VERIFY_SYNC_ITEM property set to "neither".
  5. Set the remaining Configuration properties for InstalledProductSync.  

Using InstalledProductSync in a collaboration-object group

To verify or synchronize related Contacts, Customers, CustomerPartners, items (of the type specified), or Sites as part of the InstalledProductSync process, you can create any combination of the following collaboration-object groups:


Verify Synchronize Required collaborations
Contacts   InstalledProductSync, ContactWrapper
  Contacts InstalledProductSync, ContactWrapper, ContactSync
Customers   InstalledProductSync, CustomerWrapper
  Customers InstalledProductSync, CustomerWrapper, CustomerSync
CustomerPartners   InstalledProductSync, CustomerPartnerWrapper
  CustomerPartners InstalledProductSync, CustomerPartnerWrapper, CustomerPartnerSync
Items   InstalledProductSync, ItemWrapper
  Items InstalledProductSync, ItemWrapper, ItemSync
Sites   InstalledProductSync, SiteWrapper
  Sites InstalledProductSync, SiteWrapper, SiteSync

The following procedure describes the steps for setting up InstalledProductSync as part of a collaboration-object group. For this example, the steps assume you want to synchronize InstalledProducts and only their referenced Items and Sites.

  1. Create collaboration objects from the templates for InstalledProductSync and for each wrapper and synchronization collaboration required. In this example, create collaboration objects for InstalledProductSync, ItemWrapper, ItemSync, SiteWrapper, and SiteSync.
  2. Edit the InstalledProductSync collaboration object to bind its ToBusObjWrapper ports to the appropriate wrapper collaboration object or to the Port connector. In this example, bind the ToItemWrapper and ToSiteWrapper ports to the From port of the ItemWrapper and SiteWrapper collaborations, respectively. See the Port information section for appropriate destinations.
  3. Bind the remaining ports for the InstalledProductSync collaboration object as described in this document's Port information section.
  4. Set the InstalledProductSync collaboration object's VERIFY_SYNC_BusObj properties. In this example, set or retain these suggested values for the following properties.
  5. Set the InstalledProductSync collaboration object's ITEM_TYPE to the desired item type, and set it's FAIL_ON_CONTACT_ERROR property to the desired value.
  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 InstalledProductSync'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. Edit the SiteWrapper collaboration object to bind its To port to SiteSync's From port.
  10. Bind the SiteWrapper collaboration object's remaining ports. For more information, see Port information in the Wrapper collaboration reference page.
  11. Edit the SiteSync collaboration object to bind its ports. For more information, see Port information in the SiteSync Collaboration reference page.
  12. Set the configuration properties for each collaboration. For more information, see:

If synchronizing Contacts, Customers, or CustomerPartners, 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

The process logic includes the following subprocesses:

Depending on the value of its VERIFY_SYNC_PARENT property, the collaboration ignores the triggering business object's parent business object, verifies the triggering business object's parent business object, or synchronizes the triggering business object's ancestors. An ancestor is a parent business object or the parent of a parent.

For example, assume that your organization builds cars and manages the components as separate installed products within a product hierarchy. In such a case, you might handle the fuel injector as an installed product, the parent of the fuel injector (the engine) as an installed product, and the parent of the engine (the car) as an installed product.

When configured to synchronize ancestor InstalledProducts, InstalledProductSync recursively locates the parent of the triggering InstalledProduct and the parent of each parent. After locating all of the parents, InstalledProductSync synchronizes the topmost parent before synchronizing its child. The triggering business object is the last business object that the collaboration synchronizes. For more information, see Synchronization of parent business objects. Figure 2 illustrates the main business process. Figure 3 illustrates the process for synchronizing parent InstalledProduct business objects, in other words, VERIFY_SYNC_PARENT evaluates to "sync". For more information, see Verification or synchronization of parent business objects.

Depending on the value of its VERIFY_SYNC_BusObj properties (such as VERIFY_SYNC_ITEM and VERIFY_SYNC_CONTACT), InstalledProductSync calls wrapper collaborations to create or verify the existence of business objects that are referenced by the InstalledProduct business object. For more information about verifying or synchronizing these related objects, see Verification or synchronization of referenced business objects.

Figure 2 illustrates InstalledProductSync's process logic.

Figure 2. InstalledProductSync 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.

Verification or synchronization of parent business objects

If VERIFY_SYNC_PARENT evaluates to "verify" or "sync", InstalledProductSync performs the following steps:

  1. Places the triggering business object in a stack.
  2. Sends the triggering business object through the filtering process. If it passes filtering, InstalledProductSync checks the value of InstalledProduct's ParentId attribute.

Figure 3 illustrates InstalledProductSync's process for synchronizing parent InstalledProducts.

Figure 3. Process for synchronizing parent InstalledProducts

Verification or synchronization of Items, Contacts, Customers, CustomerPartners, and Sites

To verify or synchronize referenced Items, InstalledProductSync must first determine the type of generic Item business object. To do so, it evaluates its ITEM_TYPE property.

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.

To verify or synchronize referenced Customers and CustomerPartners, InstalledProductSync must first determine which of these business objects each InstalledProduct business object references. If its VERIFY_SYNC_CUSTOMERS and VERIFY_SYNC_CUSTOMERPARTNERS properties evaluate to "verify" or "sync", InstalledProductSync checks the value of the ObjectType attribute of InstalledProduct's RelatedCustomerRef child business object. If the value is "Customer", InstalledProductSync sends the Customer business object to CustomerWrapper. If the value is "CustomerPartner", InstalledProductSync sends the CustomerPartner business object to CustomerPartnerWrapper.

If it fails to synchronize a referenced Contact, InstalledProductSync evaluates its FAIL_ON_CONTACT_ERROR property. If this property is set to "false", the collaboration removes failed Contacts from InstalledProduct's ContactRef child business object and continues processing. If this property is set to "true", the collaboration raises an exception and stops.

Figure 4 illustrates InstalledProductSync's process for verifying or synchronizing referenced Items, Contacts, Customers, CustomerPartners, and Sites.

Figure 4. Verification or synchronization of Items, Contacts, Customers, CustomerPartners, and Sites

Compensation processing

InterChange Server Express can roll back a transaction when any step in a transactional collaboration fails. For example, when InstalledProductSync 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 an InstalledProductSync 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 this collaboration template

Property name and explanation Possible values Default value

FAIL_ON_CONTACT_ERROR

Set to "true" to cause InstalledProductSync to stop processing if VERIFY_SYNC_CONTACT evaluates to true and ContactWrapper fails to verify or synchronize any of the referenced Contacts.

Set to "false" to cause InstalledProductSync to continue processing if VERIFY_SYNC_CONTACT evaluates to true and ContactWrapper fails to verify or synchronize any of the referenced Contacts. In this case, InstalledProductSync removes each failed Contact from InstalledProduct's array of ContactRef child business objects.

true, false true

ITEM_TYPE

Set to the type of generic Item whose existence should be synchronized or verified before the collaboration synchronizes the InstalledProduct business object. If its VERIFY_SYNC_ITEM property evaluates to "sync" or "verify", InstalledProductSync uses the value of this property to determine the type of item to be synchronized or verified.

Item, ItemBasic, ItemOrder, ItemPlanning Item

VERIFY_SYNC_CONTACT

Set to "sync" to cause InstalledProductSync to synchronize related Contacts in the destination application. InstalledProductSync copies the ContactId from each of InstalledProduct's ContactRef child business objects and creates a generic Contact business object for each referenced Contact. InstalledProductSync 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 ContactSync. If ContactSync fails to create the related Contact, the behavior of InstalledProductSync depends on the value of its FAIL_ON_CONTACT_ERROR property.

Set to "verify" to cause InstalledProductSync to verify related Contacts in the destination application. InstalledProductSync copies the ContactId from each of InstalledProduct's ContactRef child business objects and creates a generic Contact business object for each referenced Contact. InstalledProductSync 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 the related Contact, the behavior of InstalledProductSync depends on the value of its FAIL_ON_CONTACT_ERROR property.

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

neither, verify, sync neither

VERIFY_SYNC_CUSTOMERS

Set to "sync" to cause InstalledProductSync to synchronize the related Customer in the destination application. InstalledProductSync performs the following process:

  1. Checks the value of the ObjectType attribute of InstalledProduct's child business object, RelatedCustomerRef. If the value is "Customer", InstalledProductSync creates a generic Customer business object.
  2. Copies the CustomerId from the InstalledProduct 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. In turn, the wrapper collaboration 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, InstalledProductSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

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

  1. Checks the value of the ObjectType attribute of InstalledProduct's child business object, RelatedCustomerRef. If the value is "Customer", InstalledProductSync creates a generic Customer business object.
  2. Copies the CustomerId from the InstalledProduct 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. In turn, the wrapper collaboration retrieves the business object from the destination application.
  4. If the wrapper collaboration fails to retrieve the Customer, InstalledProductSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

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

neither, verify, sync neither

VERIFY_SYNC_CUSTOMERPARTNERS

Set to "sync" to cause InstalledProductSync to synchronize the related CustomerPartner in the destination application. InstalledProductSync performs the following process:

  1. Checks the value of the ObjectType attribute of InstalledProduct's child business object, RelatedCustomerRef. If the value is "CustomerPartner", InstalledProductSync creates a generic CustomerPartner business object.
  2. Copies the CustomerId from the InstalledProduct 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. In turn, the wrapper collaboration 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, InstalledProductSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

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

  1. Checks the value of the ObjectType attribute of InstalledProduct's child business object, RelatedCustomerRef. If the value is "CustomerPartner", InstalledProductSync creates a generic CustomerPartner business object.
  2. Copies the CustomerId from the InstalledProduct 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. In turn, the wrapper collaboration retrieves the business object from the destination application.
  4. If the wrapper collaboration fails to retrieve the CustomerPartner, InstalledProductSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

Set to "neither" to cause InstalledProductSync to create the InstalledProduct business object without first synchronizing or verifying the related CustomerPartner in the destination application.

neither, verify, sync neither

VERIFY_SYNC_ITEM

Set to "sync" to cause InstalledProductSync to synchronize related items in the destination application. InstalledProductSync copies the ItemId (and other interesting attribute values, such as the Plant attribute) from the InstalledProduct business object and creates the type of generic business object specified in the ITEM_TYPE property. InstalledProductSync sends the business object with the Sync verb to ItemWrapper. In turn, ItemWrapper retrieves values for all attributes from the source application and sends the business object with the Create verb to ItemSync. If ItemSync fails to create the related item, InstalledProductSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

Set to "verify" to cause InstalledProductSync to verify related items in the destination application. InstalledProductSync copies the ItemId from the InstalledProduct business object and creates the type of generic business object specified in the ITEM_TYPE property. InstalledProductSync 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 a related item, InstalledProductSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

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

neither, verify, sync neither

VERIFY_SYNC_PARENT

Set to "sync" to cause InstalledProductSync to recursively locate the parent of the triggering InstalledProduct and the parent of each parent. After locating all parent business objects, InstalledProductSync synchronizes the topmost parent before synchronizing its child. The triggering business object is the last business object that the collaboration synchronizes. For more information, see Synchronization of Parent Business Objects.

Set to "verify" to cause InstalledProductSync to create or verify the existence of the triggering InstalledProduct's parent business object in the destination application. The collaboration performs this verification only if the triggering InstalledProduct's ParentId attribute contains a reference to its parent business object.

  • If the parent exists in the destination, InstalledProductSync continues to the next step in the synchronization of the triggering business object.
  • If the parent does not exist, InstalledProductSync raises an exception and stops.

Set to "neither" to cause InstalledProductSync to synchronize the triggering InstalledProduct business object without first synchronizing or verifying parent InstalledProduct business objects. neither, verify, sync neither.

neither, verify, sync neither

VERIFY_SYNC_SITE

Set to "sync" to cause InstalledProductSync to synchronize related Sites in the destination application. InstalledProductSync copies the SiteId from the InstalledProduct business object and creates the generic Site business object. InstalledProductSync sends the business object with the Sync verb to SiteWrapper. In turn, SiteWrapper retrieves values for all attributes from the source application and sends the business object with the Create verb to SiteSync. If SiteSync fails to create the related Site, InstalledProductSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

Set to "verify" to cause InstalledProductSync to verify related Sites in the destination application. InstalledProductSync copies the SiteId from the InstalledProduct business object and creates the generic Site business object. InstalledProductSync sends the business object with the Exists verb to SiteWrapper. In turn, SiteWrapper retrieves the business object from the destination application. If SiteWrapper fails to retrieve the related Site, InstalledProductSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

Set to "neither" to cause InstalledProductSync to synchronize the triggering InstalledProduct business object without first synchronizing or verifying related Sites.

   

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 current InstalledProductSync 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 InstalledProductSync 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