Route node

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

The Route node is available in the following operation modes:
  • Developer
  • Application Integration Suite
  • Standard
  • Advanced
  • Scale
For more information, see Operation modes.

This topic contains the following sections:

Purpose

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. For more information about XPath 1.0 query syntax, see W3C XPath 1.0 Specification.

The Route node is contained in the Routing drawer of the message flow node palette, and is represented in the IBM® Integration Toolkit by the following icon:

Route node icon

Using this node in a message flow

The Route node has one input terminal and a minimum of three output terminals: Match, Default, and Failure. The Default and Failure output terminals are static, so they are always present on the node. The dynamic Match terminal is created automatically each time a new Route node is selected and used in the Message Flow editor. This behavior means that you do not always have to create the first dynamic output terminal for this node, which is the minimum number of terminals needed for this node to operate. You can rename this dynamic terminal if "Match" is not an appropriate name.

A message is copied to the Default terminal if none of the filter expressions are true. If an exception occurs during filtering, the message is propagated to the Failure terminal. The Route node can define one or more dynamic output terminals. For all terminals, the associated filter expression is applied to the input message and, if the result is true, a copy of the message is routed to the specified terminal. The Route node determines the order in which the terminals are driven. The node always propagates messages to the terminals in the order in which they appear in the filter table.

Each filter expression is applied to the input message in the order that is given in the filter table. If the result is true, a copy of the message is routed to its associated dynamic output terminal. If you set the Distribution Mode property to First, application of all filter expressions might not occur.

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

In this example, the Distribution Mode property is set to First. The Route node processes the XPath filter expressions, in the order in which the are displayed, against the input message. Because the Distribution Mode property is set to First, the unmodified input message is propagated only once to the dynamic output terminal that is mapped to the first filter expression that resolves to true. In the previous example, the first filter expression, which is associated with the Match terminal, is false because the employee number in the input message is not "00002". Therefore no message is propagated to the Match terminal. The second filter expression is true, therefore a copy of the input message is routed to the "out_expr2" dynamic terminal. If the employee number in the input message is "00003", and therefore does not match either filter expression, the message is propagated to the static Default output terminal. If the Distribution Mode property is set to All for this example, the same outcome is achieved because only one filter expression is true.

Terminals

The Route node terminals are described in the following table.

Terminal Description
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; see 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.

Dynamic terminals

The Route node can have further dynamic output terminals. Not all dynamic output terminals that are created on a Route node have to be mapped to an expression in the filter table. Messages are never propagated to unmapped dynamic output terminals. Several expressions can map to the same single dynamic output terminal. No static output terminal exists to which the message is passed straight through. For more information about using dynamic terminals, see Using dynamic terminals.

Properties

When you have put an instance of the Route node into a message flow, you can configure it. For more information, 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 properties that do not have a default value defined) are marked with an asterisk.

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 Route node Description properties are described in the following table.
Property M C Default Description
Node name No No The node type, Route 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 Route node Basic properties are described in the following table.
Property M C Default Description mqsiapplybaroverride command property
Filter table Yes No   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 IBM Integration Toolkit do not support use of the $Body variable. If you are using the XPath Expression Builder, use the $Root variable instead.

Expressions are evaluated in the order in which they are displayed in the table. To improve performance, specify the expressions that are satisfied most frequently at the top of the filter table. Typically, you specify a unique terminal name for each XPath expression.

 
Distribution Mode No Yes All 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. distributionMode
The Monitoring properties of the node are described in the following table.
Property M C Default Description
Events No No None Events that you have defined 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.