Mule Message Structure

This document examines the Mule message in the context of a flow rather than a batch job. Please see Batch Processing for more information about how messages in a batch job are broken up and processed as records.

The Mule message is the data that passes through an application via one or more flows. It consists of two main parts:

The message header, which contains metadata about the message.
The message payload, which contains your business-specific data.

A Mule message is, itself, embedded within a Mule message object. Some Mule message objects may contain variables, attachments, and exception payloads. However, as attachments and exception payloads are not frequently used or manipulated, this overview document does not include details about them.

If you’re ever in doubt about the structure of the message in a given step of the flow, you can easily check by using the DataSense Explorer.

Properties and Variables

The metadata contained in the message header consists of properties which provide useful information about the message. Contained within the message object, variables represent data about a message.

Properties and variables share a common format: each individual property or variable has a name and a value. The name is how you refer to the property or variable in Mule, and the value is the information stored within it. Thus, the name is like a key to a door and the value is the material behind the door.

A message’s properties and variables have specific scopes that define and organize how they apply across that message’s lifecycle. Properties send metadata along with a message in order to facilitate processing and avoid errors when the message crosses the transport barrier – either by entering a new flow or by being transmitted to another application.

Properties have two main scopes: inbound and outbound.

Inbound properties are immutable, are automatically generated by the message source and cannot be set or manipulated by the user. They contain metadata specific to the message source that prevents scrambling of data formats or other processing mishaps later in the message’s lifecycle. A message retains its inbound properties only for the duration of the flow; when a message passes out of a flow, its inbound properties do not follow it (see image below).
Outbound properties are mutable; they are set during the course of a flow and can become inbound properties when the message passes from the outbound endpoint of one flow to the inbound endpoint of a different flow via a transport. They contain metadata similar to that of an inbound property, but an outbound property is applied after the message enters the flow. Outbound properties can be set automatically by Mule or a user can set them by manually inserting one or more transformer elements in the flow. Note that if the message is passed to a new flow via a flow-ref rather than a connector, the outbound properties remain outbound properties rather than being converted to inbound properties (see image below).

Variables are user-defined metadata about a message. Variables have three scopes:
Flow variables apply only to the flow in which they exist.
Session variables apply across all flows within the same application.
Record variables apply to only to records processed as part of a batch.

Variables are temporary pieces of information about a message that are meant to be used by the application that is processing it, rather than passed along with the message to its destination. Thus, variables are more likely to be set by humans, whereas properties are more likely to be set and invoked by systems. However, there are no strict rules about how properties and variables should be used.

Setting and Using Properties and Variables

Mule includes three message processors you can use to set, copy or remove outbound properties and variables on a message in a flow. When you include one of these transformers in your flow, Mule adds, copies or removes metadata to the message header or object. (There is a fourth message processor: the Record Variable Transformer can set or remove variables on a record in a batch. This section, however, focuses only on message processors which act upon messages.)

For example, you may want to add a property to a message to set an HTTP transport header on your message. Alternatively, if your flow looks up an account number associated with a user, you may want to add a variable to your message to store the account number as metadata on the message. The table below describes these three message processors: Property Transformer, Variable Transformer, and Session Variable Transformer.

	Property	Variable	Session Variable
Use	Use a Property Transformer to set, remove, or copy properties on the outbound scope of a message.	Use a Variable Transformer to set or remove a flow variable on the message, tied to the current flow.	Use as Session Variable Transformer to set or remove a variable that is tied to the current message for its entire lifecycle, across multiple flows, applications, and even servers.
Persistence	Once a message hits an outbound-endpoint, all properties in the outbound scope are sent with the message, in the form of transport-specific metadata (HTTP headers for an HTTP outbound-endpoint, for example).	Variables set with a variable transformer persist only for the current flow and cannot cross the transport barrier.	Session variables set with a session variable transformer persist for the entire message lifecycle, regardless of transport barriers. Note that session variables persist across transport barriers when used with transports which support sessions.

Property

Variable

Session Variable

Use

Use a Property Transformer to set, remove, or copy properties on the outbound scope of a message.

Use a Variable Transformer to set or remove a flow variable on the message, tied to the current flow.

Use as Session Variable Transformer to set or remove a variable that is tied to the current message for its entire lifecycle, across multiple flows, applications, and even servers.

Persistence

Once a message hits an outbound-endpoint, all properties in the outbound scope are sent with the message, in the form of transport-specific metadata (HTTP headers for an HTTP outbound-endpoint, for example).

Variables set with a variable transformer persist only for the current flow and cannot cross the transport barrier.

Session variables set with a session variable transformer persist for the entire message lifecycle, regardless of transport barriers.

