Service Invoke mediation primitive

Use the Service Invoke mediation primitive to call a service from inside a mediation flow, as an alternative to using the callout mechanism at the end of the mediation flow.

Introduction

When you use the Service Invoke mediation primitive inside a mediation flow, the input message is used to call the service. If the call is successful, the response, or a section of the response identified by one or more XPath expressions, is used to create the output message. If the call is unsuccessful, you can retry the same service, or call another service.

You can have multiple Service Invoke mediation primitives inside one mediation flow. Therefore, you can have a series of service calls. You can use the Service Invoke mediation primitive in a request or response mediation flow.

Generally, the initial service that the Service Invoke mediation primitive calls is defined by the reference operation, which is a combination of the Reference name property and the Operation name property. For a Service Invoke mediation primitive in a subflow, the reference is defined on the subflow and resolved to a reference in the parent flow when an instance of the subflow is created.

The Service Invoke mediation primitive has one input terminal (in) and multiple output terminals. There is a fail terminal (fail) for unmodeled faults, and one output terminal for each modeled fault. Modeled faults are those that are explicitly listed in a WSDL file; any other fault is an unmodeled fault. In addition, there is an output terminal (out), which is used for successful service calls, and a timeout terminal (timeout), which is used for some types of asynchronous calls. Output terminals that are created for a specific reason are classified as dynamic terminals. For example, a WSDL-defined fault causes a dynamic output terminal to be created.

The Service Invoke mediation primitive can operate in default mode or Message Enrichment mode. You can configure the mode from the Select Reference Operation window that opens when the mediation primitive is dropped on the canvas:

To use the default mode, ensure that the Message Enrichment mode check box is clear.
To enable the Message Enrichment mode, select the Message Enrichment mode check box.

Details (default mode)

In default mode, the input message, which is received at the in terminal, is passed directly to the service, and the response message from the service invocation is passed directly to the out terminal. The body and header sections of the response message are propagated to the output message.

The in and out terminals are automatically set to the appropriate message types for the interface and operation with which the mediation primitive is associated. The input and output terminals of the Service Invoke mediation primitive reflect the reference operation in the following way:

The message type of the in terminal must match the request message type of the reference operation.
If there is a response message, the message type of the out terminal must match the response message type of the reference operation.

The following figure shows the message flow in default mode, for a two-way operation.

Figure 1. Message propagation in default mode

This figure shows how the output message is populated in default mode.

The following table summarizes the operation of the terminals of the mediation primitive in default mode.

Table 1. Terminals of the Service Invoke mediation primitive in default mode
Terminal type	Terminal name	Dynamic terminal?	Message type	Terminal description
Input	in	No	WSDL message type for the request message of the operation.	Receives the input message. The message (SMO) received at the input terminal is used to call the service. Service calls are defined by the operations specified in the WSDL. For example, you might have an operation called `getCustomerDetails` that calls a customer information service.
Output	out	Yes. WebSphere® Integration Developer defines one for the response message on the interface.	WSDL message type for the response message of the operation.	Propagates the updated message. The result of the service call is used to make a new message (SMO) that is sent to this terminal. Used when the service call is successful. This terminal does not exist if the operation is one-way.
Output	Defaults to modeled fault name.	Yes. WebSphere Integration Developer defines one for each modeled fault on the interface.	WSDL message type for the fault message of the operation.	Propagates the fault response message. No information is put in the `failInfo` element. Used when the relevant modeled fault is returned from the service call.
Output	timeout	No	WSDL message type for the request message of the operation. (Same as input terminal.)	Propagates the original message together with the timeout exception information. The timeout exception information is stored in the `failInfo` element. Used when an asynchronous service call fails because of a timeout. The timeout terminal is not used for calls that are asynchronous with callback, only for calls that are asynchronous with a deferred response. This terminal does not exist if the operation is one-way.
Fail	fail	No	WSDL message type for the request message of the operation. (Same as input terminal.)	Propagates the original message together with any exception information. The exception information is stored in the `failInfo` element. Used when an unmodeled fault is returned from the service call.

Details (Message Enrichment mode)

In Message Enrichment mode, a section of the input message, which is received at the in terminal of the Service Invoke mediation primitive, is used for the service invocation. The output message that passes through the out terminal is constructed by merging the response from the service with the original request message that was passed into the mediation primitive.

The message type of the in and out terminals must match, but the type is initially not set. When the in terminal is wired, its message type is defined implicitly by the input message, and this message type is propagated to the out terminals.

The following figure shows how the message is enriched as it flows through the mediation primitive in a two-way operation.

Figure 2. Message propagation in Message Enrichment mode

This figure shows how the output message is populated in Message Enrichment mode.

The following table summarizes the operation of the terminals of the mediation primitive in Message Enrichment mode.

Table 2. Terminals of the Service Invoke mediation primitive in Message Enrichment mode
Terminal type	Terminal name	Dynamic terminal?	Message type	Terminal description
Input	in	No	Undefined until wire propagation causes the message type to be defined.	Receives the input message. One or more XPath expressions are used to extract a section of the inbound SMO for use as the request message.
Output	out	Yes. WebSphere Integration Developer defines one for the response message on the interface.	Undefined until wire propagation causes the message type to be defined.	Populates the output message by merging the response from the service with the original request message that was passed into the mediation primitive. This terminal does not exist if the operation is one-way.
Output	Defaults to modeled fault name.	Yes. WebSphere Integration Developer defines one for each modeled fault on the interface.	Undefined until wire propagation causes the message type to be defined.	Populates the fault message by merging the response from the service with the original request message that was passed into the mediation primitive. No information is put in the `failInfo` element. Used when the relevant modeled fault is returned from the service call.
Output	timeout	No	Undefined until wire propagation causes the message type to be defined.	Propagates the original message together with the timeout exception information. The timeout exception information is stored in the `failInfo` element. Used when an asynchronous service call fails because of a timeout. The timeout terminal is not used for calls that are asynchronous with callback, only for calls that are asynchronous with a deferred response. This terminal does not exist if the operation is one-way.
Fail	fail	No	Undefined until wire propagation causes the message type to be defined.	Propagates the original message together with any exception information. The exception information is stored in the `failInfo` element. Used when an unmodeled fault is returned from the service call.

Usage

You can use the Service Invoke mediation primitive to help control the service retry sequence. The retry sequence can be a combination of the following:

Re-send the initial request to the initial service.
Send the initial request to an alternate service.
Send a new request to the initial service.
Send a new request to an alternate service.

For more information about using the Service Invoke mediation primitive, see: Usage patterns.