ItemSync Collaboration Template

Item information is critical to the operation of enterprise application systems throughout an organization and the organization's extended partner network, including suppliers, distributors, resellers, and customers. Item information is typically duplicated in systems that support different business functions or different businesses, such as Planning, Purchasing, Inventory, Manufacturing, Sales and Distribution, and Support.

The ItemSync collaboration maintains the integrity of item information that is replicated across multiple systems, ensuring that all systems are updated with the most current item information.

An item is generally maintained over time, from its beginning as a new product or as a component of a new or improved item, through extensions required by use. If the item is valued and held in inventory, the definition of the item is extended with costing data. If the item is included in Material Requirements Planning (MRP), additional properties are defined to allow necessary calculations to be performed. In order for an item to be referenced in a sales or service order, additional properties are added.

Figure1 illustrates how multiple organizations can define and modify item information. IBM provides separate generic business objects to represent the different requirements used by different operations. Some of these business objects serve as prerequisites for others. Only the organizations within the dotted rectangle are not currently supported.

Figure 1. Item life cycle: organizations and operations

To synchronize critical information throughout the item life cycle, the ItemSync collaboration supports the following generic business objects:

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.

ItemSync synchronizes data from an Enterprise Resource Planning (ERP) application to front-office systems, such as a Customer Interaction Management (CIM) application, and to Supply Chain (SC) systems. An ERP system serves as the source because it generally provides an extensive set of functions that cause it to be the "system of record". For example, modules in the ERP application price the item for sale, track it from raw to finished product, and track its storage location to the desired level of detail.

ItemSync has configuration properties that enable you to limit the data processed. You can specify whether to apply filter data and whether to verify or synchronize prerequisite information before synchronizing the item. For example, you can specify that the planning data for an item must be created before the item can be used on a sales order.

Note: ItemSync does not support Bill of Material (BOM) data or revision information associated with engineering changes.

Collaboration object setup

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

Figure 2. Item Manager 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
ItemOrder, ItemPlanning, or any supported generic item business object Destination application's connector Sends a reference-valued business object to retrieve the full-valued business object. Retrieval is based on the ID contained in the referencing business object. The result determines the verb to use when synchronizing the triggering or a prerequisite business object.

Retrieve


Port name: From
Business object Bound to Function Verbs used
Item, ItemBasic, ItemOrder, ItemPlanning, or any supported generic item business object Source application's connector or the To port of a calling collaboration Receives any supported generic Item business object from another collaboration, usually the ItemWrapper collaboration. This port is useful when you do not know what type of Item business object will trigger ItemSync at the time you configure this collaboration. For example, if another collaboration calls ItemWrapper to synchronize Items referenced on its triggering business object and ItemWrapper calls ItemSync, the type of triggering Item is determined only at runtime.

Create Update Delete


Port name: FromItemBasic
Business object Bound to Function Verbs used
ItemBasic Source application's connector

Receives the triggering ItemBasic 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 Update Delete


Port name: FromItemOrder
Business object Bound to Function Verbs used
ItemOrder Source application's connector Receives the triggering ItemOrder 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 Update Delete


Port name: FromItemPlanning
Business object Bound to Function Verbs used
ItemPlanning Source application's connector Receives the triggering ItemPlanning 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 Update Delete


Port name: SourceApp
Business object Bound to Function Verbs used
ItemBasic, ItemOrder, ItemPlanning, or any supported generic item business object Source application's connector

Sends a reference-valued business object to retrieve a full-valued prerequisite business object based on the ID contained in the referencing business object

Retrieve


Port name: To
Business object Bound to Function Verbs used
Item, ItemBasic, ItemOrder, ItemPlanning, or any supported generic item business Destination application's connector

Sends the full-valued triggering business object or one of its prerequisite business objects out of the collaboration

Create Update Delete

Determining the triggering port

If you create an ItemSync collaboration object that can be triggered by any of the generic Item business objects, bind its FromItemBasic, FromItemOrder, and FromItemPlanning ports to the source connector and bind its From port to the Port connector.

