2. Introduction
■ 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.
3. Properties andVariables
■ 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.
4. Properties scope - inbound
■ 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).
5. Properties scope - outbound
■ 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).
6. Variable scope
■ 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.
7. Setting and Using Properties andVariables
■ 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,VariableTransformer, and SessionVariableTransformer.
8.
9. 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.
10. 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: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=""#['Hello, my friend!']"" doc:name="Set Payload"/>
</flow>
</mule>
11. 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.