Routing Nodes

Routing :

Filter node :

Use the Filter node to route a message according to message content.

- Create a filter expression in ESQL to define the route that the message is to take. You can include elements of the input message or message properties in the filter expression, and you can use data that is held in an external database to complete the expression. The output terminal to which the message is routed depends on whether the expression evaluates to true, false, or unknown.

Note : The Filter node accepts ESQL statements in the same way as the Compute and Database nodes.If your message flow requires more complex routing options, use the RouteToLabel and Label nodes.

Terminals:

In : The input terminal that accepts a message for processing by the node.

Failure : The output terminal to which the message is routed if a failure is detected during the computation.

Unknown : The output terminal to which the message is routed if the specified filter expression evaluates to unknown or a null value.

False : The output terminal to which the message is routed if the specified filter expression evaluates to false.

True : The output terminal to which the message is routed if the specified filter expression evaluates to true.

Basic Properties :

Data Source : The ODBC data source name of the database that contains the tables to which you refer in the ESQL that is associated with this node (identified by the Filter Expression property). This name identifies the appropriate database on the system on which this message flow is to execute. The broker connects to this database with user ID and password information that you have specified.

Transaction : The transaction mode for the node. The values are:

• Automatic (the default). The message flow, of which the Filter node is a part, is committed if it is successful. That is, the actions that you define in the ESQL module are performed and the message continues through the message flow. If the message flow fails, it is rolled back. Therefore, if you choose Automatic, the ability to commit or roll back the action of the Filter node on the database depends on the success or failure of the entire message flow.
• Commit. To commit any uncommitted actions that are performed in this message flow on the database that is connected to this node, irrespective of the success or failure of the message flow as a whole, select Commit. The changes to the database are committed even if the message flow itself fails.

Filter Expression :The name of the module within the ESQL resource (file) that contains the statements to execute against the message that is received in the node The ESQL file, which by default has the name <message_flow_name>.esql

Important Note : You can use all the ESQL statements including SET, WHILE, DECLARE, and IF in this module, but (unlike the Compute node) the Filter node propagates the message that it receives at its input terminal to its output terminal unchanged. Therefore, in the Filter node, like the Database node, you have only one message to which to refer.

You cannot modify any part of any message, so the assignment statement (the SET statement, not the SET clause of the INSERT statement) can assign values only to temporary variables. The scope of actions that you can take with an assignment statement is therefore limited.

Treat warnings as errors : For database warning messages to be treated as errors, and to propagate the output message from the node to the Failure terminal, select Treat warnings as errors.

-If you do not select the check box, the node treats warnings as normal return codes and does not raise any exceptions. The most significant warning raised is not found, which can be handled safely as a normal return code in most circumstances.

Label node :

-Use the Label node to process a message that is propagated by a RouteToLabel node to dynamically determine the route that the message takes through the message flow.

-The RouteToLabel node interrogates the LocalEnvironment of the message to determine the identifier of the Label node to which the message must be routed next.You can propagate the message by coding ESQL in a Compute node, or by coding Java™ in a JavaCompute or user-defined node.

-Precede the RouteToLabel node in the message flow with a Compute node or JavaCompute node and populate the LocalEnvironment of the message with the identifiers of one or more Label nodes that introduce the next sequence of processing for the message.

- Typically, a Label node connects to a subflow that processes each message in a specific way, and either ends in an output node or in another RouteToLabel node.

Terminals:

Out : The output terminal to which the message is routed.

RouteToLabel node :

- Use the RouteToLabel node in combination with one or more Label nodes to dynamically determine the route that a message takes through the message flow, based on its content.

-The RouteToLabel node interrogates the local environment of the message to determine the identifier of the Label node to which to route the message.

- You must precede the RouteToLabel node in the message flow with a Compute node that populates the local environment of the message with the identifiers of one or more Label nodes that introduce the next sequence of processing for the message. The destinations are set up as a list of label names in the local environment tree in a specific location.

Example:

IF InputRoot.XMLNSC.PassengerQuery.ReservationNumber<>'' THEN
  SET OutputLocalEnvironment.Destination.RouterList.DestinationData[1].labelName = 'L1';
