SalesOrderProcessing Collaboration Template

SalesOrderProcessing is a core process in any business. Typically, a customer initiates a request for certain products that a company manufactures or distributes. The Customer Service Representative (CSR) records the request as a quote or order in a front-office application. The CSR then passes the information to a back-office system, which processes the order to fulfillment.

Several sub-processes can occur between the order's creation and its handoff. For example, products may be configured to suit a customer's unique requirements, a credit check may be performed to verify the customer's good standing, and an inventory availability check may be performed to verify the availability of the products being ordered.

The CSR may be empowered to carry out the different tasks before handing the order off to a back-office order management system. Alternately, the intermediate steps may be performed by the back-office system, which relies on the front-office system only to provide it with the quote or order information.

The SalesOrderProcessing collaboration abstracts the complete Order-handling business process so that it is generic. Therefore, the collaboration can be used by multiple implementations that work with multiple applications. SalesOrderProcessing is also useful when Order information is distributed across multiple systems and it is important to maintain the integrity of the data across these systems.

For example, SalesOrderProcessing handles the following business scenarios:

SalesOrderProcessing uses the generic Order business object to synchronize order data.

Synchronization of related business objects

Although it synchronizes only Orders, SalesOrderProcessing 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 FAIL_ON_CONTACT_ERROR VERIFY_SYNC_CONTACT ContactSync

ContactWrapper

Customer VERIFY_SYNC_CUSTOMERS CustomerSync

CustomerWrapper

Item

ItemBasic

ItemOrder

ItemPlanning

FIND_ALL_ITEM_ERRORS

ITEM_TYPE

VERIFY_SYNC_ITEM

ItemSync

ItemWrapper

Issues and assumptions

Collaboration object setup

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

Figure 1. SalesOrderProcessing 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
Order The 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 Order.

Retrieve


Port name: From
Business object Bound to Function Verbs used
Order 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: To
Business object Bound to Function Verbs used
Order 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 verifying or synchronizing)
  • Destination application's connector or the Port connector (if not verifying or synchronizing Items)
Used to send an Item business object for verification or synchronization

Sync Exists


Port name: ToContactWrapper
Business object Bound to Function Verbs used
Contact
  • The From port of ContactWrapper (if verifying or synchronizing)
  • Destination application's connector or the Port connector (if not verifying or synchronizing Contacts)
Used to send a 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 verifying or synchronizing)
  • Destination application's connector or the Port connector (if not verifying or synchronizing Customers)
Used to send a Customer business object for verification or synchronization

Sync Exists

Setting up the collaboration object

Using SalesOrderProcessing as stand-alone

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

  1. Create the SalesOrderProcessing collaboration object.
  2. Bind each of the collaboration object's ToBusObjWrapper ports to the Port connector.
  3. Bind the remaining ports as described in Port information.
  4. Retain the default value of "neither" for the SalesOrderProcessing collaboration object's VERIFY_SYNC_BusObj configuration property.
  5. Set the remaining collaboration properties. For more information, see Configuration properties.  

Using SalesOrderProcessing in a collaboration-object group

To verify or synchronize related Customers, header or line item Contacts, or Items as part of the SalesOrderProcessing process, you can create any combination of the following collaboration-object groups:


Verify Synchronize Required collaborations
Contacts   SalesOrderProcessing, ContactWrapper
  Contacts SalesOrderProcessing, ContactWrapper, ContactSync
Customers   SalesOrderProcessing, CustomerWrapper
  Customers SalesOrderProcessing, CustomerWrapper, CustomerSync
Items   SalesOrderProcessing, ItemWrapper
  referenced Items SalesOrderProcessing, ItemWrapper
  referenced and prerequisite Items SalesOrderProcessing, ItemWrapper, ItemSync

Using SalesOrderProcessing in a collaboration-object group

