Contact Us 1-800-596-4880

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

Assumptions

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

example_set_payload

XML Editor or Standalone

<sub-flow name="MEL_example" doc:name="MEL_example">
        <set-payload value="#[message.inboundProperties['username']]" doc:name="Set Payload"/>
    </sub-flow>

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.

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 image below, right).

image:contextob-field.png[contextob_field]           image:flowvars2.png[flowVars2]

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
javaVersion
javaVendor
nanoSeconds
osName
osArch
osVersion
systemProperties
timeZone
tmpDir
userName
userHome
userDir

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
standalone
workDir
registry

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

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

As a shortcut, Mule accepts an expression such as [payload], rather than [message.payload] because it knows to automatically evaluate the expression for the message context object. 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

#[ ]

#[message.id]

Always bounds an expression.

Simple expressions

[message.field]
[sessionVars['age']]

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

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

xpath('/orders/order[0]') regex('^(To FromCc):')

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

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

#[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 a particular field associated with the specified context object. The value of this expression is the unique message id.

#[payload['name']]

This expression accesses a particular map item (with the key "name") within the the field (payload) associated with the context object (message). The value of this expression is the value associated with the variable 'name'.

#[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.

    auto_complete
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

  • As a shortcut, Mule accepts an expression such as [payload], rather than [message.payload] because it knows to automatically evaluate the expression for the message context object. This shortcut only applies with the payload field.

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

    • use single quotes ('expression')

    • escape quotes with " ("expression")

    • escape quotes with \u0027 (\u0027expression\u0027)

      If you’re writing on Studio’s visual editor, Studio transforms double quotes into escaped quotes` ("`)in the XML view.

  • While Mule Expression Language is new 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 ESB, but given the availability of Mule Expression Language, their use is no longer recommended.

See Also