---
schema_version: "1"
id: 38202e2572d8aa20fd3f4487f1ee287c72a2a18a5d624354ebe6dc4d625e2987
title: Choice Router
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-runtime/4.6/choice-router-concept.md
canonical_url: https://docs.mulesoft.com/mule-runtime/4.6/choice-router-concept
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 4c9f654af27d5ca9085a35aeb92cf825b3ccd27e9ca3248b98c0f03c75fc1aee
description: MuleSoft Documentation Site
release: "4.6"
latest: false
---
---
product: Mule Runtime
version: 4.6
---

# Choice Router

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The Choice router dynamically routes messages through a flow according to a set of DataWeave
expressions that evaluate message content. Each expression is associated with a different routing
option. The effect is to add conditional processing to a flow, similar to an `if`/`then`/`else` code
block in most programming languages.

Only one of the routes in the Choice router executes, meaning that the first expression that
evaluates to `true` triggers that route’s execution and the others are not checked. If none of the
expressions are `true`, then the default route executes.

![Choice Router Schematic](/mulesoft/current/en-us/mule-runtime/4.6/_images/component-choice-schematic.png)

Figure 1. Schematic diagram of a Choice router with three options, one being the default option

## Configuration

To configure the Choice router, specify one or more conditions to evaluate, and the message
processors that execute when any condition evaluates to `true`. Additionally, configure a default
route that executes when none of the defined conditions are `true`.

### Anypoint Studio Configuration

To configure the Choice router in Studio, follow these steps:

![Choice configuration Studio](/mulesoft/current/en-us/mule-runtime/4.6/_images/mruntime-choice-configuration-studio.png)

1.  Drag the **Choice** component to any point of the flow.

2.  Click **When**, inside the Choice router, and configure the **Expression** value in the
    properties window to specify the condition to evaluate.

3.  Drag message processors inside **When** to specify the processors to execute when the condition
    is met.

4.  Drag message processors inside **Default** to specify the processors to execute when none of the
    defined conditions are met.

### XML Configuration

Following is the basic XML structure for a Choice router:

```xml
<choice doc:name="Choice">
  <when expression=${expressionToEvaluate}> (1)
  	<!-- Message processors --> (2)
  </when>
  <otherwise>
    <!-- Message processors--> (3)
  </otherwise>
</choice>
```

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>The <code>expression</code> attribute has the condition to evaluate.</td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Add any number of message processors to execute if <code>expression</code> evaluates to <code>true</code>.</td></tr><tr><td><i data-value="3"></i><b>3</b></td><td>Add any number of message processors to execute if none of the conditions evaluates to <code>true</code>.</td></tr></tbody></table>

## Adding Routes to the Choice Router

By default, the Choice router has one route option that executes when the configured DataWeave
expression evaluates to `true`, and a default route that executes when none of the expressions in
the existing routes are `true`. Add more routes when you need to evaluate more than one condition
and then execute different operations depending on which condition is met.

### Add Routes by Dragging Components in Studio

From **Mule Palette** in Anypoint Studio, click any component and drag it into the Choice router,
where you see a vertical black line:

![add+route+option](/mulesoft/current/en-us/mule-runtime/4.6/_images/mruntime-choice-add-route.png)

### Add Routes by Editing the XML

You can also add additional route options to a Choice router by modifying the XML configuration
file:

1.  In Studio, right-click the Choice router and select **Go to XML…​**.

2.  Inside the `<choice>` element, add a `<when>` element:

    ```xml
    <!--Content based routing example flow -->
    <flow name="content-based-routingFlow">
      <http:listener config-ref="HTTP_Listener_config" path="/" doc:name="Listener"/>
      <set-variable variableName="language" value="#[attributes.queryParams.language]" doc:name="Set Variable" />
      <!-- Choice router block-->
      <choice doc:name="Choice" >
        <when expression="#[vars.language == 'Spanish']" >
          <set-payload value="Hola!" doc:name="Reply in Spanish" />
        </when>
        <when expression="#[vars.language == 'French']" >
          <set-payload value="Bonjour!" doc:name="Reply in French" />
        </when>
        <!-- This is the new route option added in this step -->
        <when>
        </when>
        <otherwise>
          <flow-ref name="reply-in-default-languageSub_Flow" doc:name="reply-in-default-languageSub_Flow" />
        </otherwise>
      </choice>
      <logger level="INFO" doc:name="Log the reply" message='#["The reply $(payload) means hello in $(vars.language)" ]'/>
    </flow>
    ```

After adding a new `<when>` element, the new route option shows in the Message Flow view:
![new-route-option](/mulesoft/current/en-us/mule-runtime/4.6/_images/mruntime-choice-new-route.png)

## Example Project

You can use Anypoint Studio to download the example project _Content-Based Routing_ from Anypoint
Exchange. This project presents a working example of a flow that uses the Choice router.

![choice-router-example](/mulesoft/current/en-us/mule-runtime/4.6/_images/mruntime-choice-example.png)

