ARInvoiceSync collaboration template

The ARInvoiceSync collaboration template synchronizes accounts-receivable invoice information from a Customer Interaction Management (CIM) application into an Enterprise Resource Planning (ERP) application. The collaboration is intended to ensure that information from accounting and general ledger (GL) transactions is accurately posted into the appropriate financial accounts of a single application, such as SAP, that serves as a system of record.

The collaboration is designed to synchronize information into the application that serves as a system of record, but not to extract information out of that application.

ARInvoiceSync uses the generic ARInvoice business object, which represents accounts-receivable invoice information in a Finance system application.

Synchronization of related business objects

Although it synchronizes only ARInvoice business object data, ARInvoiceSync can be configured to call the appropriate collaborations to verify or synchronize the following related business objects:

Business object Related collaboration properties Called collaborations
Customer VERIFY_SYNC_CUSTOMERS CustomerSync

CustomerWrapper

Item

Item Basic

Item Order

Item Planning

VERIFY_SYNC_ITEM ITEM_TYPE ItemSync

ItemWrapper

Note: If you configure ARInvoiceSync to synchronize Customer, CustomerPartner, or Item, create and bind the appropriate collaboration objects before you configure ARInvoiceSync. For more information, see Collaboration object setup.

Collaboration object setup

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

Figure 1. ARInvoiceSync collaboration object 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
ARInvoice 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 ARInvoice.

Retrieve


Port name: From
Business object Bound to Function Verbs used
ARInvoice 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
ARInvoice The destination application's connector

Sends the triggering business object out of the collaboration

Note: This collaboration template is designed to support only the Create and Delete verbs. Because it follows collaboration standards and contains the Update scenario, you can use it to process updates if you modify the business object to use the Update verb.

Create

Update

Delete


Port name: ToCustomerPartnerWrapper
Business object Bound to Function Verbs used
CustomerPartner

The From port of CustomerPartnerWrapper (if verifying or synchronizing)

Port connector (if not verifying or synchronizing).

Used to send a reference-valued CustomerPartner 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).

Used to send a reference-valued Customer business object for verification or synchronization.

Sync

Exists


Port name: ToItemWrapper
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 verifying or synchronizing)

Port connector (if not verifying or synchronizing).

Used to send a reference-valued Item business object for verification or synchronization.

Sync

Exists

Setting up the collaboration object

Using ARInvoiceSync as stand-alone

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

  1. Create the ARInvoice collaboration object.
  2. Bind each of the collaboration object's ToBusObjWrapper ports to the destination application's connector or to the Port connector.
  3. Bind the remaining ports as described in Port information.
  4. Retain the default value of "neither" for the ARInvoiceSync collaboration object's VERIFY_SYNC_BusObj configuration properties.
  5. Set the remaining Configuration properties for ARInvoiceSync.

Using ARInvoiceSync in a collaboration-object group

To verify or synchronize related Customers, CustomerPartners, or items as part of the ARInvoiceSync process, you can create any combination of the following collaboration-object groups:


Verify Synchronize Required collaborations
Customers   ARInvoiceSync, CustomerWrapper
  Customers ARInvoiceSync, CustomerWrapper, CustomerSync
CustomerPartners   ARInvoiceSync, CustomerPartnerWrapper
  CustomerPartners ARInvoiceSync, CustomerPartnerWrapper, CustomerPartnerSync
Items   ARInvoiceSync, ItemWrapper
  Items ARInvoiceSync, ItemWrapper, ItemSync

Creating collaboration objects

The following procedure describes the initial steps for setting up ARInvoiceSync as part of a collaboration-object group. For the purpose of this example, these steps assume you want to synchronize the ARInvoice business object and its related Customers and Items.

  1. Create collaboration objects from the templates for ARInvoiceSync and for each wrapper and synchronization collaboration required. Example: Create collaboration objects for ARInvoiceSync, CustomerWrapper, CustomerSync, ItemWrapper, and ItemSync.
  2. Edit the ARInvoiceSync collaboration object to bind its ToBusObjWrapper ports to the appropriate wrapper collaboration object or to the Port connector. Example: Bind the ToItemWrapper and ToCustomerWrapper ports to the From ports of the ItemWrapper and CustomerWrapper collaborations, respectively. See the Port information section for appropriate destinations.
  3. Bind the remaining ports for the ARInvoiceSync collaboration object as described in this document's Port information section.
  4. Set the ARInvoiceSync collaboration object's VERIFY_SYNC_BusObj properties. Example: To synchronize Customers and Items, set these suggested values for the following properties:
  5. Set the ARInvoiceSync collaboration object's ITEM_TYPE property to the desired item type.

Completing the setup of the ARInvoiceSync collaboration-object group

