CallableFlowAsyncInvoke node

Use the CallableFlowAsyncInvoke node in conjunction with a paired CallableFlowAsyncResponse node to split message flow processing asynchronously. The CallableFlowAsyncInvoke node issues a call to the CallableInput node of a message flow in another location and then completes. When the called message flow completes processing, data is returned to the paired CallableFlowAsyncResponse node.

This topic contains the following sections:

Purpose

You can split message flows asynchronously so that you can do processing in different locations, by using the CallableFlowAsyncInvoke and CallableFlowAsyncResponse nodes. For information about how to call message flows asynchronously, see Developing asynchronously callable message flows.

You can split your processing between different locations, such as different applications in an integration server, or IBM® App Connect Enterprise and IBM App Connect Enterprise as a Service. A calling flow processes information in one location, then calls another flow in a different location. A separate response flow is also running in the same location as the calling flow. The calling flow includes a CallableFlowAsyncInvoke node, which calls a CallableInput node in a second (callable) flow.

You specify an endpoint name on the CallableFlowAsyncInvoke node of the calling flow. The CallableFlowAsyncInvoke node calls the correct callable flow by specifying the application that contains the callable flow, and the endpoint name that is specified on the CallableInput node. When the callable flow has completed processing, the CallableReply node sends the information to the paired CallableFlowAsyncResponse node in the separate response flow that is in the same location as the calling flow.

When you pass a message into the main calling message flow, the CallableFlowAsyncInvoke node sends the contents of the message body and local environment folders to the CallableInput node of the callable flow. The CallableFlowAsyncInvoke node parses the incoming message in full, so that it is in a suitable format to send to the CallableInput node. Therefore, you should validate the message before it reaches the CallableFlowAsyncInvoke node. If the message fails validation at this point, it can be rolled back.

When the CallableFlowAsyncInvoke node has sent the incoming message to the callable flow, it completes, propagating to any node that is connected to its output terminal.

You can share data between the flow that contains the CallableFlowAsyncInvoke node and the flow that contains the CallableFlowAsyncResponse node, by storing and retrieving data in the UserContext folder in the Environment. For more information, see Sharing data between a calling flow and a response flow.

The CallableFlowAsyncInvoke node is contained in the Callable Flow drawer of the palette, and is represented in the IBM App Connect Enterprise Toolkit by the following icon:
CallableFlowAsyncInvoke node icon

Behavior of a node that adds a request to a group

When a supported node successfully processes a message for output, it adds the information about the request that was just sent to the group that was most recently created in the message flow. The reply ID that the group expects is determined automatically from the transport, and the folder name is taken from the Request folder property.

Overrides

By default, the output node adds the request to the most recently created group. If multiple groups are being constructed in the same thread, a local environment override can be used to specify the group ID of the target group: LocalEnvironment.Destination.GroupScatter.RequestNode.GroupId. Requests can be added only to a group that is in construction in the current message flow thread. An exception is issued if no such group is available.

Transactions

Where a transport is transactional, the message obeys the usual transactional rules for the given transport. However, the group information is updated outside of the scope of the transaction. Therefore, if the transaction and output message are rolled back, the request is still added to the group.

Errors

If the Add Request to Group property is set to true, and the Request folder property is blank, a configuration exception is issued. The thread context is used to determine which group to add a request to.

If the Add Request to Group property is set to true, but no group is in construction in this thread, an exception is issued.

If a group ID override is specified and the ID is invalid or does not correspond to a group that is in construction in the current thread, an exception is issued.

Request timeouts

You can use the Request timeout (secs) property to specify a timeout for an individual request that is part of a group, which is separate from the base timeout that is set on the group. If timeouts are set for individual requests, the timeout value for the group becomes the same as the timeout value of the individual request with the shortest timeout that has not yet received a reply.

For example, you might have a group with a base timeout of 5 seconds, and the following requests:
  • Request A, with a request timeout of 1 second
  • Request B, with a request timeout of 4 seconds
  • Request C, with no request timeout
The group will time out at the following times in the following circumstances:
  • After 1 second if no reply for request A is received, regardless of whether replies for request B or C are received
  • After 4 seconds if a reply for request A is received within 1 second, but no reply for request B is received, regardless of whether a reply for request C is received
  • After 5 seconds if a reply for request A is received within 1 second for request A, a reply for request B was received within 4 seconds, but no reply is received for request C