If you create an ItemSync collaboration object that can be triggered by only one of the generic Item business objects, bind only the relevant port to the source connector and bind the three alternate triggering ports to the Port connector. For example, if its source connector will send only ItemOrder business objects, bind ItemSync's FromItemOrder port to the source connector. Bind its FromItemBasic, FromItemPlanning, and From ports to the Port connector.

If you create an ItemSync collaboration object as part of a collaboration-object group such that ItemSync is triggered by an ItemWrapper collaboration object, the type of triggering business object is determined only at runtime. The generic Item business object, which behaves like a superclass, allows the collaboration to receive any type of supported generic Item business object. In this case, bind the From port to ItemWrapper's To port and bind the FromItemBasic, FromItemOrder, and FromItemPlanning ports to the Port connector.

Setting up the collaboration object

Using ItemSync as stand-alone

If you do not use ItemSync in conjunction with another collaboration to synchronize Items that are referenced on the other collaboration's triggering business object, you can use ItemSync stand-alone. To use ItemSync stand-alone, do the following:

  1. Create the ItemSync collaboration object.
  2. Bind each of the collaboration object's ports as described in Port information.
  3. Set the Configuration properties for ItemSync.  

Using ItemSync in a collaboration-object group

If you use ItemSync in conjunction with another collaboration so that related items are synchronized along with the other collaboration's triggering business object, ItemSync becomes part of a collaboration-object group. To use ItemSync as part of a collaboration-object group, do the following:

  1. Create collaboration objects from the templates for ItemSync, ItemWrapper, and the calling collaboration.
  2. Bind ItemSync's From port to ItemWrapper's To port.
  3. Bind the calling collaboration's ToItemWrapper port to ItemWrapper's From port.
  4. Bind the remaining ports for each collaboration object as described in its Port Information section.
  5. Configure each collaboration object as described in its Configuration Properties section.
 

Collaboration template processes

This section illustrates the process logic for this collaboration template:

Note: ItemSync does not include a Retrieve scenario.

Overall process logic

The process logic includes the following subprocesses:

Figure 3 illustrates ItemSync's process logic.

Figure 3. ItemSync 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 and synchronization of prerequisites

Figure 4 illustrates the synchronization of prerequisites.

Figure 4. Synchronization of prerequisites

ItemSync evaluates its VERIFY_SYNC_PREQ property only if its triggering verb is Create.

If VERIFY_SYNC_PREQ evaluates to "verify" or "sync", ItemSync checks the value of its RETRIEVE_PREQ property.

RETRIEVE_PREQ Evaluates to "true"

If RETRIEVE_PREQ evaluates to "true", ItemSync loops through its list of prerequisite business objects and retrieves each one from the destination application. The collaboration's behavior depends on the success of the retrieval.

Figure 5. Example of prerequisite hierarchy

As illustrated, ItemShipping has two prerequisites (ItemOrder and ItemPlanning) and ItemOrder has two prerequisites (ItemBasic and ItemCost). If ItemSync retrieves ItemOrder successfully, it removes ItemOrder, ItemCost, and ItemBasic from its list of prerequisites. However, if it fails to retrieve ItemOrder, it attempts to retrieve ItemCost and ItemBasic. If it succeeds in retrieving them, it removes them from its list of prerequisites, but keeps ItemOrder. If it fails to retrieve either ItemCost or ItemBasic, it keeps ItemOrder and its failed prerequisite on the list.

If ItemSync has failed to retrieve ItemPlanning from the destination, the collaboration keeps ItemPlanning on its list of prerequisites. If it has succeeded, it removes it from the list.

For each prerequisite still on the list, ItemSync retrieves the full business object from the source application. If it succeeds, ItemSync sends the prerequisite through the filtering process and then to the destination application with the Create verb.

RETRIEVE_PREQ Evaluates to "false"