The following procedure describes the steps for setting up SalesOrderProcessing as part of a collaboration-object group: For the sake of example, these steps assume you want to synchronize Orders and only their referenced Items.

  1. Create collaboration objects from the templates for SalesOrderProcessing and for each wrapper and synchronization collaboration required. In this example, create collaboration objects for SalesOrderProcessing, ItemWrapper, and ItemSync.
  2. Edit the SalesOrderProcessing collaboration object to bind its ToBusObjWrapper ports to the appropriate wrapper collaboration object or to the Port connector. In this example, bind the ToItemWrapper port to the From port of the ItemWrapper collaboration. See the Port information section for appropriate destinations.
  3. Bind the remaining ports for the SalesOrderProcessing collaboration object as described in this document's Port information section.
  4. Set the SalesOrderProcessing collaboration object's VERIFY_SYNC_BusObj properties. In this example, set or retain these suggested values for the following properties.
  5. Set the SalesOrderProcessing collaboration object's ITEM_TYPE to the desired item type, and set it's FIND_ALL_ITEM_ERRORS 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 SalesOrderProcessing'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. 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:

For more information, see Figure 4. Figure 2 illustrates SalesOrderProcessing's process logic.

Figure 2. SalesOrderProcessing 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 customers and contacts

Figure 3 illustrates SalesOrderProcessing's process for verifying or synchronizing Customers, Header Contacts, and Line Item Contacts. SalesOrderProcessing calls its wrapper collaborations in the following order: Customer, Contact (for header contacts), Item, Contact (for line-item contacts).

Figure 3. Verification or synchronization of Customers, Header Contacts, and Line Item Contacts

Verification or synchronization of items

Figure 4 illustrates SalesOrderProcessing's process for verifying or synchronizing related items.

Figure 4. Verification or synchronization of 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.

Compensation processing

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

Property name and explanation Possible values Default value

FAIL_ON_CONTACT_ERROR

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

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

true, false true

FIND_ALL_ITEM_ERRORS

Set to "true" to cause SalesOrderProcessing to continue verifying all Items if VERIFY_SYNC_ITEM evaluates to "verify", USE_RETRIEVE evaluates to "true", and ItemWrapper fails to verify a referenced Item. After verifying all Items, SalesOrderProcessing enters an exception or the email process for error handling.

Set to "false" to cause SalesOrderProcessing to stop processing if VERIFY_SYNC_ITEM evaluates to "verify", USE_RETRIEVE evaluates to "true", and ItemWrapper fails to verify a referenced Item.

true, false false

ITEM_TYPE

Set to the type of generic Item whose existence should be synchronized or verified before the collaboration synchronizes the Order business object. If its VERIFY_SYNC_ITEM property evaluates to "sync" or "verify", SalesOrderProcessing 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 SalesOrderProcessing to synchronize related Contacts in the destination application. SalesOrderProcessing copies the ContactId from each of Order's ContactRef child business objects and creates a generic Contact business object for each referenced Contact. SalesOrderProcessing sends each Contact business object with the Sync verb to ContactWrapper. In turn, ContactWrapper retrieves values 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 SalesOrderProcessing depends on the value of its FAIL_ON_CONTACT_ERROR property.

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

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

neither, verify, sync neither

VERIFY_SYNC_CUSTOMERS

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

  1. Copies the CustomerId from the Order business object and uses it as the unique identifier of the newly created generic Customer business object.
  2. 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.
  3. If the synchronization collaboration fails to create the Customer, SalesOrderProcessing handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

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

  1. Copies the CustomerId from the Order business object and uses it as the unique identifier of the newly created generic Customer business object.
  2. Sends the business object with the Exists verb to CustomerWrapper. In turn, the wrapper collaboration retrieves the business object from the destination application.
  3. If the wrapper collaboration fails to retrieve the Customer, SalesOrderProcessing handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

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

neither, verify, sync neither

VERIFY_SYNC_ITEM

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

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

Set to "neither" to cause SalesOrderProcessing to synchronize the triggering Order business object without first synchronizing related items or verifying existing related 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 SalesOrderProcessing 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 SalesOrderProcessing 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