Service calls

An action node cannot, by itself, send a request to a connector or another collaboration. Instead, you must connect the action node to a service call. InterChange Server supports both synchronous and asynchronous service calls. The following is an example of a synchronous service call that uses a Retrieve request:

A service call always connects to an action. The action generates the service call and handles the service call's results on its outgoing transition links. An action and a service call work as a pair; the service call performs the action's remote input/output function.

Figure 35 illustrates the relationship between an action node and service call. The figure shows the order in which the collaboration runtime environment processes the action and its service call.

Figure 35. Relationship between action node and service call


Figure 35 shows that the collaboration runtime environment first processes the code in the action and then executes the service call. When the service call completes, the action node's outgoing transition links handle the result. When an action node generates a service call, it is good practice to include an outgoing exception link that checks for ServiceCallException.

Types of service calls

InterChange Server supports three types of service calls: synchronous, asynchronous outbound, and asynchronous inbound. The following sections describe each type of call.

Synchronous service call

This type of service call uses a synchronous request/response mechanism. The service call sends the request but does not complete until the response arrives and is processed.

Synchronous service calls support compensation. In addition, they support a timeout value for long-lived business processes.

By default, all service calls added to an activity diagram are synchronous. You can then change the type if required by your scenario.

Asynchronous outbound service call

An asynchronous outbound service call sends a request but does not expect or wait for a response before continuing its processing. A collaboration template must support long-lived business processes in order to use asynchronous outbound service calls.

If an asynchronous outbound service call has a port that is bound to a collaboration instead of a connector, the service call automatically becomes synchronous.

Asynchronous outbound service calls support compensation, but do not support a timeout value for long-lived business processes.

Asynchronous inbound service call

An asynchronous inbound service call waits to receive an incoming event based on a correlation attribute or set of correlation attributes that identify the event. It is used in conjunction with long-lived business processes. (See Using a correlation attribute for more information.)

When an asynchronous inbound service call is created, it is given a timeout value; if the service call does not receive an incoming event before the timeout expires, the exception TimeoutException is raised.

Asynchronous inbound service calls are available only if the collaboration template supports long-lived business processes. You can enable this support at any time during the template development processes by clicking the Long Lived Business Process Support option on the Template Definitions General tab.

Asynchronous inbound service calls do not support compensation.

Creating a service call

Perform the following steps to add a service call to the activity diagram:

  1. Ensure that the diagram editor is open.
  2. In the workspace, right-click the symbol for the action node with which you want to associate a service call.
  3. From the context menu, click Add service node. The service call is added to the activity diagram; a dotted line connects the service call to the action node. By default, the service call is synchronous.

Defining a service call

After you have created the service call, you must define it. Use the Service Call Properties dialog box to specify these required properties:

Optionally, you can also specify the following:

Tip

Upon return of a service call, the business object variable contains the result of the call. The data in the original business object is lost if the service call retrieves new data for the business object. Therefore, if you anticipate needing the values in the original, it is useful to copy the original business object into a temporary variable in an action that calls the service call.

Perform the following steps to define a regular service call (one that does not use compensation or correlation sets):

  1. In the activity diagram, double-click the service call symbol you have already created. The Service Call Properties dialog box is displayed, as shown in Figure 36. Notice that you cannot directly enter a value in the

    Label field for a service call. Process Designer Express assigns the label after you complete the service call definition.

    Figure 36. Service Call Properties dialog box


  2. Optionally, specify the description for this service call.
  3. Use the Port drop-down list to select the port the service call is going to use for sending or receiving requests.
  4. Use the Verb drop-down list to specify which verb is going to be used in the request. For example, to update an application with the data contained in the business object the service call sends, use the Update verb.
  5. Use the BO variable drop-down list to select the variable that contains the business object the service call sends. If you plan to support long-lived business processes, this variable must be a global template or port variable; scenario variables cannot be used in this capacity for long-lived business processes.
  6. Click Apply to save the definition.

Defining the service call type

To change the type of the service call, do the following:

  1. If the Service Call Properties dialog box is not open, display it by double-clicking the service call symbol in your activity diagram.
  2. Ensure that you have supplied the required port name, verb, and business object variable name for the service call.
  3. Click the Advanced button on the Service Call Properties dialog box. The Service Call Advanced Properties dialog box is displayed.

    Figure 37. Service Call Advanced Properties dialog box


  4. In the Call Type box, click the radio button next to the type of service call you want to use.
    Note:
    The Async Inbound option is available only if you have enabled support for long-lived business processes in the template definition.
  5. If you are using a synchronous service call or an asynchronous inbound service call and you want to specify a timeout value to be used with long-lived business processes, click the Time-out checkbox and set the timeout value to one of the following:

    Note:
    If the port of a synchronous service call is bound to a collaboration instead of a connector, any specified timeout value is ignored.
  6. Click Ok to close the Service Call Advanced Properties dialog box.
  7. Click Apply in the Service Call Properties dialog box to save your changes.

Defining compensation

Subtransaction steps of a collaboration define the transactional behavior of a transactional collaboration. A subtransaction is an operation in which the collaboration sends a request that causes a transactional data change in an application data store. Service calls implement subtransaction steps. A service call that has a

Create, Delete, or Update request is a subtransaction step; a Retrieve request is not (because it does not change the data). Other verbs might or might not be transactional, depending on whether they change data in an application data store.

Note:
Although a service call with a Retrieve request is not considered a subtransaction step, you can still specify compensation for it.

To create a collaboration template that supports transactional behavior, you define compensation for each subtransaction step. Compensation is a logical undo action: if execution of a collaboration object fails, it causes rollback of the previously executed operations. When rollback occurs, the collaboration runtime environment steps backward through the path of execution, executing a compensation step for every normal step that has already executed and that has compensation defined. Rollback thereby logically returns data to the state that it was in before the transactional collaboration started to execute.

Viewed in Process Designer Express, a subtransaction step is a service call that requests an operation such as Create, Update, or Delete. These operations always result in data-altering transactions within an application. You can also specify compensation for a service call that requests a Retrieve operation, though compensation is not required since no data is modified during a Retrieve. A service call is defined by a business object with a particular verb, which the collaboration sends either to another collaboration or to a connector. The compensation for that operation is another business object and verb. Any business object and verb can compensate for a service call.

Table 24, taken from the manual Technical Introduction to IBM WebSphere InterChange Server, lists some common types of compensation.

Table 24. Compensation Examples
Action Compensation
Create a business object Delete a business object
Delete a business object Create a business object
Update a business object Update a business object, restoring the former values

Compensation is supported for both synchronous service calls and asynchronous outbound service calls. If the collaboration is transactional, and if the verb for this service call requests a data modification, you can specify the compensation operation that rolls back the regular service call. Define the compensation as follows:

  1. If the Service Call Properties dialog box is not open, display it by double-clicking the service call symbol in your activity diagram.
  2. Click the Compensation checkbox. The Port, Verb, and BO Variable fields in the Compensation Service Call box become active.
  3. In the Compensation Service Call box, select the port, verb, and business object variable to be used in the compensation service call. Compensation service calls can use the same port, verb, and business object as the regular service call, or you can specify a different port, verb, and business object.
  4. Click Apply to save your changes.

For more information on transactional collaborations, see "Using transactional features".

Using a correlation attribute

A correlation attribute is used to identify a conversation. A conversation is a unit of coherent communication between two business processes. Because there can be multiple conversations when two or more business processes communicate with each other, it is necessary to identify a conversation with a correlation attribute. You can think of a correlation attribute as a UID for a conversation. The ID must be initialized when the conversation is started, and all subsequent participants must use this ID when involved in the conversation.

InterChange Server supports only one conversation per scenario. If you need more than one conversation, you must use multiple scenarios within the collaboration template, or use multiple collaboration templates. In addition, a correlation attribute can be initialized only once in the scenario.

In order to use a correlation attribute, you must ensure the following conditions are true:

When using a correlation attribute with a service call, the business object is determined automatically; it is always the business object assigned to the port used for the service call.

After a correlation attribute is initialized in a scenario, you can set it for outbound service calls (see Setting correlation attributes), match it on asynchronous inbound service calls (see Matching correlation attributes), or both.

Initializing correlation attributes

The first step in using correlation attributes is initialization. When you initialize a correlation attribute, you specify the business object attribute and the template variable to be used to capture that attribute's value. Initialization must be done prior to setting the correlation attribute on an outbound service call, or matching the correlation attribute in the runtime environment.

Initialization can be done in a start node, an asynchronous outbound service call, or a synchronous service call.

Perform the following steps to define and initialize correlation attributes in a service call:

  1. Ensure that Process Designer Express is open, and that the Service Call Properties dialog box is displayed.
  2. Click Advanced to open the Service Call Advanced Properties dialog box.
  3. Click Correlation Set. Notice that the business object variable is automatically defined as the one assigned to the service call's outbound port.
  4. Click Initialize.
  5. Click the checkbox next to each business object attribute you want to use for correlation.
  6. For each selected attribute, use the drop-down list in the Correlation column to select a template variable to capture and store the attribute's value.
  7. Click Apply.

The procedure for initializing a correlation set from the start node is the same, with the exception of clicking the Initialize checkbox. Since a start node does not participate in matching correlation attributes, initialization is implicit.

Setting correlation attributes

After you have defined and initialized a correlation set, you can assign it to any outbound service call. The service call then sends out a request that includes the correlation set. You can set correlation attributes on as many outbound service calls as you want.

Perform the following steps to set correlation attributes on an outbound service call:

  1. Ensure that Process Designer Express is open, and that the Service Call Properties dialog box is displayed for the outbound service call.
  2. Click Advanced to open the Service Call Advanced Properties dialog box.
  3. Click Correlation Set.
  4. Click the checkbox next to each business object attribute you defined in your initialized correlation set.
  5. For each selected attribute, use the drop-down list in the Correlation column to select the template variable used to capture and store the attribute's value. This variable must be the same one used when the correlation set was initialized.
  6. Click Apply.

Matching correlation attributes

After you have initialized a correlation set, you can configure an asynchronous inbound service call to receive any response that matches that particular correlation set.

Perform the following steps to specify a correlation set in an asynchronous inbound service call:

  1. Ensure that Process Designer Express is open, and that the Service Call Properties dialog box is displayed for the asynchronous inbound service call.
  2. Click Advanced to open the Service Call Advanced Properties dialog box.
  3. Click Correlation Set.
  4. Click the checkbox next to each business object attribute you defined in your initialized correlation set.
  5. For each selected attribute, use the drop-down list in the Correlation column to select the template variable used to capture and store the attribute's value. This variable must be the same one used when the correlation set was initialized.
  6. Click Apply.

At runtime, if the asynchronous inbound service call has attributes that match those defined in the correlation set, the service call is invoked by the scenario. If its attributes do not match, the service call is routed to another scenario or collaboration that has defined a matching correlation set.

Handling results

When a service call executes, the scenario receives two return values: a status and a business object. Table 25 describes the use of each.

Table 25. Service call return values
Returned Description
Status The normal outgoing transition link of the action that generated the service call tests for success of the service call. An exception transition link can check for a ServiceCallException exception to test for failure of the service call. A service call can fail due to transport problems as well as application problems. Because transport failure can cause duplication of data, it is important to determine whether a service call failure was due to transmission problems. For more information, see Handling particular service-call exceptions.
Business object Upon completion of a service call, the business object variable that the service call used contains new data values if the service call resulted in any application change.

Performance considerations

Collaboration performance is affected by the number of service calls and the size of the business objects passed by the service calls. Although you cannot change business object size, try to reduce the number of service calls that a collaboration makes.

For example, suppose the scenario needs to perform an operation on child business objects in a hierarchical business object. In some situations, it can be more efficient to retrieve the entire hierarchical object and iterate through it locally, rather than creating a service call for each child business object that needs to perform a service call.

Copyright IBM Corp. 2003, 2004