If RETRIEVE_PREQ evaluates to "false", ItemSync does not loop through the list of prerequisites and retrieve each one from the destination application. Therefore, IBM recommends setting RETRIEVE_PREQ to "false" only if you also set VERIFY_SYNC_PREQ to "sync". Because it is not configured to retrieve from the destination if RETRIEVE_PREQ evaluates to "false", the collaboration follows the same process regardless of whether VERIFY_SYNC_PREQ evaluates to "verify" or to "sync". ItemSync loops through the list of prerequisite business objects and performs the following steps for each prerequisite:

  1. Gets the prerequisite business object from the source.
  2. If successful, puts the prerequisite business object through the filtering process.
  3. If successful, sends the prerequisite business object to the destination application with the Create verb. If the prerequisite business object is successfully created in the destination application, ItemSync continues to the next step. If the prerequisite business object is not successfully created in the destination application, ItemSync evaluates its CONVERT_CREATE property. If CONVERT_CREATE evaluates to "true", ItemSync sends the prerequisite business object to the destination application with the Update verb and continues to the next step. If CONVERT_CREATE evaluates to "false", ItemSync raises an exception.

Compensation processing

InterChange Server Express can roll back a transaction when any step in a transactional collaboration fails. For example, when ItemSync 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 ItemSync 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. To understand transaction processing in the IBM WebSphere Business Integration Server Express Plus system, see the System Implementation Guide. For information about adding transaction processing to the collaboration template, see the Collaboration Development Guide.

To extend the collaboration object to handle transaction processing, complete the following steps:

  1. Add this capability to the collaboration template and to every other collaboration template in the collaboration-object group.
  2. Set the minimum transaction level of the collaboration object and all members of the collaboration-object group to a value higher than None. If a failure occurs in any subtransaction step, settings of Minimal Effort or higher cause this collaboration object and other collaboration objects in the group to execute compensation for Create, Update, and Delete operations performed on all business objects.
  3. Set the USE_RETRIEVE property of the collaboration object and all other members of the collaboration-object group to "true". Forcing the collaboration objects to retrieve values before changing them allows the collaboration objects to restore the original values in an Update or Delete process.

Configuration properties

This section describes the standard properties and collaboration template-specific properties for this collaboration template:

Standard properties

This collaboration template uses the following standard configuration properties for collaboration templates:

For information on these configuration properties, see the Collaboration Development Guide.

Properties specific to this collaboration template

In addition to its standard configuration properties, this collaboration template has the configuration properties described below.

Configuration properties specific to the ItemSync collaboration template

Property name and explanation Possible values Default value

PREQ_ITEMORDER

Because IBM considers ItemBasic to be a prerequisite for ItemPlanning and ItemOrder, PREQ_ITEMORDER specifies ItemBasic as its first prerequisite. To cause ItemSync to synchronize or verify ItemPlanning in addition to ItemBasic, specify ItemPlanning as the second prerequisite.

Note: ItemSync processes prerequisites in the order in which they are specified. In the following example, ItemSync processes ItemBasic before processing ItemPlanning: PREQ_ITEMORDER = {ItemBasic,ItemPlanning} To cause ItemSync not to synchronize prerequisites for ItemOrder, remove ItemBasic as the prerequisite. For example: PREQ_ITEMORDER = {}

type1, type2, .., typeN ItemBasic

PREQ_ITEMPLANNING

Because IBM considers ItemBasic to be a prerequisite for ItemPlanning and ItemOrder, PREQ_ITEMPLANNING specifies ItemBasic as its first prerequisite. To cause ItemSync to synchronize or verify ItemOrder in addition to ItemBasic, specify ItemOrder as the second prerequisite.

Note: ItemSync processes prerequisites in the order in which they are specified. In the following example, ItemSync processes ItemBasic before processing ItemOrder: PREQ_ITEMPLANNING = {ItemBasic,ItemOrder} To cause ItemSync not to synchronize prerequisites for ItemPlanning, remove ItemBasic as the prerequisite. For example: PREQ_ITEMPLANNING = {}

type1, type2, .., typeN ItemBasic

RETRIEVE_PREQ

