InventoryLevelManager Collaboration Template

The InventoryLevelManager collaboration template synchronizes inventory-level information for a particular Inventory Type from one application to another. The collaboration is designed to capture a "snapshot" of the inventory level and synchronize the quantity across multiple systems periodically.

IBM recommends:

InventoryLevelManager uses the generic InventoryLevel business object to capture an item's stock quantities for a particular Inventory Type and Stock Type.

Inventory types and stock types

An Inventory Type represents a category of inventory. Such categories allow an organization to represent inventory that is managed separately due to ownership or physical location. For example, a company might use the following Inventory Types:

Each of these Inventory Types is represented by a single instance of the generic InventoryLevel business object.

A Stock Type represents the state of the inventory. Examples of Stock Types are "Unrestricted", "Quality Inspection", "Blocked Stock", and "In-Transit". Each Inventory Type/Stock Type combination is represented by a single instance of the generic InventoryLevel business object.

Synchronizing referenced items

Although InventoryLevelManager synchronizes only inventory levels, you can configure it to call the appropriate collaborations to verify or synchronize the following related business objects:

Business object Related collaboration properties Called collaborations
Item

ItemBasic

ItemOrder

ItemPlanning

VERIFY_SYNC_ITEM ITEM_TYPE

ItemSync

ItemWrapper

Connector support

In addition to the processes that InventoryLevelManager performs, IBM WebSphere Business Integration Server Express Plus connectors can provide some of the following functionality in their role as source application:

Note: The above features are application-specific. To determine the capability of a specific application, refer to the reference 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 InventoryLevelManager. For information on standard features, ports, and configuration properties for collaboration templates, refer to the Collaboration Development Guide. For general information on creating collaboration objects refer to the System Implementation Guide.

Port information

Figure 1 illustrates InventoryLevelManager's ports as they are displayed in System Manager.

Figure 1. InventoryLevelManager collaboration ports

Note: To keep 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
InventoryLevel The destination application's connector Sends a reference-valued business object to retrieve the full-valued business object.

RetrieveByContent


Port name: From
Business object Bound to Function Verbs used
InventoryLevel 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 RetrieveByContent Update Delete


Port name: To
Business object Bound to Function Verbs used
InventoryLevel. The destination application's connector.

Sends the triggering business object out of the collaboration.

Create Update Delete


Port name: ToItemWrapper
Business object Bound to Function Verbs used
Any of the generic item business objects, such as Item, ItemBasic, ItemOrder, or ItemPlanning.
  • The From port of ItemWrapper (if VERIFY_SYNC_ITEM = "verify" or "sync").
  • The Port connector (if VERIFY_SYNC_ITEM = "neither").
Sends a reference-valued Item business object for verification or synchronization.

Sync or Exists

Setting up the collaboration object

You can use InventoryLevelManager as a stand-alone collaboration that synchronizes only InventoryLevel business objects. You can also use it in conjunction with other collaborations to cause the verification or synchronization of referenced Items.

Using InventoryLevelManager as stand-alone

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

  1. Create the InventoryLevelManager collaboration object.
  2. Bind the collaboration object's ToItemWrapper port to the destination application or to the Port connector.
  3. Bind the remaining ports as described in Port information.
  4. Keep the InventoryLevelManager collaboration object's VERIFY_SYNC_ITEM configuration property set to "neither".
  5. Set the remaining configuration properties as described in Configuration properties.  

Using InventoryLevelManager in a collaboration-object group

To verify or synchronize referenced items as part of the InventoryLevelManager process, create one of the following collaboration-object groups:


Verify Synchronize Required collaborations
Items   InventoryLevelManager, ItemWrapper
  Items InventoryLevelManager, ItemWrapper, ItemSync

Using ContractSync in a collaboration-object group

The following procedure describes setting up InventoryLevelManager as part of a collaboration-object group:

  1. Create collaboration objects from the InventoryLevelManager, ItemWrapper, and (optionally) ItemSync templates.
  2. Edit the InventoryLevelManager collaboration object to bind its ToItemWrapper port to the From port of the ItemWrapper collaboration object.
  3. Bind the remaining ports for the InventoryLevelManager collaboration object as described in this document's Port information section.
  4. Set the InventoryLevelManager collaboration object's VERIFY_SYNC_ITEM configuration property. For item verification, set it to "verify"; for item synchronization, set it to "sync".
  5. Edit the ItemWrapper collaboration object to bind its To port.
  6. 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 the InventoryLevelManager collaboration object. For item verification, go directly to step #8.

  7. For item synchronization, edit the ItemSync collaboration object to bind its ports. System Manager will have already bound its From port to the ItemWrapper collaboration object. Bind its remaining ports. For more information, see Port information in the ItemSync Collaboration reference page.
  8. Set the configuration properties for each collaboration. For more information, see:

Collaboration template processes

This section illustrates the process logic for this collaboration template:

Overall process logic

The process logic includes the following subprocesses:

Figure 2 and Figure 3 illustrate InventoryLevelManager's process logic.

Figure 2. InventoryLevelManager collaboration process logic(Part 1)

