Choice Flow Control Reference
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 (evaluates to true). If none of expressions evaluate to true, the choice flow control directs the message to the default (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 processors that form the flow (below).
Studio XML Editor 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 |
<http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
<flow name="New_Studio_ProjectFlow1" doc:name="New_Studio_ProjectFlow1">
<http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
<expression-filter expression="#[message.inboundProperties.'http.request.uri' != '/favicon.ico']" doc:name="Expression"/>
<set-variable variableName="language" value="#[message.inboundProperties.'http.query.params'.language]" doc:name="Set Language Variable"/>
<choice doc:name="Choice">
<when expression="">
</when>
<otherwise>
</otherwise>
</choice>
<logger message="#[payload]" level="INFO" doc:name="Logger"/>
</flow>
Configuring the Choice Flow Control
To configure the choice flow control, you need to determine the following message routing details:
-
What content the choice flow router evaluates to determine routing
-
Number of routing options for the choice flow control
-
What processing Mule performs for each routing option
-
Default routing option
After you determine your routing goals, follow this procedure to define the routing options, then the routing instructions.
Studio Visual Editor
-
Insert message processors, in this example Set Payload processors within the dashed line area that signifies the choice flow control scope to define the routing options. Add a Variable within the "Default" box along with another Set Payload item. The default blocks define the default routing option. You can place several message processors in a chain for each routing option, as needed. In the following example are three routing options to reply in Spanish, French, or English:
-
Click the Choice Router processor to open its Properties Editor. You can enter Mule expressions to define the routing logic that Mule applies to incoming messages (see table below; detailed instructions follow).
When Route Message to #[flowVars.language == 'Spanish']
Set Payload
#[flowVars.language == 'French']
Set Payload
Default
Variable
-
In the table, double-click the first empty row under When:
-
In the Route Properties dialog, enter:
#[flowVars.language == 'Spanish']
-
Click OK. This expression tells Mule to look for a flow variable called
language
on the incoming message and check whether it equals Spanish. If this expression evaluates to true, Mule routes the message to the message processor in that path. -
Click the next empty row, and enter:
#[flowVars.language == 'French']
Just as in the previous row, this expression tells Mule to look for a flow variable called
language
in the incoming message. This time, the expression indicates Mule should check whetherlanguage
equals French. If this expression evaluates to true, Mule routes the message to the message processor in that path. -
Click OK to save the routing configurations.
-
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.
-
-
Next, click the topmost Set Payload processor within your Choice Router scope to open its Properties Editor and set Value to: `Hola! `
If Mule finds the flow variable
language=Spanish
, your message produces this payload as a response. -
Click the next Set Payload processor for Reply in French and set the value to:
Bonjour!
If Mule finds the flow variable
language=French
, your message produces this payload as a response. -
Click the Variable Transformer inside the Default box to open its Properties Editor, then configure it as:
This Variable Transformer, and the Set Payload that follows it, are only invoked if neither of the expressions in the choice routing logic evaluate to true. Thus, if Mule does not find either the flow variable
language=Spanish
or the flow variablelanguage=French
, Mule routes the message to this default processing option, which sets the flow variablelanguage
with the valueEnglish
.Note that in this configuration you are setting a literal value for the variable, rather than using Mule expression language to extract a value from the message, as you did in the previous Variable Transformer. -
Click the Set Payload after the Variable Transformer inside the Default box to open its Properties Editor, then configure it as:
This Set Payload transformer sets a payload for the default option you configured above in your choice routing logic.
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 processors 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. Add as many additionalwhen
elements as needed.<http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/> <flow name="New_Studio_ProjectFlow1" doc:name="New_Studio_ProjectFlow1"> <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/> <expression-filter expression="#[message.inboundProperties.'http.request.uri' != '/favicon.ico']" doc:name="Expression"/> <set-variable variableName="language" value="#[message.inboundProperties.'http.query.params'.language]" doc:name="Set Language Variable"/> <choice doc:name="Choice"> <when expression=""> <set-payload value="Hola!" doc:name="Reply in Spanish"/> </when> <when expression=""> <set-payload value="Bonjour!" doc:name="Reply in French"/> </when> <otherwise> </otherwise> </choice> <logger message="#[payload]" level="INFO" doc:name="Logger"/> </flow>
-
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.<http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/> <flow name="New_Studio_ProjectFlow1" doc:name="New_Studio_ProjectFlow1"> <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/> <expression-filter expression="#[message.inboundProperties.'http.request.uri' != '/favicon.ico']" doc:name="Expression"/> <set-variable variableName="language" value="#[message.inboundProperties.'http.query.params'.language]" doc:name="Set Language Variable"/> <choice doc:name="Choice"> <when expression=""> <set-payload value="Hola!" doc:name="Reply in Spanish"/> </when> <when expression=""> <set-payload value="Bonjour!" doc:name="Reply in French"/> </when> <otherwise> <set-variable variableName="language" value="English" doc:name="Set Language to English"/> <set-payload value="Hello!" doc:name="Reply in English"/> </otherwise> </choice> <logger message="#[payload]" level="INFO" doc:name="Logger"/> </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="#[flowVars.language == 'Spanish']">
-
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 |
Element Attribute | Description |
---|---|
doc:name |
Customize to display a unique name for the flow control in your application. Note: Attribute not required in Mule Standalone configuration. |
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 |
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 English 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.
<http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
<flow name="New_Studio_ProjectFlow1" >
<http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
<expression-filter expression="#[message.inboundProperties.'http.request.uri' != '/favicon.ico']" doc:name="Expression"/>
<set-variable variableName="language" value="#[message.inboundProperties.'http.query.params'.language]" doc:name="Set Language Variable"/>
<choice doc:name="Choice">
<when expression="#[flowVars.language == 'french']">
<set-payload value="Bonjour!" doc:name="Reply in French"/>
</when>
<otherwise >
<set-variable variableName="language" value="spanish" doc:name="Set Language to Spanish"/>
<set-payload value="Hola!" doc:name="Reply in Spanish"/>
</otherwise>
<when expression="#[flowVars.language == 'english']">
<set-payload value="Hello!" doc:name="Reply in English"/>
</when>
</choice>
<logger message="#[payload]" level="INFO" doc:name="Logger"/>
</flow>
Complete Example Code
<mule xmlns:vm="http://www.mulesoft.org/schema/mule/vm" xmlns:scripting="http://www.mulesoft.org/schema/mule/scripting" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" 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/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd
http://www.mulesoft.org/schema/mule/scripting http://www.mulesoft.org/schema/mule/scripting/current/mule-scripting.xsd
http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd">
<http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
<flow name="New_Studio_ProjectFlow1" >
<http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
<expression-filter expression="#[message.inboundProperties.'http.request.uri' != '/favicon.ico']" doc:name="Expression"/>
<set-variable variableName="language" value="#[message.inboundProperties.'http.query.params'.language]" doc:name="Set Language Variable"/>
<choice doc:name="Choice">
<when expression="#[flowVars.language == 'french']">
<set-payload value="Bonjour!" doc:name="Reply in French"/>
</when>
<when expression="#[flowVars.language == 'spanish']">
<set-payload value="Hola!" doc:name="Reply in Spanish"/>
</when>
<otherwise >
<set-variable variableName="language" value="English" doc:name="Set Language to English"/>
<set-payload value="Hello!" doc:name="Reply in English"/>
</otherwise>
</choice>
<logger message="#[payload]" level="INFO" doc:name="Logger"/>
</flow>
</mule>
The flow for this example is:
See Also
-
For more information on the Choice Flow Control, see the Choice section on the Routing Message Processors page.