Contact Us 1-800-596-4880

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.

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

  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

    Click for more detail

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

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

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

      drag_attachment
    4. Next, add a message processor within the "Default" box to set the default routing option. In our example below, we add an FTP connector.

      drag_FTP
  2. Open the Choice Flow Control’s Properties Editor (below)

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

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

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

    choice2
  6. 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.

  7. Click OK to save the routing configurations.

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

  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. 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>
  2. Configure the contents of one or more additional when elements to define multiple routing options for your choice element. Refer to code sample below.

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

Studio Visual Editor

  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 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'] &gt; 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'] &gt; 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.