Set to "true" to cause ItemSync to retrieve prerequisite business objects from the destination prior to processing the triggering business object. If RETRIEVE_PREQ evaluates to "true" and ItemSync successfully retrieves the prerequisites from the destination, ItemSync sends the prerequisites through the filtering process before processing the triggering business object. If RETRIEVE_PREQ evaluates to "true" and ItemSync does not successfully retrieve any prerequisite from the destination, ItemSync's behavior depends upon the setting of its VERIFY_SYNC_PREQ property.

Set to "false" to cause ItemSync not to retrieve prerequisite business objects from the destination prior to processing them. If RETRIEVE_PREQ evaluates to "false", ItemSync uses the IDs contained in the triggering business object to get each prerequisite from the source application. ItemSync sends each prerequisite to the destination with the Create verb. For each prerequisite whose creation succeeds, ItemSync sends the prerequisite through the filtering process.

For each prerequisite whose creation fails, ItemSync's behavior depends upon the setting of its CONVERT_CREATE property. For more information on the how this property affects the business process, see Figure 4.

true, false

true

VERIFY_SYNC_PREQ

Set to "sync" to cause ItemSync to synchronize prerequisite items in the destination application. ItemSync's behavior depends on the setting of its RETRIEVE_PREQ property.

If RETRIEVE_PREQ evaluates to "true" and VERIFY_SYNC_PREQ evaluates to "sync", ItemSync loops through its list of immediate prerequisite business objects and retrieves each one from the destination application. The collaboration's behavior depends on the success of the retrieval.

  • If ItemSync retrieves all prerequisites successfully, it moves to the filtering process.
  • If it fails to retrieve any prerequisite, ItemSync evaluates its list of prerequisites. If the failed prerequisite has a prerequisite that was successfully retrieved, ItemSync removes the failed prerequisite from the list.

For example, assume you have created ItemShipping and ItemCost business objects as illustrated in Figure 5. ItemShipping has two prerequisites (ItemOrder and ItemPlanning) and ItemOrder has two prerequisites (ItemBasic and ItemCost). If ItemSync retrieves ItemOrder successfully, it removes ItemOrder, ItemCost, and ItemBasic from its list of prerequisites. However, if it fails to retrieve ItemOrder, it attempts to retrieve ItemCost and ItemBasic. If it succeeds in retrieving them, it removes them from its list of prerequisites, but keeps ItemOrder. If it fails to retrieve either ItemCost or ItemBasic, it keeps ItemOrder and its failed prerequisite on the list.

If ItemSync has failed to retrieve ItemPlanning from the destination, the collaboration keeps ItemPlanning on its list of prerequisites. If it has succeeded, it removes it from the list.

For each prerequisite still on the list, ItemSync retrieves the full business object from the source application. If it succeeds, ItemSync sends the prerequisite through the filtering process and then to the destination application with the Create verb.

o If the creation succeeds, ItemSync continues to the next step.

o If the creation fails, ItemSync raises an exception. Its behavior depends on the setting of its INFORMATIONAL_EXCEPTIONS and SEND_EMAIL properties.

If RETRIEVE_PREQ evaluates to "false" and VERIFY_SYNC_PREQ evaluates to "sync", ItemSync loops through the list of prerequisite business objects and performs the following steps for each prerequisite:

  1. Gets the prerequisite business object from the source.
  2. If successful, puts the prerequisite business object through the filtering process.
  3. If successful, sends the prerequisite business object to the destination application with the Create verb.
    • If the prerequisite business object is successfully created in the destination application, ItemSync continues to the next step.
    • If the prerequisite business object is not successfully created in the destination application, ItemSync evaluates its CONVERT_CREATE property. If CONVERT_CREATE evaluates to "true", ItemSync sends the prerequisite business object to the destination application with the Update verb and continues to the next step. If CONVERT_CREATE evaluates to "false", ItemSync raises an exception.

