BillingInquiry collaboration template

The BillingInquiry collaboration enables a company's applications to share billing information. If those applications have web access capability, the BillingInquiry collaboration can be used with the IBM WebSphere Business Integration Server Express Plus Access for web retrieval.

The BillingInquiry collaboration extends standard collaboration features by providing a scenario that handles the RetrieveByContent verb.

BillingInquiry uses the generic BillingStatement business object to transport billing data.

Collaboration object setup

This section includes information on port bindings and required steps for setting up collaboration objects based on BillingInquiry. 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 BillingInquiry's ports, as they are displayed in System Manager.

Figure 1. BillingInquiry collaboration's 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
BillingStatement The destination application's connector Sends a reference-valued business object to retrieve the full-valued business object. Retrieve RetrieveByContent

Port name: From
Business object Bound to Function Verbs used
BillingStatement 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
BillingStatement The destination application's connector Sends the triggering business object out of the collaboration.

Create Update Delete

Setup suggestions

BillingInquiry is designed to be used as a stand-alone collaboration. To set up BillingInquiry as a stand-alone collaboration object, follow these steps:

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

Collaboration template processes

This section illustrates the process logic for this collaboration template:

Overall process logic

Figure 2 illustrates BillingInquiry's process logic.

Figure 2. BillingInquiry collaboration'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.

RetrieveByContent

The BillingInquiry 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 this means that the connector or connectors that integrate this process must support the RetrieveByContent verb. What this means is that 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.

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

IBM WebSphere Business Integration Server Express Plus connector functionality is to return one unique object using the retrieve by key method. To make non-key retrieval possible, the following suggestions may be considered as part of connector design:

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

Alternatively, if the result set (multiple objects) is desired, design changes to the BillingStatement business object and collaboration are required. You need to do the following:

For example, a new business object (lets call it the BillingStatementWrapper) must be created in the repository. The BillingStatementWrapper will have the BillingStatement business object as a child container with cardinality 'n' and will have those attributes required for retrieval at the header level.

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

Figure 3 illustrates BillingInquiry's RetrieveByContent process.

Figure 3. BillingInquiry collaboration RetrieveByContent process

Compensation processing

InterChange Server Express Plus rolls back a transaction when any step in a transactional collaboration fails. For example, when BillingInquiry 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 Plus rolls back the processing of every collaboration in the group.

When a BillingInquiry 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

Note: BillingInquiry does not have unique configuration properties. All of its properties are standard.

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.

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.

Copyright IBM Corp. 1997, 2004