Choice Flow Control Reference
Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version. |
The choice flow control dynamically routes messages based on message payload or properties. It adds conditional programming to a flow, similar to an if/then/else
code block.
A choice flow control uses expressions to evaluate the content of a message, then it routes the message to one of the routing options within its scope (see image below). It directs messages to the first routing option in the scope that matches the routing configurations ( i.e. evaluates to true). If none of expressions evaluate to true, the choice flow control directs the message to the default (i.e. else
) route.
Adding the Choice Flow Control
Studio Visual Editor
In Studio, drag the Choice icon from the Studio palette to the canvas, positioning it within the sequence of building blocks that form the flow (below).
Studio XML or Standalone
Add a choice
element in your flow, with one attribute and, at minimum, two child elements as per the table below. Refer to the code sample below.
Attribute | Value |
---|---|
doc:name |
unique name for the choice element (not required for Standalone) |
Child Element |
Attribute |
when |
expression |
otherwise |
n/a |
<flow name="New_Studio_ProjectFlow1" doc:name="New_Studio_ProjectFlow1">
<http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="HTTP"/>
<choice doc:name="Choice">
<when expression="">
</when>
<otherwise>
</otherwise>
</choice>
<scripting:component doc:name="Groovy">
<scripting:script engine="Groovy"/>
</scripting:component>
</flow>
Configuring the Choice Flow Control
To configure the choice flow control, you need to determine the following message routing details:
-
the Content the choice flow router should evaluate to determine routing
-
the Number of routing options with which to supply the choice flow control
-
the processing Mule should perform for each routing option
-
the Default routing option
Once you have determined your routing goals, follow this procedure to define the routing options, then the routing instructions.
Studio Visual Editor
-
Insert message processors within the dashed line area that signifies the choice flow control scope to define the routing options, making sure to place one of them within the "Default" box to define it as the default routing option. You can place several message processors in a chain for each routing option, as needed. In our example, shown below, we have defined three routing options to reply in Spanish, French, or English:
Click for more detail
-
Drag, then drop a message processor into the blank area above the default box within the dashed line which signifies the scope of the choice flow control. This is the first message processor in the flow control’s first routing option. In the example (below), we use the Expression transformer as the first message processor in the first routing option.
-
To add additional processing steps to a routing option, drag and drop another message processor into the space immediately after the message processor you just added, still within the scope of the choice flow control. In the example (below), we add the Session Variable transformer as the second message processor in the first routing option.
-
To add another routing option, drag and drop a message processor into the choice flow control scope. In the example below, we add an Attachment transformer as our second routing option.
-
Next, add a message processor within the "Default" box to set the default routing option. In our example below, we add an FTP connector.
-
-
Open the Choice Flow Control’s Properties Editor (below)
-
Mule displays a table with two columns: When and Route Message to. Notice, in the image above, that Mule displays a line item for each routing option. Mule identifies each routing option by its first message processor. Double-click the first empty line item in the Route Message to column to open the Route Properties panel (below).
-
In the Expression field, enter an expression for the choice router to use to evaluate the contents of a message. For example: #[payload['name'] == null]
-
Repeat the two preceding steps until you have supplied the choice flow control with a When expression for each non-default routing option (see example below).
-
Double-click the Default line item to open its Route Properties panel. Notice that:
-
you cannot edit the Expression field
-
the Otherwise box is checked
The Otherwise box identifies this route as the Default for the choice flow control. If the flow control cannot route a message to any of the preceding routing options in its scope, it directs the message to the default route.
-
-
Click OK to save the routing configurations.
-
As it processes messages, Mule evaluates the expressions defined in your routing options in order, top down, until one of them evaluates to "true". If necessary, drag and drop building blocks within the choice flow control scope on the canvas to reorder routing options.
Studio XML Editor or Standalone
-
To the first when element within your choice element, add message processors as child elements to form a routing option to which the choice element can direct messages. In the code sample below, we have added an expression-transformer and a session-variable-transformer.
<flow name="New_Studio_ProjectFlow1" doc:name="New_Studio_ProjectFlow1"> <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="HTTP"/> <choice doc:name="Choice"> <when expression=""> <expression-transformer doc:name="Expression"/> <session-variable-transformer doc:name="Session Variable"/> </when> <otherwise> </otherwise> </choice> <scripting:component doc:name="Groovy"> <scripting:script engine="Groovy"/> </scripting:component> </flow>
-
Configure the contents of one or more additional when elements to define multiple routing options for your choice element. Refer to code sample below.
-
Configure the contents of the otherwise child element to define the default routing option to which your choice router can direct messages if all the previous when expressions evaluate to false. Refer to code sample below.
<flow name="New_Studio_ProjectFlow1" doc:name="New_Studio_ProjectFlow1"> <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="HTTP"/> <choice doc:name="Choice"> <when expression=""> <expression-transformer doc:name="Expression"/> <session-variable-transformer doc:name="Session Variable"/> </when> <when expression=""> <attachment-transformer doc:name="Attachment"/> </when> <otherwise> <ftp:outbound-endpoint host="localhost" port="21" responseTimeout="10000" doc:name="FTP"/> </otherwise> </choice> <scripting:component doc:name="Groovy"> <scripting:script engine="Groovy"/> </scripting:component> </flow>
-
For each when element, enter an expression for the choice router to use to evaluate the contents of a message. If, during processing, the expression associated with a routing option evaluates to true, Mule directs the message to that route. Refer to example expression below.
<when expression="#[payload['name'] == null]">
-
As it processes messages, Mule evaluates the expressions defined in your routing options in the order they appear in the config, top down, until one of them evaluates to "true". Adjust the order of the when elements in your flow with this in mind.
Configuration Summary
Element | Description |
---|---|
choice |
Dynamically routes messages based on message payload or properties, adding conditional programming to a flow, similar to an if/then/else code block. |
Element Attribute | Description |
---|---|
doc:name |
Customize to display a unique name for the flow control in your application. |
Child Element | Description |
---|---|
when |
Use to define all non-default routing options within the choice flow control. |
Child Element Attribute | Value | Description |
---|---|---|
expression |
Mule expression |
Use MEL to define an expression that the choice router will use to evaluate the contents of a message. If the expression evaluates to "true", Mule directs the message to this routing option. |
Child Element | Description |
---|---|
otherwise |
Use to define the default routing option for the message, should none of the preceding when expressions evaluate to "true" |
Changing the Default Route
You can change the choice flow control configuration to identify a different default routing option.
Studio Visual Editor
-
Open the Choice Flow Control’s Properties Editor, then, in the table, double-click the line item of whichever routing option that you would like to specify as the new default route.
-
Check the Otherwise box (see below), then click OK.
-
Mule applies the Default label to the new default routing option in the table on the Properties Editor (below). (Note that the English routing option now needs a "when" expression defined.)
-
Define a when expression for the routing option previously identified as the default. (In the example, the FTP routing option.)
Studio XML Editor or Standalone
Adjust your XML configuration to swap the contents of a when
element and the otherwise
element.
The code sample below has been adjusted to make the Spanish language the default routing option and change the English language to a when
element. Note that the otherwise
element requires no further configuration, but we defined a new expression for the new when
element.
<flow name="ChoiceFlowFlow1" doc:name="ChoiceFlowFlow1">
<http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="HTTP"/>
<choice doc:name="Choice">
<when expression="#[payload['name'] == null]">
<expression-transformer doc:name="Expression"/>
<session-variable-transformer doc:name="Session Variable"/>
</when>
<when expression="#[payload['amount'] > 30000]">
<ftp:outbound-endpoint host="localhost" port="21" responseTimeout="10000" doc:name="FTP"/>
</when>
<otherwise>
<attachment-transformer doc:name="Attachment"/>
</otherwise>
</choice>
<scripting:component doc:name="Groovy">
<scripting:script engine="Groovy"/>
</scripting:component>
</flow>
Complete Example Code
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:scripting="http://www.mulesoft.org/schema/mule/scripting" xmlns:ftp="http://www.mulesoft.org/schema/mule/ee/ftp" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/ee/ftp http://www.mulesoft.org/schema/mule/ee/ftp/current/mule-ftp-ee.xsd
http://www.mulesoft.org/schema/mule/scripting http://www.mulesoft.org/schema/mule/scripting/current/mule-scripting.xsd">
<flow name="choiceFlow1" doc:name="choiceFlow1">
<http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="HTTP"/>
<choice doc:name="Choice">
<when expression="#[payload['amount'] > 30000]">
<attachment-transformer doc:name="Attachment"/>
</when>
<when expression="#[payload['name'] == null]">
<expression-transformer doc:name="Expression"/>
<session-variable-transformer doc:name="Session Variable"/>
</when>
<otherwise>
<ftp:outbound-endpoint host="localhost" port="21" responseTimeout="10000" doc:name="FTP"/>
</otherwise>
</choice>
<scripting:component doc:name="Groovy">
<scripting:script engine="Groovy"/>
</scripting:component>
</flow>
</mule>
See Also
-
For more information on the Choice Flow Control, see the Choice section on the Routing Message Processors page.