InvoiceGen Collaboration Template

The InvoiceGen collaboration provides a mechanism for generating an invoice in a financial system from billing information in another system. An invoice is a document that summarizes charges for goods or services between a company and another party. Invoices can reflect either Account Receivables or Account Payables. Generally invoices are sent to a Bill-to customer.

Invoices can originate in different functional areas of an organization, such as Customer Support and Sales. They can be generated in different ways; for example, an invoice might be generated for a specific service rendered or generated cyclically on a monthly cycle. InvoiceGen provides a common view of invoice information that facilitates Account Receivables or General Ledger posting in managing invoice information regardless of its origin in the organization.

Generally, Enterprise Resource Planning (ERP) applications manage financial information and are designated as the "system of record." It is an ERP application that creates and maintains the billing invoice for the organization and mails it to the customer. Customer Interaction Management (CIM) applications, however, accumulate information that is relevant to customer billing. Therefore, InvoiceGen is designed to use a CIM application as the source of invoice data and an ERP application as the destination. The CIM application can send an invoice or a collection of information taken from such sources as cases or contracts.

InvoiceGen is designed to synchronize invoice creation only. IBM WebSphere Business Integration Server Express Plus does not trigger changes to or cancellations of the invoice. Therefore, IBM WebSphere Business Integration Server Express Plus does not provide cross-referencing of the synchronized invoices and does not verify whether updates or cancellations are valid. Nor does InvoiceGen support returning ERP changes to the CIM system that originated the invoice.

InvoiceGen synchronizes invoices with billing implications for Account Receivables. These invoices contain such billing details as the Item being invoiced, the pricing of the Item, and the Bill-to customer being invoiced. InvoiceGen does not synchronize accounting summary invoices that are not actually used for customer billing. The collaboration supports three types of invoice: Standard, Debit memo, and Credit memo.

The collaboration processes the generic Invoice business object. The business object's header contains a reference to the Sold-to customer associated with the invoice. An invoice can reference a single Sold-to customer. Each of its InvoiceLineItem child business objects can contain a reference to the item associated with the invoice line. Before synchronizing an Invoice, InvoiceGen can verify or synchronize the existence of the referenced Sold-to Customer and referenced Items.

Notes:

Synchronization of related business objects

Although it synchronizes only InvoiceGen business object data, InvoiceGen 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

ItemBasic

ItemOrder

ItemPlanning

VERIFY_SYNC_ITEM

ITEM_TYPE

ItemSync

ItemWrapper

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

Issues and assumptions

Collaboration object setup

This section includes information on port bindings and required steps for setting up collaboration objects based on InvoiceGen. 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 the relationship of InvoiceGen to its source and destination ports.

Figure 1. InvoiceGen 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
Invoice The destination application's connector Sends a reference-valued business object to retrieve the full-valued business object. The result determines what verb to use when synchronizing the Invoice.

Retrieve


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

Sends the triggering business object out of the collaboration.

Create Update Delete


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 InvoiceGen as stand-alone

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

  1. Create the InvoiceGen 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 InvoiceGen collaboration object's VERIFY_SYNC_BusObj configuration properties.
  5. Set the remaining Configuration properties for InvoiceGen.

Using InvoiceGen in a collaboration-object group

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


Verify Synchronize Required collaborations
Customers   InvoiceGen, CustomerWrapper
  Customers InvoiceGen, CustomerWrapper, CustomerSync
Items   InvoiceGen, ItemWrapper
  Items InvoiceGen, ItemWrapper, ItemSync

Using InvoiceGen in a collaboration-object group

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

  1. Create collaboration objects from the templates for InvoiceGen and for each wrapper and synchronization collaboration required. Example: Create collaboration objects for InvoiceGen, CustomerWrapper, CustomerSync, ItemWrapper, and ItemSync.
  2. Edit the InvoiceGen collaboration object to bind its ToBusObjWrapper ports to the appropriate wrapper collaboration object. 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 InvoiceGen collaboration object as described in this document's Port information section.
  4. Set the InvoiceGen collaboration object's VERIFY_SYNC_BusObj properties. Example: To synchronize Customers and Items, set these suggested values for the following properties:
  5. Set the InvoiceGen collaboration object's ITEM_TYPE property to the desired item type.

Completing the setup of the InvoiceGen collaboration-object group

The steps below assume that you have already created collaboration objects from the templates for InvoiceGen and for each required wrapper and synchronization collaboration. For example, to synchronize InvoiceGen and related Items and Customers, you have created collaboration objects for InvoiceGen, ItemWrapper, ItemSync, CustomerWrapper, and CustomerSync. The following steps complete the setup procedure for synchronizing InvoiceGen, 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 has already bound the ItemWrapper collaboration object's From port to the InvoiceGen 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. For more information, see:

Collaboration template processes

This section illustrates the process logic for this collaboration template:

Overall process logic

Figure 2 illustrates InvoiceGen's process logic.

Figure 2. InvoiceGen collaboration process logic

Inherited process logic

