Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.6)
  3. Developing
  4. Routers

  5. Choice Flow Control Reference

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 (evaluates to true). If none of expressions evaluate to true, the choice flow control directs the message to the default (else) route.

Choice_schematic

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).

choice+flow+2

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:

  • Content the choice flow router should evaluate to determine routing

  • Number of routing options with which to supply the choice flow control

  • What processing Mule should perform 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.

  1. 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:

    Studio_Choice_routingoptions

  2. Click the Choice Router building block to open its Properties Editor. Here, 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

  3. In the table, double-click the first empty row under When:

    ChoiceClickHere

  4. In the Route Properties dialog, enter: #[flowVars.language == 'Spanish']

    ChoiceRouteProperties

  5. 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.

  6. 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 on the incoming message. This time, the expression indicates Mule should check whether language equals French. If this expression evaluates to true, Mule routes the message to the message processor in that path.

  1. Click OK to save the routing configurations.

  2. Double-click the Default line item to open its Route Properties panel.

Notice that:

  1. You cannot edit the Expression field

  2. The Otherwise box is checked

    Studio_Choice_default_routeproperties

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.

  1. Next, click the topmost Set Payload building block within your Choice Router scope to open its Properties Editor and set Value to: `Hola! `

    HolaAmigos

If Mule finds the flow variable language=Spanish, your message produces this payload as a response.

  1. Click the next Set Payload building block 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.

  1. Click the Variable Transformer inside the Default box to open its Properties Editor, then configure it as:

    VarSetLangToEnv

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 variable language=French, Mule routes the message to this default processing option, which sets the flow variable language with the value English.

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.

  1. Click the Set Payload after the Variable Transformer inside the Default box to open its Properties Editor, then configure it as:

    SetPayLoadEnglish

This Set Payload transformer sets a payload for the default option you configured above in your choice routing logic.

  1. 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.

[tab,title="Studio XML Editor or Standalone"]

  1. 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 additional when 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>

  2. 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>

  3. 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']">

  4. 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.

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 when expressions evaluate to "true"

Changing the Default Route

You can change the choice flow control configuration to identify a different default routing option.

  1. 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.

    choice+select+default+1

  2. Check the Otherwise box (see below), then click OK.

    select+default

  3. 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.)

    select+default+2

  4. Define a when expression for the routing option previously identified as the default. (In the example, the english routing option.)

[tab,title="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:

FinalFlow

See Also

  • For more information on the Choice Flow Control, see the Choice section on the Routing Message Processors page.