Note that session variables persist across transport barriers when used with transports which support sessions.

As an example, the following flow sets an outbound property – a timestamp – on a message.

Studio Visual Editor

Value is set to the #[server.dateTime] expression:

XML Editor or Standalone

<?xml version="1.0" encoding="UTF-8"?>
<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_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
    <flow name="setting_propertiesFlow1" doc:name="setting_propertiesFlow1">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
        <set-property propertyName="timeStamp" value="#[server.dateTime]" doc:name="Set Property"/>
    </flow>
</mule>

To access the property or variable that you have set on a message earlier in a flow, or in a different flow in the application, use a MEL expression.

Type Description

Type	Description
Outbound Property	Sets, removes, or copies a Property transformer. MEL Example: `#[message.outboundProperties]`
Inbound Property	Specifies inbound properties. MEL Example: `#[message.inboundProperties]`
Session Variable	Sets or removes a Session Variable Transformer. MEL Example: `#[sessionVars]`
Variable	Sets or removes a Variable Transformer, or copies a Variable. MEL Example: `#[flowVars]`

Outbound Property

Sets, removes, or copies a Property transformer.

MEL Example: #[message.outboundProperties]

Inbound Property

Specifies inbound properties.

MEL Example: #[message.inboundProperties]

Session Variable

Sets or removes a Session Variable Transformer.

MEL Example: #[sessionVars]

Variable

Sets or removes a Variable Transformer, or copies a Variable.

MEL Example: #[flowVars]

For example, if you want to route messages according to the timeStamp property you added to the header earlier in processing, you can use an expression in a choice router to access the outbound property using message.outboundProperties and route accordingly. Refer to the example below, where the following expression accesses the timeStamp property and evaluates to the value of the property (that is, the time stamped on the message)

MEL Expression:

#[message.outboundProperties.timeStamp]

Example:

<choice doc:name="Choice">
    <when expression="#[message.outboundProperties.timeStamp]">
        <logger level="INFO" doc:name="Logger"/>
    </when>
    <otherwise>
    ...
    </otherwise>
</choice>

Similarly, once you have set a session variable, you can access it using the sessionVars map in a Mule expression. For example, if you have set a session variable with the name “SVname” and the value “SVvalue”, you can later invoke that session variable using the expression #[sessionVars['SVname']], which evaluates to SVvalue. To access a variable, use flowVars in place of sessionVars in the preceding expression.

Message Payload

The message payload is the most important part of the Mule message because it contains the data your Mule application processes. You may apply metadata in the message header or message object to communicate information about your message or secure it from being tampered with, but the core of the message – the data you are transporting – is the reason the message exists in the first place.

The payload doesn’t necessarily stay the same as it travels through a flow. Various message processors in a Mule flow can affect the payload along the way by setting it, enriching, or transforming it into a new format. You can also extract information from a payload within a flow using a MEL expression.

Setting a Message Payload

Use a Set Payload message processor to completely replace the content of the message’s payload. Enter a literal string or a Mule expression that defines the new payload that Mule should set. The following example replaces the payload with a string that reads "Hello, my friend!".

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" 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/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">

    <http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
    <flow name="setting_propertiesFlow3" doc:name="setting_propertiesFlow3">
         <http:listener config-ref="HTTP_Listener_Configuration" path="replace" doc:name="HTTP"/>
        <set-payload value="&quot;#['Hello, my friend!']&quot;" doc:name="Set Payload"/>
    </flow>

</mule>

Enriching a Message Payload

In some cases, you may wish to call an external resource and use the response to enrich the message payload, rather than replace it. To do so, you can use a Message Enricher scope (or wrapper) to encapsulate one or more message processors which perform the task of fetching the information. Once obtained, Mule adds to, or enriches, the message payload with the result of the call to the resource.

Viewing the Mule Message

In Studio, you can visualize the structure of a Mule Message at any given point of the flow. All you have to do is select an element in the flow and click the DataSense icon.

This opens the DataSense explorer, and displays both the structure of the message that enters the element, and the structure of the message that leaves it. This is useful to know the names of variables and properties that are available at that point, as well as the payload’s internal structure.

When the Mule Message relies on inbound requests, information about the initial message structure won’t be known by Studio and so won’t be displayed in the DataSense explorer. If you know what the structure needs to be like, you can input this information into the Metadata tab of the inbound connector. Thanks to that, the DataSense explorer infers the message structure for any of the elements that follow that input.

For more information, see using the DataSense Explorer

Mule Message Structure

Properties and Variables

Setting and Using Properties and Variables

Studio Visual Editor

XML Editor or Standalone

Message Payload

Setting a Message Payload

Enriching a Message Payload

Viewing the Mule Message

See Also