This collaboration template uses the following standard collaboration business processes:

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

Verifying or synchronizing referenced Customers and Items

At its header level, the generic Invoice business object references the Sold-to Customer related to the invoice. Each of the InvoiceLineItem child business object references an invoiced Item. If its VERIFY_SYNC_CUSTOMERS and VERIFY_SYNC_ITEM properties evaluate to "sync" or "exists," InvoiceGen creates generic Customer and Item business objects, and then sends them to CustomerWrapper and ItemWrapper, respectively. InvoiceGen builds the generic Customer and Item business objects by using the verb specified in VERIFY_SYNC_CUSTOMER and VERIFY_SYNC_ITEM; it also uses the identifiers referenced in Invoice and InvoiceLineItem.

Because IBM supports several generic item business objects, InvoiceGen uses its ITEM_TYPE property to determine which generic item to verify or synchronize.

Note: For a collaboration to successfully process ItemBasic, ItemOrder, and ItemPlanning, 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.

Figure 3 illustrates InvoiceGen's process for verifying or synchronizing a Sold-to Customer and Items.

Figure 3. Verify or synchronize customers and items

Updating references to items

When InvoiceGen sends the Invoice business object with the Update verb to the destination, the synchronization updates relationships to LineItems, but it does not actually create, update or delete a LineItem.

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

Figure 6 illustrates data for Invoice #100 that has been synchronized by InvoiceGen. Both the source and destination applications contain the same primary Invoice with the same three related LineItems.

Figure 4. Invoice Data before deletion of references to items

Figure 5 illustrates the same primary Invoice after the source application has deleted one of its related LineItems. The deletion of the child business object triggers the source connector to send the Invoice business object with the Update verb to InvoiceGen. The graphic illustrates the state of the Invoice business object as InvoiceGen sends it to the destination application, before the destination application has removed the reference to the related LineItem.

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

Figure 6 illustrates the state of the Invoice business object after deletion of the reference to the related LineItem in the destination application.

Figure 6. Vendor 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 InvoiceGen 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 InvoiceGen 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 InvoiceGen 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 creates the Invoice business object. If the collaboration's VERIFY_SYNC_ITEM property evaluates to "sync" or "verify," InvoiceGen 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 InvoiceGen to synchronize the referenced Sold-to Customer in the destination application. InvoiceGen copies the CustomerId from the Invoice business object and creates a generic Customer business object. InvoiceGen sends the business object with the Sync verb to CustomerWrapper. In turn, CustomerWrapper retrieves values for all attributes from the source application and sends the business object with the Create verb to CustomerSync. If CustomerSync fails to create the Customer, InvoiceGen logs a message and ends.

Set to "verify" to cause InvoiceGen to verify the referenced Sold-to Customer in the destination application. InvoiceGen copies the CustomerId from the Invoice business object and creates a generic Customer business object. InvoiceGen sends the business object with the Exists verb to CustomerWrapper. In turn, CustomerWrapper retrieves the business object from the destination application. If CustomerWrapper fails to retrieve the Customer, InvoiceGen logs a message and ends.

Set to "neither" to cause InvoiceGen to create the Invoice business object without first synchronizing the referenced Customer or items in the destination application.

neither, verify, sync

neither

VERIFY_SYNC_ITEM

Set to "sync" to cause InvoiceGen to synchronize prerequisite items in the destination application. InvoiceGen copies the ItemId (and other interesting attribute values, such as the Plant attribute) from the Invoice business object and creates the type of generic business object specified in the ITEM_TYPE property. InvoiceGen 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 prerequisite item, InvoiceGen logs a message and ends.

Set to "verify" to cause InvoiceGen to verify prerequisite items in the destination application. InvoiceGen copies the ItemId from the Invoice business object and creates the type of generic business object specified in the ITEM_TYPE property. InvoiceGen 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 prerequisite item, InvoiceGen logs a message and ends.

Set to "neither" to cause InvoiceGen to create the triggering Invoice business object without first synchronizing prerequisite items or verifying existing prerequisite items in the destination application.

neither, verify, sync neither

VERIFY_SYNC_ITEM

Set to "sync" to cause ContractSync to synchronize related items in the destination application. ContractSync sends the business object with the Sync (and values in key fields only) verb to ItemWrapper. In turn, ItemWrapper retrieves values for all attributes from the source application and sends the generic business object with the Create verb to ItemSync. If ItemWrapper fails to create the related item, ContractSync logs error message #5010 and ends. If ItemWrapper successfully creates all of the related items and if the trace level is set to 3 or higher, information message #5020 appears at the trace destination.

Set to "verify" to cause ContractSync to verify related items in the destination application. ContractSync 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 the related item, ContractSync logs error message #5010 and ends. If ItemWrapper successfully verify all of the related items and if the trace level is set to 3 or higher, information message #5020 appears at the trace destination.

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

neither, sync verify sync

Collaboration messages

Note: Messages that provide warnings and those that provide information appear at the trace destination only if the trace level has been set to 3 or higher.

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