The steps provided below assume that you have already created collaboration objects from the templates for ARInvoiceSync and for each required wrapper and synchronization collaboration. For example, to synchronize ARInvoice and related Items and Customers, you have created collaboration objects for ARInvoiceSync, ItemWrapper, ItemSync, CustomerWrapper, and CustomerSync. The following steps complete the setup procedure for synchronizing ARInvoice, Items, and Customers:

  1. Configure the ItemWrapper collaboration object to bind its To port to the From port of the ItemSync collaboration object.
  2. 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 ARInvoiceSync collaboration object.
  3. Edit the ItemSync collaboration object to bind its ports. For more information, see Port information in the ItemSync Collaboration reference page.
  4. Edit the CustomerWrapper collaboration object to bind its To port to the From port of the CustomerSync collaboration object.
  5. Bind the CustomerWrapper collaboration object's remaining ports. For more information, see Port information in the Wrapper Collaboration reference page.
  6. Edit the CustomerSync collaboration object to bind its ports. For more information, see Port information in the CustomerSync Collaboration reference page.
  7. Set the configuration properties for each collaboration object. For more information, see:

Collaboration template processes

This section illustrates the process logic for this collaboration template:

Overall process logic

Figure 2 illustrates ARInvoiceSync's process logic.

Figure 2. ARInvoiceSync collaboration template's 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.

Verifying or synchronizing referenced customers and items

Figures 3 and 4 show the VERIFY_SYNC process.

Figure 3. ARInvoiceSync collaboration process for verifying or synchronizing customers and CustomerPartners

Figure 4. ARInvoiceSync collaboration process for verifying or synchronizing items

Note: For a collaboration to process ItemBasic, ItemOrder, and ItemPlanning successfully, your installation's repository must contain the following business objects:

Updating references to customers and items

When ARInvoiceSync sends the ARInvoice business object with the Update verb to the destination, the synchronization updates relationships to Customers or Items, but it does not actually create, update or delete a Customer or Item.

For example, when an ARInvoice deletes a reference to a Customer or Item, the application does not delete the Customer or Item (neither physical nor logical delete). The application simply removes the reference to the Customer or Item; it removes the relationship to the Customer or Item without removing the Customer or Item.

Figure 5 illustrates data for ARInvoice #100 that has been synchronized by ARInvoiceSync. Both the source and destination applications contain the same ARInvoiceLineItems with the same three related Customers or Items.

Figure 5. Invoice data before deletion of references to items

Figure 6 illustrates the same primary ARInvoice after the source application has deleted one of its related Customers or Items. The deletion of the child business object triggers the source connector to send the ARInvoice business object with the Update verb to ARInvoiceSync. The graphic illustrates the state of the ARInvoice business object as ARInvoiceSync sends it to the destination application, before the destination application has removed the reference to the related Customer or Item.

Figure 6. Invoice data after the source application has deleted references to items

Figure 7 illustrates the state of the ARInvoice business object after deletion of the reference to the related Item in the destination application.

Figure 7. ARInvoice data after synchronization in the destination application

Compensation processing

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

Property name and explanation Possible values Default value

ITEM_TYPE

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

Item, ItemBasic, ItemOrder, ItemPlanning Item

VERIFY_SYNC_CUSTOMERS

Set to "sync" to cause ARInvoiceSync to synchronize the related Customer or CustomerPartner in the destination application. ARInvoiceSync performs the following process:

  1. Checks the value of the ObjectType attribute of ARInvoice's child business object, RelatedCustomerRef. If the value is "Customer", ARInvoiceSync creates a generic Customer business object. If the value is "CustomerPartner", ARInvoiceSync creates a generic CustomerPartner business object.
  2. Copies the CustomerId from the ARInvoice business object and uses it as the unique identifier of the newly created generic Customer or CustomerPartner business object.
  3. Sends the business object with the Sync verb to CustomerWrapper or CustomerPartnerWrapper. 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 or CustomerPartnerSync.
  4. If the synchronization collaboration fails to create the Customer or CustomerPartner, ARInvoiceSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

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

  1. Checks the value of the ObjectType attribute of ARInvoice's child business object, CustomerAddress. If the value is "Customer", ARInvoiceSync creates a generic Customer business object. If the value is "CustomerPartner", ARInvoiceSync creates a generic CustomerPartner business object.
  2. Copies the CustomerId from the ARInvoice business object and uses it as the unique identifier of the newly created generic Customer or CustomerPartner business object.
  3. Sends the business object with the Exists verb to CustomerWrapper or CustomerPartnerWrapper. In turn, the wrapper collaboration retrieves the business object from the destination application.
  4. If the wrapper collaboration fails to retrieve the Customer or CustomerPartner, ARInvoiceSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

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

neither,

sync,

verify

neither

VERIFY_SYNC_ITEM

Set to "sync" to synchronize related items in the destination application. ARInvoiceSync copies ItemId (and other interesting attribute values) from the ARInvoice business object and creates the type of generic business object specified in the ITEM_TYPE property. ARInvoiceSync 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, ARInvoiceSync handles the error as specified in its INFORMATIONAL_EXCEPTIONS property.

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

Set to "neither" to cause ARInvoiceSync to synchronize the triggering ARInvoice business object without first synchronizing related items or verifying existing related items in the destination application.

neither, sync, verify 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, perform the following steps:

  1. Stop the ARInvoiceSync v. x.x.x collaboration.
  2. Back up the repository. For information about backing up the repository, see the System Administration Guide.
  3. If you have customized the collaboration template:
  4. Install the new ARInvoiceSync 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