Choice Router | MuleSoft Documentation
# Choice Router
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.
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:
  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:
```
<choice doc:name="Choice">
 <when expression=${expressionToEvaluate}> **(1)**
 	<!-- Message processors --> **(2)**
 </when>
 <otherwise>
  <!-- Message processors--> **(3)**
 </otherwise>
</choice>
```

The `expression` attribute has the condition to evaluate.  
---  
Add any number of message processors to execute if `expression` evaluates to `true`.  
Add any number of message processors to execute if none of the conditions evaluates to `true`.  
## 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 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:
```
<!--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: 
## 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.
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 () 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 ().


### 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:
```
<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
## 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>
Property | Description  
---|---  
Business Events |  For activating the Business Events feature: ```
<choice doc:name="Choice" tracking:enable-default-events="true" >
```
  
### Properties of <when>
Property | Description  
---|---  
Expression (`expression`) |  Expression in DataWeave language to evaluate input. If the expression evaluates to `true`, this routing option is used: ```
<when expression="#[vars.language == 'Spanish']" >
```
  
## See Also
  * Flows and Subflows
  *   *   *