Set to "verify" to cause ItemSync to verify prerequisite items in the destination application. ItemSync's behavior depends on the setting of its RETRIEVE_PREQ property.

  • If RETRIEVE_PREQ evaluates to "true", ItemSync loops through all specified prerequisites and retrieves them from the destination application. If any prerequisite fails retrieval, ItemSync raises an exception and stops. ItemSync's behavior depends on the setting of its INFORMATIONAL_EXCEPTIONS and SEND_EMAIL properties.
  • If RETRIEVE_PREQ evaluates to "false", ItemSync cannot retrieve prerequisites from the destination in order to verify them. Therefore, IBM recommends setting RETRIEVE_PREQ to "false" only if you also set VERIFY_SYNC_PREQ to "sync". Because it is not configured to retrieve from the destination if RETRIEVE_PREQ evaluates to "false", the collaboration follows the same process regardless of whether VERIFY_SYNC_PREQ evaluates to "verify" or to "sync". For information on this process, see the discussion for RETRIEVE_PREQ evaluates to "false".

Set to "neither" to cause ItemSync to synchronize the triggering generic item business object without first synchronizing or verifying prerequisite items in the destination application.

Note: For more information on this property's usage, see Figure 4.

neither, verify, sync neither

Collaboration messages

To view an explanation of the messages of this collaboration template, launch the Log Viewer and open the collaboration template's message file. To launch the Log Viewer and open the collaboration template's message file:

  1. In the Start menu, click Programs > IBM WebSphere Business Integration Express > Toolset Express > Administrative > Log Viewer.
  2. In the File menu, click Open.
  3. Use the Look In field to change the current folder to ProductDir\collaborations\messages and select the message file for this collaboration template.

Implementation notes

This section provides information about the following topics: " Expansion of ItemSync's capability " Consistency of generic Item business objects

Expansion of ItemSync's capability

ItemSync is sufficiently flexible to process generic business objects that did not exist when the collaboration was developed. For example, ItemSync does not currently support the synchronization of item shipping, cost, inventory, and purchase order data. If you create additional generic item business objects to represent this data, you can modify the collaboration template to accept them as triggering business objects or as prerequisites.

For example, assume you have created ItemShipping and ItemCost business objects as illustrated in Figure 5. ItemShipping has two prerequisites (ItemOrder and ItemPlanning) and ItemOrder has two prerequisites (ItemBasic and ItemCost). Assume further that you want creation or modification of ItemShipping in the source application to trigger the ItemSync collaboration.

To expand the collaboration template's capability to take advantage of your two new business objects, make the following changes:

Modifying collaboration properties

If you create a new generic business object that serves as the prerequisite for an existing business object, you must modify the collaboration property for the existing business object to recognize its new prerequisite. For example, if you create the ItemCost business object and wish it to function as a prerequisite to ItemOrder, you must modify the PREQ_ITEMORDER property to include ItemCost as well as ItemBasic.

The prerequisite list contains the prerequisites in the order in which ItemSync processes them. In the following example, ItemSync processes ItemBasic before processing ItemCost: PREQ_ITEMORDER = {ItemBasic,ItemCost}.

Creating new collaboration properties

Create a new collaboration property when you create a new business object that has its own set of prerequisites. For example, if you create the ItemShipping business object, you must create the PREQ_ITEMSHIPPING property to specify the new business object's prerequisites: ItemOrder and ItemPlanning.

Notes:

Adding new collaboration ports

If you create a new generic business object that you want to trigger the ItemSync collaboration, you must add a triggering port to the collaboration template.

Note: Before you add the port, you must have already created your user-defined business object and mapped it to an application-specific business object.

When adding a port to a collaboration template, use the same naming convention as its related ports. The naming convention for ItemSync's triggering ports for specific business objects is: FromBusObjName.

Consistency of generic item business objects

The generic ItemBasic, ItemOrder, and ItemPlanning business objects contain the same key attributes. Because ItemSync can process prerequisite item business objects as well as the triggering item business object, it is important that these key attributes remain consistent in the generic business objects. If you modify the key attributes, modify them consistently.

Upgrade information

Upgrade process

To upgrade to a newer version of the collaboration template, perform the following steps:

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