ELSE
  SET OutputLocalEnvironment.Destination.RouterList.DestinationData[1].labelName = 'L2';
END IF;

Note :

• A label name in the local environment must match the Label Name property of a corresponding Label node.
• When you configure the Compute node, you must also select a value for the Compute Mode property from the list that includes LocalEnvironment.

Terminals:

In : The input terminal that accepts a message for processing by the node.

Failure : The output terminal to which the message is routed if a failure is detected during processing.

Mode :

This property controls how the RouteToLabel node processes the items in the local environment that is associated with the current message . Valid values are:

• Route To First: removes the first item from the local environment. The current message is routed to the Label node that is identified by labelName in that list item.
• Route To Last (the default): removes the last item from the local environment. The current message is routed to the Label node that is identified by labelName in that list item.

Route node :

-Use the Route node to direct messages that meet certain criteria down different paths of a message flow.

-As an example, you can forward a message to different service providers, based on the request details. You can also use the Route node to bypass unnecessary steps. For example, you can check to see if certain data is in a message, and perform a database lookup operation only if the data is missing. If you set the Distribution Mode property to All, you can trigger multiple events that each require different conditions. For example, you can log requests that relate to a particular account identifier, and send requests that relate to a particular product to be audited.

-You use XPath filter expressions to control processing. A result of a filter expression is cast as Boolean, so the result is guaranteed to be either true or false.

Consider the following example input message:

<EmployeeRecord>
    <EmployeeNumber>00001</EmployeeNumber>
    <FamilyName>Smith</FamilyName>
    <Wage>20000</Wage>
</EmployeeRecord>

and the following XPath filter expressions:

$Root/XMLNSC/EmployeeRecord/EmployeeNumber="00002"|Match
$Root/XMLNSC/EmployeeRecord/EmployeeNumber="00001"|out_exp2

Terminals:

In : The static input terminal that accepts a message for processing by the node.

Match : A dynamic output terminal to which the original message can be routed when processing completes successfully. You can create additional dynamic terminals;

Default : The static output terminal to which the message is routed if no filter expression resolves to true.

Failure : The static output terminal to which the message is routed if a failure is detected during processing.

Filter table :

- A table where all rows are expressions and associated terminal names that define the switching that is performed by this node following evaluation of each filter expression. The full expression is in the format

XPath filter expression, terminal name

- All XPath expressions must start with $Root, $Properties, $LocalEnvironment, $DestinationList, $ExceptionList, or $Environment. If you are creating an expression by hand, you can also start the expression with $Body. However, the XPath Expression Builder and associated validation in the WebSphere Message Broker Toolkit do not support use of the $Body variable. If you are using the XPath Expression Builder, use the $Root variable instead.   

Distribution Mode :

-This property determines the routing behavior of the node when an inbound message matches multiple filter expressions. If you set the Distribution Mode property to First, the message is propagated to the associated output terminal of the first expression in the table that resolves to true. If you set this property to All, the message is propagated to the associated output terminal for each expression in the table that resolves to true. If no output terminal matches, the message is propagated to the Default terminal.

Aggregate Control node :

- Use the AggregateControl node to mark the beginning of a fan-out of requests that are part of an aggregation.

- Aggregation is an extension of the request/reply application model. It combines the generation and fan-out of a number of related requests with the fan-in of the corresponding replies, and compiles those replies into a single aggregated reply message.

- It sends a control message that is used by the AggregateReply node to match the different requests that have been made.

Terminals:

In : The input terminal that accepts a message for processing by the node.

Out : The output terminal to which the original message is routed when processing completes successfully.

Control : The output terminal to which a control message is routed. The control message is sent to a corresponding AggregateReply node. The Control terminal is deprecated in Version 6.0.

Timeout (sec) :

-The amount of time, in seconds, that it waits for replies to arrive at the fan-in.

-The default value is zero; if you accept this default value, the timeout is disabled for fan-outs from this node (that is, it waits for replies indefinitely). If not all responses are received, the message flow continues to wait, and does not complete. Set a value greater than zero to ensure that the message flow can complete, even if not all responses are received.

Timeout location :

- Default('$LocalEnvironment/Aggregation/Timeout')