If any in-flight request has a request timeout, it takes priority over the group timeout. For example, you might have a group with a base timeout of 5 seconds and the following individual request timeouts:
  • Request A, with an individual request timeout of 10 seconds
  • Request B, with no individual request timeout
  • Request C, with no individual request timeout
This group will timeout in the following circumstances:
  • After 10 seconds if no response for request A is received, regardless of the status of requests B and C
  • After 5 seconds if a response for request A is received within those 5 seconds and no response for requests B or C are received (because the reply from request A removes the 10 seconds timeout and reverts to the 5 second timeout)
  • Immediately after the response for request A is received, if the response for request A is received after 5 seconds but before 10 seconds, and either request B or C has not replied. Note that if request A is received after 7 seconds and request C is received after 6 seconds, request C would still be marked as a completed request even though it was received after its default 5 seconds.

Terminals and properties

When you have put an instance of the CallableFlowAsyncInvoke node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

The CallableFlowAsyncInvoke node terminals are described in the following table.
Terminal Description
In The input terminal.
Failure The output terminal to which the message is routed if a failure is detected during processing.
Out The output terminal, if connected, propagates the input message when the callable flow has been sent the input message data.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).

The Description properties of the CallableFlowAsyncInvoke node are described in the following table.
Property M C Default Description
Node name No No The node type (CallableFlowAsyncInvoke) The name of the node.
Short Description No No   A brief description of the node.
Long Description No No   Text that describes the purpose of the node in the message flow.
The Basic properties of the CallableFlowAsyncInvoke node are described in the following table.
Property M C Default Description mqsiapplybaroverride command property
Unique identifier Yes Yes A unique value prefixed with the node name. The unique identifier value is used to match this node with a CallableFlowAsyncResponse node, to which the called flow’s CallableReply node will send the response. asyncResponseCorrelator
Target Application Yes Yes   The name of the application that contains the message flow that you want to call.

The application name is case sensitive.

 targetApplication
Target Endpoint Name Yes Yes   The Endpoint Name property that is set on the message flow that you want to call.

This property is case sensitive and must match the Endpoint Name property on the CallableInput node of the flow that you want to call.

 targetEndpointName
Request timeout (sec) No Yes 120 The time within which the callable flow must be called, in seconds. If the callable flow is not called within the specified time, an error message is issued. requestTimeout
Call Preference No No Prefer local calls Specifies how the CallableFlowAsyncInvoke node locates a callable flow. Select one of the following options:
Prefer local calls
Select this option if the callable flow is in the same integration server as the main flow.
Remote calls only
Select this option if the callable flow is in a different integration server from the main flow, or if one flow is in App Connect Enterprise and the other flow is in App Connect Enterprise as a Service.
 
The Group properties of the node are described in the following table:
Property M C Default Description
Add request to group No No False If selected, this property causes the request or output node to add the request to a group that is being built, and generate group information in the environment tree.
Request folder No (See note) No   The folder name in the group for the request that this node will make.
Request timeout (secs) No No   Use this property to specify a timeout for an individual request that is part of a group, which is separate from the base timeout that is set on the group.

If timeouts are set for individual requests, the timeout value for the group becomes the same as the timeout value of the individual request with the shortest timeout that has not yet received a reply.
Note: The Request folder is a mandatory property only if the Add Request to Group property is selected.
The Monitoring properties of the node are described in the following table.
Property M C Default Description
Events No No None Events that you define for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change, or delete monitoring events for the node; see Configuring monitoring event sources by using monitoring properties for details.

You can enable and disable events that are shown here by selecting or clearing the Enabled check box.

Local environment overrides

You can override the following node properties dynamically in the local environment. You can set the following values under LocalEnvironment.Destination.CallableFlow.Invoke.
Table 1. Local environment overrides for the CallableFlowAsyncInvoke node
Setting Description
requestTimeout Overrides the Request timeout (secs) property on the node; for example:
SET LocalEnvironment.Destination.CallableFlow.Invoke.requestTimeout = 180;
callPreference Overrides the Call Preference property on the node. Set this property to RemoteOnly or PreferLocal; for example:
SET LocalEnvironment.Destination.CallableFlow.Invoke.callPreference = 'RemoteOnly';
targetApplication Overrides the Target Application property on the node; for example:
SET LocalEnvironment.Destination.CallableFlow.Invoke.targetApplication = 'App2';
targetEndpointName Overrides the Target Endpoint Name property on the node; for example:
SET LocalEnvironment.Destination.CallableFlow.Invoke.targetEndpointName = 'Gold';