Figure 3. InventoryLevelManager collaboration process logic (Part 2)

Inherited process logic

This collaboration template uses the following standard collaboration business processes:

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

Verify or synchronize referenced items

Depending on the value of its VERIFY_SYNC_ITEM property, the collaboration sends inventoried items to the ItemWrapper collaboration for verification or synchronization. Figure 4 illustrates InventoryLevelManager's process for verifying or synchronizing referenced items.

Figure 4. Verify or synchronize items

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.

RetrieveByContent

The InventoryLevelManager collaboration can receive a triggering business object with the RetrieveByContent verb. It is assumed that a source application's business object uses this verb when it does not contain key values. The business object's map and the destination application's connector use the values in specified, meaningful attributes to return the business object from the destination application.

Design considerations for RetrieveByContent

If a business process mandates that data be retrieved by specification of non-key values, for example, a selection criteria, then the connector or connectors that integrate this process must support the RetrieveByContent verb. So, the connector must be designed to recognize that it needs to perform a retrieval of data from an application based on values that exist in non-key attributes of a business object that comes in with a RetrieveByContent verb.

This presents the problem of what to do if a non-key retrieval does not retrieve a unique object, but instead retrieves multiple objects (rows).

InterChange Server Express standard-connector functionality returns one unique object using the retrieve by key method. To make non-key retrieval possible, the following suggestions can be considered as part of the connector design:

  1. The connector must support the RetrieveByContent verb for the appropriate object.
  2. Additionally, the destination application connector can be designed so that it returns only one object for a RetrieveByContent request even though there might be multiple hits as a result of non-key retrieval (IBM's Clarify connector currently does this.)

Alternatively, if the result set (multiple objects) is desired, design changes to the IBM'sInventoryLevel business object and collaboration are required, as follow:

For example, a new business object (named InventoryLevelWrapper in this example) must be created in the repository. The InventoryLevelWrapper will have the InventoryLevel business object as a child container with cardinality 'n' and will have those attributes required for retrieval at the header level.

When the source application connector sends the InventoryLevel business object into the collaboration on a SubscriptionDelivery, the collaboration must first instantiate a new InventoryLevelWrapper object. The collaboration must then map the required attributes from the triggering business object (InventoryLevel) to the InventoryLevelWrapper's header level. This object must then be sent to the destination application for retrieval. If the destination application connector retrieves more than one inventory level, then those business objects are stored in the child container of the InventoryLevelWrapper business object and sent back to the collaboration. The collaboration must now "unpack" the InventoryLevelWrapper business object to obtain each instance of the child container. The collaboration must then send each InventoryLevel through another wrapper collaboration to the source application. After all instances of the InventoryLevel object are sent to the source application, the entire collaboration-object group ends. Figure 5 illustrates InventoryLevelManager's RetrieveByContent process.

Figure 5. InventoryLevelManager collaboration RetrieveByContent process

Compensation processing

InterChange Server Express can roll back a transaction when any step in a transactional collaboration fails. For example, when InventoryLevelManager is a member of a collaboration-object group that participates in a transactional collaboration, its actions are one subtransactional step in 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 InventoryLevelManager collaboration object is used independently of other collaborations, 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's template. To understand transaction processing in the IBM WebSphere Business Integration Server Express Plus system, see the System Implementation Guide. For information on adding transaction processing to the collaboration template, see the Collaboration Development Guide.

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

  1. Add this capability to the collaboration's template and to every 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 the collaboration object and member collaborations 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 members of a collaboration-object group to "true". Forcing the collaborations to retrieve values before changing them allows the collaborations 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 InventoryLevelManager collaboration template

Property name and explanation Possible values Default value

CONVERT_NEG

Set to "true" to cause InventoryLevelManager to adjust the value of generic InventoryLevel's AdjustedQty attribute to zero if it the value is negative.

Set to "false" to cause InventoryLevelManager to ignore the value of generic InventoryLevel's AdjustedQty attribute.

true, false false

ITEM_TYPE

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

Item, ItemBasic, ItemOrder, ItemPlanning

Item

SEND_DELETE

Set to "true" to cause InventoryLevelManager to change the verb to Delete when the AdjustedQty attribute of its triggering InventoryLevel business object evaluates to zero. Note: You must also set the USE_RETRIEVE property to "true".

Set to "false" to cause InventoryLevelManager not to change the verb to Delete.

true, false false

VERIFY_SYNC_ITEM

Set to "sync" to cause InventoryLevelManager to synchronize inventoried items in the destination application. InventoryLevelManager copies the ItemId (and other attribute values, such as the Plant attribute) from the InventoryLevel business object and creates the type of generic business object specified in the ITEM_TYPE property. InventoryLevelManager 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 inventoried item, InventoryLevelManager handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

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

Set to "neither" to cause InventoryLevelManager to synchronize the triggering InventoryLevel business object without first synchronizing inventoried items or verifying existing inventoried items in the destination application.

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 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 InventoryLevelManager 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 InventoryLevelManager 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.

Copyright IBM Corp. 1997, 2004

Copyright IBM Corp. 2004