Mule Message Structure
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.
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, and 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 transport, 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, and available with Mule Studio (December 2013) with CloudHub Mule Runtime (December 2013).
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 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, Variable, Session Variable.
|Property Transformer||Variable Transformer||Session Variable Transformer|
|Use||Use to set, remove, or copy properties on the outbound scope of a message.||Use to set or remove a variable on the message, tied to the current flow.||Use 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.|
As an example, the following flow sets an outbound property – a timestamp – on a message.
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||Set or Remove||Copy||Access using MEL|
|Outbound Property||Property transformer||Property transformer|
|Session Variable||Session Variable transformer||-|
|Variable||Variable transformer||Variable transformer|
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
(message.outboundProperties) and route accordingly. Refer to the example below, where the expression
#[message.outboundProperties=timeStamp] accesses the timeStamp property and evaluates to the value of the property (i.e. the time stamped on the message).
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.
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!".
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.
- NEXT STEP: Learn about Message State.
- Learn more about the Variable and Session Variable transformers.
- Learn more about the Property Transformer.
- Learn more about setting or enriching the message payload.
- Learn about the Record Variable available with Mule Studio (December 2013) with CloudHub Mule Runtime (December 2013).