Figure 2. Flow with a Choice router with three options, one being the default option

To download and open this example project:

1.  Click the Exchange icon (![3%](/mulesoft/current/en-us/mule-runtime/4.6/_images/mruntime-exchange-icon.png)) in Anypoint Studio.

2.  In the left panel, click **All assets**.

3.  In the window that opens, log in to Anypoint Exchange and search for the example project
    Content-Based Routing.

4.  Click the Open icon (![6%](/mulesoft/current/en-us/mule-runtime/4.6/_images/mruntime-open-exchange-icon.png)).

### Behavior of the Example Project

When you run the project as a Mule application, the application performs the following actions:

1.  Listens for messages.

2.  Passes messages to a Set Variable component that sets the variable `language` to the language
    that is passed in the message by the parameter `language`.

3.  Uses a Choice router to find out whether each message contains a `language` attribute. The
    presence and value of this attribute determine how the Choice router routes the message:

    - If the value is `French`, the router routes the message to a Set Payload component that is
      named _Reply in French_. This latter component returns the message `Bonjour!` to the
      requester.

    - If the value is `Spanish`, the router routes the message to a Set Payload component that is
      named _Reply in Spanish_. This latter component returns the message `Hola!` to the requester.

    - If the message contains no `language` attribute, the router routes the message to the default
      path, which is a subflow that:

4.  Logs the message "No language specified. Using English as a default." to the console

5.  Sets the value of `language` to `English`.

6.  Returns the message `Hello!`.

The example project demonstrates that, when you are planning to route messages in a flow by using a
Choice router, there are four aspects to planning that you need to consider:

- The content that the Choice router evaluates to determine how it routes messages

- The number of routes

- The default routing option

- The processing that the flow performs for each routing option

## Example XML

Following is the XML code for the Choice router example:

```xml
<mule 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:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" >
		<http:listener-connection host="0.0.0.0" port="8081" />
	</http:listener-config>
	<flow name="content-based-routingFlow" >
		<http:listener config-ref="HTTP_Listener_config" path="/" doc:name="Listener" />
		<set-variable variableName="language" value="#[attributes.queryParams.language]" doc:name="Set Variable" />
    <!-- START OF CHOICE BLOCK-->
		<choice doc:name="Choice" >
			<when expression="#[vars.language == 'Spanish']" >
				<set-payload value="Hola!" doc:name="Reply in Spanish" />
			</when>
			<when expression="#[vars.language == 'French']" >
				<set-payload value="Bonjour!" doc:name="Reply in French" />
			</when>
			<otherwise>
				<flow-ref name="reply-in-default-languageSub_Flow" doc:name="reply-in-default-languageSub_Flow" />
			</otherwise>
		</choice>
    <!-- END OF CHOICE BLOCK-->
		<logger level="INFO" doc:name="Log the reply" message='#["The reply $(payload) means hello in $(vars.language)" ]'/>
	</flow>
  <sub-flow name="reply-in-default-languageSub_Flow" >
		<logger level="INFO" doc:name="Logger" message="No language specified. Using English as a default. "/>
		<set-variable variableName="language" value="English" doc:name="Set Language to English" />
		<set-payload value="Hello!" doc:name="Reply in English" />
	</sub-flow>
</mule>
```

## Choice Router XML Reference

A Choice flow control component contains these elements:

- A single root element `<choice>`

- A `<when>` child element for each routing option, each with an expression to match

- Optionally, an `<otherwise>` child element of Choice that handles all cases where none of the
  expressions on the `<when>` elements evaluate to `true`

- Components that are conditionally executed under each of the choices are defined as child elements
  of the `when` and `otherwise` elements

### Properties of <choice>

<table><colgroup><col> <col></colgroup><thead><tr><th>Property</th><th>Description</th></tr></thead><tbody><tr><td><p>Business Events</p></td><td><div><div><p>For activating the Business Events feature:<br></p></div><div><div><pre><code data-lang="xml">&lt;choice doc:name="Choice" tracking:enable-default-events="true" &gt;</code></pre></div></div></div></td></tr></tbody></table>

### Properties of <when>

<table><colgroup><col> <col></colgroup><thead><tr><th>Property</th><th>Description</th></tr></thead><tbody><tr><td><p>Expression (<code>expression</code>)</p></td><td><div><div><p>Expression in DataWeave language to evaluate input.<br>If the expression evaluates to <code>true</code>, this routing option is used:<br></p></div><div><div><pre><code data-lang="xml">&lt;when expression="#[vars.language == 'Spanish']" &gt;</code></pre></div></div></div></td></tr></tbody></table>

## See Also

- [Flows and Subflows](https://docs.mulesoft.com/mule-runtime/4.6/about-flows)

- [Extract Data](https://docs.mulesoft.com/dataweave/latest/dataweave-cookbook-extract-data)

- [DataWeave Scripts](https://docs.mulesoft.com/dataweave/latest/dataweave-language-introduction)

- [Business Events](https://docs.mulesoft.com/mule-runtime/4.6/business-events)