Mule Expression Language Basic Syntax

A flexible tool, you can use Mule Expression Language (MEL) to evaluate many kinds of expressions, including constants, simple operands, operations with multiple values, or method calls on objects. You can also use MEL to perform regex or XPath3 functions. Thus, though the syntax is consistent, the expressions you write or come across in Mule applications may take many different forms, depending on their purpose. This document aims to offer insight into the basic syntax rules for MEL so you can write, or parse the functionality of MEL expressions.

For further details on MEL syntax, see the full Mule Expression Language Reference material.

Prerequisites

This document assumes that you have read Mule Expression Language MEL and have studied the Mule message structure.

Basic Syntax

Essentially, you use MEL expressions in combination with other things such as operands and operators to dynamically return a value. Mule evaluates the expression at runtime, and the message processor within which the MEL expression resides uses the result to act upon the message payload, properties or variables. For example, you can use an expression inside a Set Payload message processor to extract a username from an inboundProperty on a message, then set it as the payload. See example below.

Studio Visual Editor

XML Editor or Standalone

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
    xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
    xmlns:http="http://www.mulesoft.org/schema/mule/http"
    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_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
    <sub-flow name="mel_exampleSub_Flow">
        <set-payload value="#[message.inboundProperties.username]" doc:name="Set Payload"/>
    </sub-flow>
</mule>

Definitions

A few definitions before diving into syntax rules.

Expression

In Mule, an expression is a string, enclosed with #[ ]. At runtime, Mule uses MEL (as the default expression evaluator) to determine the value of the expression. Mule supports other types of expressions as well (which must also be enclosed in #[ ]), they are used to evaluate your expression if it can’t be recognized as MEL.

MEL expressions follow a Java-like syntax. Overall, the basic operators and operands are conventional and predictable (for example, 2 + 2 == 4 returns true). The simplest kind of expression is the one that provides access to information from the message (for example, message.id). The Examples in a section below offers some insight into how you can use MEL expressions to access information, perform comparisons, and invoke methods.

It’s important to note that MEL is an expression language, not a programming language. Thus, an expression in Mule:

Always resolves to a single value
Cannot return type void

Context Objects, Variables, and Fields

The term Context Object forms the first part of the simplest form of a MEL expression; the second part is the Field (see image below, left). Use a Variable in a MEL expression to access information contained within a Flow Variable or Session Variable on your Mule message. Itself a top-level identifier in MEL, a variable does not require that you define a context object in an expression (see second image below).

The tables below list the Context Objects and Variables available for use in Mule, and the corresponding Fields you can use with them.

Context Objects	Description	Field
server	The operating system on which the message processor is running.	dateTime env fileSeparator host ip locale javaVendor javaVersion nanoSeconds osArch osName osVersion systemProperties timeZone tmpDir userDir userHome userName
mule	The Mule instance on which the application is running.	clusterId home nodeId version
application	The user application within which the current flow is deployed.	encoding name registry standalone workDir
message	The package (payload, attachments, properties) that the message processor is processing.	id rootId correlationId correlationSequence correlationGroupSize replyTo dataType payload inboundProperties inboundAttachments outboundProperties outboundAttachments

Context Objects

Description

Field

server

The operating system on which the message processor is running.

dateTime
env
fileSeparator
host
ip
locale
javaVendor
javaVersion
nanoSeconds
osArch
osName
osVersion
systemProperties
timeZone
tmpDir
userDir
userHome
userName

mule

The Mule instance on which the application is running.

clusterId
home
nodeId
version

application

The user application within which the current flow is deployed.

encoding
name
registry
standalone
workDir

message

The package (payload, attachments, properties) that the message processor is processing.

id
rootId
correlationId
correlationSequence
correlationGroupSize
replyTo
dataType
payload
inboundProperties
inboundAttachments
outboundProperties
outboundAttachments

Variables	Description	Field
flowVars	A variable set on the message; flow variables persist only within the flow in which they were created.	n/a
sessionVars	A session variable set on the message; session variables persist across flows within an application.	n/a

Variables

Description

Field

flowVars

