Use the Route node to direct messages that meet certain criteria down different paths of a message flow.
This topic contains the following sections:
As an example, you might need to 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 could 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. For more information about XPath 1.0 query syntax, see XPath.
The Route node is contained in the Routing drawer of the message flow node palette, and is represented in the workbench by the following icon:
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 need to always create this node's first dynamic output terminal, 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 given terminal.
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.
<EmployeeRecord> <EmployeeNumber>00001</EmployeeNumber> <FamilyName>Smith</FamilyName> <Wage>20000</Wage> </EmployeeRecord>and the following XPath filter expressions:
$Body/EmployeeRecord/EmployeeNumber="00002"|Match $Body/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 they appear, 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 example above, the first filter expression, which is associated with the Match terminal, is false because the employee number in the input message is not "00002". So no message is propagated to the Match terminal. The second filter expression is true, so a copy of the input message is routed to the "out_expr2" dynamic terminal. If the employee number in the input message were "00003", and therefore did not match either filter expression, the message would be propagated to the static Default output terminal. If the Distribution Mode property were set to All for this example, the same outcome would be achieved because only one filter expression was true.
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. Depending on the preferences that you have set, you can view the node's properties in the Properties view below the Message Flow editor or in the Properties dialog box. Either click the Properties view tab, or right-click the node and click Properties. 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 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 | The dynamic output terminal to which the original message is routed when processing completes successfully. |
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. |
The Route node can have further dynamic output terminals. Not all dynamic output terminals that are created on a Route node need to be mapped to an expression in the filter table. For unmapped dynamic output terminals, messages are never propagated to them. Several expressions can map to the same single dynamic output terminal. There is no static output terminal to which the message is passed straight through.
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).
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. |
Property | M | C | Default | Description |
---|---|---|---|---|
Filters | 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 nameAll XPath expressions must start with $Root, $Body, or $LocalEnvironment. Expressions are evaluated in the order in which they appear 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 and every expression in the table that resolves to true. If no output terminal matches, the message is propagated to the Default terminal. |