-The location in the message tree where the aggregation timeout value is defined. The value specified in the message tree overrides the Timeout (sec) property of the AggregateControl node and the timeoutSeconds property of the Aggregation configurable service.

Aggregate Request node :

- Use the AggregateRequest node to record the fact that request messages have been sent. This node also collects information that helps the AggregateReply node to construct the compound response message.

- The information that is added to the message Environment by the AggregateRequest node must be preserved, otherwise the aggregation fails.

Terminals:

In : The input terminal that accepts messages sent as part of an aggregate request.

Out :The output terminal to which the input message is routed when processing completes successfully.

Folder Name : The name that is used as a folder in the AggregateReply node's compound message to store the reply to this request. You must enter a value for this property, but the value does not need to be unique.

Aggregate Reply node :

- Use the AggregateReply node to mark the end of an aggregation fan-in. This node collects replies and combines them into a single compound message.

Terminals:

In : The input terminal that accepts a message for processing by the node.

Control : The input terminal that accepts control messages that are sent by a corresponding AggregateControl node. The Control terminal is deprecated in Version 6.0.

Failure : The output terminal to which the message is routed if a failure is detected during processing.

Unknown : The output terminal to which messages are routed when they cannot be identified as valid reply messages.

Out : The output terminal to which the compound message is routed when processing completes successfully.

Timeout : The output terminal to which the incomplete compound message is routed when the timeout interval that is specified in the corresponding AggregateControl node has expired.

Catch : The output terminal to which the message is routed if an exception is thrown downstream and then caught by this node.

Unknown Message Timeout : The amount of time, in seconds, for which messages that cannot be identified as replies are held before they are propagated to the Unknown terminal.

The default value is zero; if you accept this default value, the timeout is disabled, and unknown messages are propagated to the Unknown terminal upon receipt.

Transaction Mode : If you select the check box (the default), the subsequent message flow is under transaction control. This setting remains true for messages that derive from the output message and are produced by an MQOutput node, unless the MQOutput node explicitly overrides the transaction status. No other node can change the transactional characteristics of the output message.

Collector node :

-Use the Collector node to create message collections from one or more sources based on rules that you configure in the node.

-For example, you might need to extract, combine, and transform information from three different sources. The messages from these different sources might arrive at the input terminals at different times and in an unknown order.A collection is defined by configuring an event handler for each input terminal. Each event handler controls the acceptance of a message into a collection according to the following properties:

• Number of messages
• Collect messages for a set period
• Match the contents of a correlation path
• Match the contents against a correlation pattern

- Use the Collector node to group messages from different input sources for further processing. A message collection can be processed by the following nodes only:

• Compute
• JavaCompute
• PHPCompute

- You can add and configure as many input terminals as required to the Collector node. You can configure the properties of each input terminal separately to control how the messages received on each input terminal are added to the appropriate message collection.

- You can use the Control terminal to trigger the output of completed message collections from the Collector node. Configure the Event coordination property to set the behavior of the Collector node when messages are received on the Control terminal.

- If you use additional instances of a message flow or multiple inputs to the Collector node, you can use the Correlation path and Correlation pattern properties to ensure that related messages are added to the same message collection.

Terminal	Description
Control	The static input terminal that accepts control messages. Any message received by the Control terminal is treated as a control message.
Out	The output terminal to which the complete message collection is routed if the received messages satisfy the configured conditions for the message collection.
Expire	The output terminal to which the incomplete message collection is routed if the received messages do not satisfy the configured conditions within the time specified on the Collection expiry property. If you have not set a value for the Collection expiry property this terminal is not used.
Failure	The output terminal to which the message collection is routed if a failure is detected during processing.
Catch	The output terminal to which the message collection is routed if an exception is thrown downstream and caught by this node.

Collection expiry :The amount of time, in seconds, that the Collector node waits for messages to arrive. After this time an incomplete message collection is expired and propagated to the Expire output terminal.

-If you set this property to zero, the collection expiry is disabled and the Collector node waits for messages indefinitely. Set a value greater than zero to ensure that the message collection is processed, even if not all messages are received. A warning is issued if this property is not set.

Persistence mode : This property specifies whether messages are stored on the queues of the Collector node persistently.