ProductInstallation Collaboration Template

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

ProductInstallation can help a 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 companies that use ProductInstallation use front-office and back-office applications in the following ways:

When the back office application ships a product that is managed as part of the install base, the event sends out the generic InstallShipment business object. InstallShipment triggers ProductInstallation, which creates an installed product object in the front office application. The front office application then handles any cases, contracts, and invoices for the installed product.

Although the generic InstallShipment business object, to which ProductInstallation subscribes, contains only delivery information, InstallShipment was designed to contain sufficient information for ProductInstallation to create InstalledProduct business objects. ProductInstallation sends InstalledProduct business objects to the destination application.

Note: To allow modification or deletion of InstalledProducts or to allow verification or synchronization of referenced business objects (Contacts, Customers, CustomerPartners, Items, and Sites), bind ProductInstallation's Send port to InstalledProductSync. For more information, see Port information.

Issues and assumptions

Collaboration object setup

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

Port information

Figure 1 illustrates ProductInstallation's ports, as they are displayed in System Manager. The tables that follow Figure 1 provide information about each port.

Figure 1. ProductInstallation 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
N/A Port connector ProductInstallation does not use this port. Because it does not retrieve a business object from the destination, retain the default value of "false" for the USE_RETRIEVE property. N/A

Port name: From
Business object Bound to Function Verbs used
InstallShipment Source application's connector or calling collaboration. Receives the triggering business object.

Create Retrieve Update Delete


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

Destination application's connector (if only creating InstalledProducts)

The From port of InstalledProductSync (to allow modification and deletion of InstalledProducts and to allow the verification or synchronization of referenced Contacts, Customers, CustomerPartners, Items, and Sites)

Sends out of the collaboration one InstalledProduct business object for each business object contained in InstallShipment's array of InstallShipmentLine business objects.

Create

Setting up the collaboration object

Using ProductInstallation as stand-alone

Use ProductInstallation stand-alone if your back-office application handles only order fulfillment (processes deliveries) and you do not need to verify or synchronize Contacts, Customers, CustomerPartners, Items, or Sites that are referenced on the triggering delivery object. To create ProductInstallation as a stand-alone collaboration object, follow these steps:

  1. Create the ProductInstallation collaboration object.
  2. Bind the collaboration object's From port to the source application's connector and its To port to the destination application's connector.
  3. Bind the DestinationAppRetrieve port to the Port connector, as described in Port information.
  4. Retain the default value of "false" for ProductInstallation's ADDITIONAL_RETRIEVE, CONVERT_CREATE, CONVERT_UPDATE, and USE_RETRIEVE configuration properties.
  5. To enable filtering, set the filtering properties. To specify exception handling, set the INFORMATIONAL_EXCEPTIONS, and SEND_EMAIL properties. For more information, see Configuration properties.  

Using ProductInstallation in a collaboration-object group

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


Verify Synchronize Required collaborations
Contacts   ProductInstallation, InstalledProductSync, ContactWrapper
  Contacts ProductInstallation, InstalledProductSync, ContactWrapper, ContactSync
Customers   ProductInstallation, CustomerWrapper
  Customers ProductInstallation, InstalledProductSync, CustomerWrapper, CustomerSync
CustomerPartners   ProductInstallation, InstalledProductSync, CustomerPartnerWrapper
  CustomerPartners ProductInstallation, InstalledProductSync, CustomerPartnerWrapper, CustomerPartnerSync
Items   ProductInstallation, InstalledProductSync, ItemWrapper
  Items ProductInstallation, InstalledProductSync, ItemWrapper, ItemSync
Sites   ProductInstallation, InstalledProductSync, SiteWrapper
  Sites ProductInstallation, InstalledProductSync, SiteWrapper, SiteSync
  InstalledProducts (Update and Delete, as well as Create) ProductInstallation, InstalledProductSync

Using ProductInstallation in a collaboration-object group

The following procedure describes the steps for setting up ProductInstallation as part of a collaboration-object group:

  1. Create collaboration objects from the templates for ProductInstallation and for each wrapper and synchronization collaboration required.
  2. Edit the ProductInstallation collaboration object to bind its To port to InstalledProductSync's From port and its From port to the source application's connector.
  3. Bind the ports of each collaboration object that is a member of the collaboration-object group. For more information, see the Port Information section of each collaboration's reference document.
  4. Set ProductInstallation's collaboration properties.
  5. Set each member collaboration object's collaboration properties. For more information, see the Configuration Properties section of each collaboration's reference document.

Collaboration template processes

This section illustrates the process logic for this collaboration template:

Overall process logic

The main business process includes synchronizing a hierarchy of InstalledProduct business objects. Figure 2 illustrates ProductInstallation's main business process.

Figure 2. ProductInstallation collaboration main business process

ProductInstallation is triggered by InstallShipment, which has a multiple-cardinality child business object named InstallShipmentLine. For each InstallShipmentLine child business object, ProductInstallation sends out a corresponding InstalledProduct with the Create verb through its To port. ProductInstallation first sends the topmost-parent InstalledProduct business object, that is, the parent that has no parent of its own. The collaboration next sends that business object's immediate child. Then it sends the next immediate child, until it finally sends an InstalledProduct for each contained InstallShipmentLine.

Note: For ProductInstallation to send the parent business objects in the correct order, the array of InstallShipmentLine business objects must be ordered with the topmost parent at the top, followed by its immediate child. Every child business object must be followed by its own immediate child. The last business object in the array must be the child that has no child of its own.

To understand the collaboration's process, assume that InstallShipmentLine contains three business objects. In such a case, ProductInstallation processes the following steps:

  1. Gets the first business object from the array of InstallShipmentLine business objects and creates an InstalledProduct business object from it. The first InstallShipmentLine business object should have no parent, that is, its LineNoOfParent attribute evaluates to null. The first InstalledProduct business object that ProductInstallation creates contains a null in its ParentId attribute and a value of 1 in its HierarchyLevel attribute.
  2. Sends the InstalledProduct business object with the Create verb through its To port.
  3. If the Create is successful, prepares an InstalledProduct business object from the next child InstallShipmentLine. It uses the value of the ObjectId attribute of the previously sent InstalledProduct to identify the parent of the current business object. It also increments the value of the HierarchyLevel attribute by 1, and populates all attributes. It sends out the second InstalledProduct.
  4. If the Create is successful, repeats step 3 for the third InstallShipmentLine business object.

Inherited process logic

This collaboration template uses the following standard collaboration business processes:

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

Compensation processing

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

The ProductInstallation collaboration template uses only standard collaboration properties. Not only does it not have properties specific to its processing, but it does not use all of its standard properties. For example, because ProductInstallation performs only Create operations and does not retrieve its triggering InstallShipment business object from the destination application, you need not change the default configuration of its CONVERT_CREATE, CONVERT_UPDATE, ADDITIONAL_RETRIEVE, and USE_RETRIEVE properties.

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.

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 ProductInstallation 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 ProductInstallation 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