A variable set on the message; flow variables persist only within the flow in which they were created.

n/a

sessionVars

A session variable set on the message; session variables persist across flows within an application.

n/a

Shortcut for payload

Mule accepts the expression #[payload] as a shortcut for #[message.payload]. This shortcut only applies with the payload field.

Basic Syntax Rules

For a full list of syntax rules, see full MEL reference material.

Example Description

	Example	Description
#[ ]	`#[message.id]`	Always bounds an expression.
Simple expressions	`#[message.field] #[sessionVars.age]`	The simplest type of expression, these consist of just a context object and a field, or simply a variable. Provides access to information from the message including payload, properties, and variables.
Multiline expressions	`#[calendar = Calendar.getInstance(); message.payload = new org.mule.el.datetime.DateTime(calendar);]`	You can include several lines in a single expression, each must end with a ;
Operators	`#['Cookie' + flowVars.cookie]`	Performs operations in expressions. Can be unary, comparison, logical, bitwise, arithmetic, and more.
Boolean expressions	`#['foo'=='bar'] #[2 + 2 == 4]`	Produces Boolean values.
Bean Property Access	`#[payload.property1.property2]`	Access information from bean.
Method invocations	`#[message.header.get()]`	Calls a method, then performs it on an object according to the parameter (if any) specified within the parentheses. Method calls always follow the syntax: `object.method()`
Assignments	`#[payload = 'sample']`	Evaluates to assign a value. The example at left resolves dynamically to set the payload to `sample`.
Literals	`'expression' 255 null`	Strings, numbers, Boolean values, types, and nulls.
xpath and regex	`xpath3('/orders/order[0]') regex('^(To\|From\|Cc):')`	xpath3 and regex provide ways of extracting context information that doesn’t already exist as a single value.
Wildcards	`wildcard("Hello*")`	Matches a value (the message payload, by default) against a wildcard pattern, these use the meta-characters '?' to represent any single character and '*' for a repetition of any character. It’s case sensitive by default.

#[ ]

#[message.id]

Always bounds an expression.

Simple expressions

#[message.field] #[sessionVars.age]

The simplest type of expression, these consist of just a context object and a field, or simply a variable. Provides access to information from the message including payload, properties, and variables.

Multiline expressions

#[calendar = Calendar.getInstance(); message.payload = new org.mule.el.datetime.DateTime(calendar);]

You can include several lines in a single expression, each must end with a ;

Operators

#['Cookie' + flowVars.cookie]

Performs operations in expressions. Can be unary, comparison, logical, bitwise, arithmetic, and more.

Boolean expressions

#['foo'=='bar'] #[2 + 2 == 4]

Produces Boolean values.

Bean Property Access

#[payload.property1.property2]

Access information from bean.

Method invocations

#[message.header.get()]

Calls a method, then performs it on an object according to the parameter (if any) specified within the parentheses. Method calls always follow the syntax: object.method()

Assignments

#[payload = 'sample']

Evaluates to assign a value. The example at left resolves dynamically to set the payload to sample.

Literals

'expression' 255 null

Strings, numbers, Boolean values, types, and nulls.

xpath and regex

xpath3('/orders/order[0]') regex('^(To|From|Cc):')

xpath3 and regex provide ways of extracting context information that doesn’t already exist as a single value.

Wildcards

wildcard("Hello*")

Matches a value (the message payload, by default) against a wildcard pattern, these use the meta-characters '?' to represent any single character and '*' for a repetition of any character. It’s case sensitive by default.

Further, you can use expressions inline to create lists, maps and arrays. Learn more about accessing maps, lists and arrays from within a MEL expression.

Inline list

[item1, item2, . . .]

Evaluates to produce a list.

Inline map

[key1 : value1, key2: value2, …]

Evaluates to produce a map.

Inline array

{item1, item2, . . .}

Evaluates to produce an array.

Examples

