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.
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 | |
VERIFY_SYNC_CUSTOMERS | CustomerSync CustomerWrapper | |
CustomerPartner | VERIFY_SYNC_CUSTOMERPARTNERS | CustomerPartnerSync CustomerPartnerWrapper |
Item
ItemBasic ItemOrder ItemPlanning |
ItemSync | |
Site |
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.
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.
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.
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.
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
To set up InstalledProductSync as a stand-alone collaboration object, follow these steps:
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.
If synchronizing Contacts, Customers, or CustomerPartners, configure their associated collaborations in the same manner as shown in the steps above.
This section illustrates the process logic for this collaboration template:
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
This collaboration template uses the following standard collaboration business processes:
For information on these processes, see the Collaboration Development Guide.
If VERIFY_SYNC_PARENT evaluates to "verify" or "sync", InstalledProductSync performs the following steps:
Figure 3 illustrates InstalledProductSync's process for synchronizing parent InstalledProducts.
Figure 3. Process for synchronizing parent InstalledProducts
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
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:
This section describes the standard properties and collaboration template-specific properties for this collaboration template:
This collaboration template uses the following standard configuration properties for collaboration templates:
For information on these configuration properties, see the Collaboration Development Guide.
In addition to its standard configuration properties, this collaboration template has the configuration properties described below.
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:
Set to "verify" to cause InstalledProductSync to verify the related Customer in the destination application. InstalledProductSync performs the following process:
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:
Set to "verify" to cause InstalledProductSync to verify the related CustomerPartner in the destination application. InstalledProductSync performs the following process:
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.
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. |
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:
To upgrade to a newer version of the collaboration template, perform the following steps: