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.
InterChange Server supports three types of service calls: synchronous, asynchronous outbound, and asynchronous inbound. The following sections describe each type of 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.
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.
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.
Perform the following steps to add a service call to the activity diagram:
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):
Label field for a service call. Process Designer Express assigns the label after you complete the service call definition.
To change the type of the service call, do the following:
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.
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:
For more information on transactional collaborations, see "Using transactional features".
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.
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:
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.
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:
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:
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.
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. |
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.