There is really no such thing as a single typical MEL expression. That said, a few example expressions can help illustrate how MEL expressions resolve. As the following table of examples demonstrates, the values that MEL expressions return can be numerical values, logical values (true or false), strings, or virtually any data type. MEL expressions can also perform operations, invoke methods, and execute functions. Explore all the possibilities by consulting the complete syntax reference. Access full examples that illustrate how to use MEL expressions in applications.

Expression Description

Expression	Description
`#[2 + 2]`	This expression evaluates to 4.
`#[2 + 2 == 4]`	This expression uses an operator to perform a comparison. It evaluates to true.
`#[message]`	This expression references a context object in MEL (`message`, `app`, `mule`, and `server`). The value of this expression is the message.
`#[message.id]`	This expression accesses the ID field of the message context object. The value of this expression is the unique message id that Mule automatically assigns to the message.
`#[payload.firstname]`	This expression accesses an object within the field (payload) associated with the context object (message). If the object is a map item whose key is 'firstname' then this expression evaluates to the value associated with the key 'firstname'. If the object is a bean, the property is returned.
`#[payload[4]]`	Same as above, but in this case – provided the field is a list – the expression returns the value of the 5th item in the list. (4 refers to the 5th item because the first item in the list is the 0 item.)
`#[message.header.get()]`	This expression calls the `get()` method and performs it on the object, according to the parameter (if any) specified within the parentheses.

#[2 + 2]

This expression evaluates to 4.

#[2 + 2 == 4]

This expression uses an operator to perform a comparison. It evaluates to true.

#[message]

This expression references a context object in MEL (message, app, mule, and server). The value of this expression is the message.

#[message.id]

This expression accesses the ID field of the message context object. The value of this expression is the unique message id that Mule automatically assigns to the message.

#[payload.firstname]

This expression accesses an object within the field (payload) associated with the context object (message). If the object is a map item whose key is 'firstname' then this expression evaluates to the value associated with the key 'firstname'. If the object is a bean, the property is returned.

#[payload[4]]

Same as above, but in this case – provided the field is a list – the expression returns the value of the 5th item in the list. (4 refers to the 5th item because the first item in the list is the 0 item.)

#[message.header.get()]

This expression calls the get() method and performs it on the object, according to the parameter (if any) specified within the parentheses.

MEL Auto-Complete

If you are configuring a field that supports expressions and need help with syntax, you can access MEL suggestions by one of two methods.

Place your cursor inside the brackets in a field that has #[ ] pre-populated for you, then press Ctrl + Space Bar.

Enter #[ to open a new MEL expression and display suggestions, as shown below.

Note that the autocomplete functionality described here works in the Visual Editor only. Although Studio’s XML tab does offer some autocomplete options, the suggestions there are limited by Eclipse and are not based on DataSense or Mule Expression Language.

Date and Time Functions

For the complete reference on date and time functions, see Mule Expression Language Date and Time Functions.

Return the system date and time in a dateTime object:
```
#[server.dateTime]
```
Return current system time in nanoseconds as an integer:
```
#[server.nanoTime()]
```

Return a dateTime object with the specified calendar and server locale:

#[calendar = Calendar.getInstance();
message.payload = new org.mule.el.datetime.DateTime(calendar);]

Set the message payload to a Java calendar representation of the server date and time:
```
#[message.payload = server.dateTime.toCalendar()]
```

Tips

MEL performs type coercion at runtime.
When writing in Studio’s XML editor, you cannot use double quotes to express String literals, because MEL expressions already appear enclosed in double quotes in configuration files. Instead, you can either:

enclose in single quotes

'expression'

enclose in escaped double quotes using "

"expression"

enclose in escaped double quotes using \u0027

\u0027expression\u0027

If you’re writing on Studio’s visual editor, Studio transforms double quotes into escaped quotes (i.e., ") in the XML view.
While Mule Expression Language was introduced in Mule 3.3, Mule has supported expressions since Mule 2.1. Prior to Mule 3.3, expression evaluators provided this functionality. An evaluator is a piece of code that follows a set of rules and logic to extract the value of expressions. Each expression evaluator has its own rules and syntax. Mule expression evaluators continue to be fully supported within Mule, but given the availability of Mule Expression Language, their use is no longer recommended.