Reading Time: 10 minutes

Last updated: August 11, 2016

Overview

Mule Properties and Flow Variables are one of the most widely used features in Mule. Nevertheless, Mule newcomers may have a hard time understanding how the different property scopes and variables compare to each other, and how to choose the right one for their use cases.

latest report
Learn why we are the Leaders in API management and iPaaS
Read reports

The idea behind this blog post is to clarify those differences, comparing side by side INBOUND, OUTBOUND, INVOCATION and SESSION property scopes. We will also cover “flow variables” and “session variables”. For more detailed information, you can go to each scope´s section in the User’s Manual.

Quick Recap: Mule Message Anatomy

The MuleMessage is the object used to pass any data through Mule.  It enables universal access to any type of message format an encapsulates properties and attachments associated with the current event being processed. Let’s do a quick review of what a Mule message looks like:

mule message anatomy

A Mule message consists of three parts

  • the header, which contains sets of named properties, partitioned into scopes
  • the payload, which consists of business-specific data
  • optional attachments
You can find more information in this document.

In this article, we will focus on the message properties contained in the message header and how to choose the right scope for them.

The Transport Barrier

One key concept you must bear in mind to understand what follows is something I will call “transport barrier.” It´s just a fancy way of saying we are sending a message across a transport. Calling subflows, for example, does not cross the “transport barrier”. Sending a message across an endpoint does cross the “transport barrier”.

In the following examples, we will use a VM transport as a “barrier”.

Mule Inbound Properties

  • Inbound properties can’t be set by you.
  • Message sources (such as inbound endpoints) set them for you when they receive a message.
  • Inbound properties are lost when crossing a “transport barrier.”

Mule Outbound Properties

  • Outbound properties can be set by you.
  • When crossing a “transport barrier”, outbound properties are automatically turned into inbound properties, and no longer exist as outbound properties.

Mule Invocation Properties

  • Invocation properties can be set by you.
  • Invocation properties are lost when crossing a “transport barrier”.

Mule Session Properties

  • Session Properties can be set by you.
  • Session properties are preserved when crossing a “transport barrier”.

Mule Flow Variables

  • They behave like instance properties.

Mule Session Variables

  • They behave like session properties.

Examples

The following examples are contained in the Mule Scopes Demo App. Feel free to download it and examine its configuration (we suggest using Mule Studio to import the example project).
All examples use a similar structure:
  • An HTTP call is received.
  • Optionally set some properties/variables (with different scopes).
  • Log the message contents to see which properties/variables are present.
  • Cross a VM “transport barrier”
  • Log the message contents on the other side to show the effects on the different scoped properties/variables of crossing the “transport barrier”.

Inbound-Scoped Properties Example

See flows “MuleScopesFlow1” and “MuleScopesFlow2”.
Since inbound properties cannot be set by you, we will just use the ones that have already been set for us by the HTTP Inbound Endpoint. Let’s take “http.method” as an example.
With your app running, open the following URL (or use curl): http://localhost:8081/inbound
  • The first flow log entry will contain http.method as an inbound property.
  • The second flow log entry will not contain http.method, since it was lost crossing the “transport barrier”.
Therefore, this property will be accessible in the areas highlighted below.
Inbound Property Example

Outbound-Scoped Properties Example

See flows “MuleScopesFlow3” and “MuleScopesFlow4”.
We will set an outbound property called “Meal” to “Soylent Green” and see what happens.
With your app running, open the following URL (or use curl): http://localhost:8081/outbound
  • The first flow log entry will contain “Meal” as an outbound property.
  • The second flow log entry will also contain “Meal”, but this time as an inbound property, since it was converted crossing the “transport barrier”.
Therefore, this property will be accessible in the areas highlighted below.
Outbound Property Example

Invocation-Scoped Properties Example

See flows “MuleScopesFlow5” and “MuleScopesFlow6”.
We will set an invocation property called “Organism” to “Plankton” and see what happens.
With your app running, open the following URL (or use curl): http://localhost:8081/invocation
  • The first flow log entry will contain “Organism” as an invocation property.
  • The second flow log entry will not contain “Organism” since it was lost crossing the “transport barrier”.
Therefore, this property will be accessible in the areas highlighted below.
Invocation Property Example

Session-Scoped Properties Example

See flows “MuleScopesFlow7” and “MuleScopesFlow8”.
We will set a session property called “Profession” to “Therapist” and see what happens.
With your app running, open the following URL (or use curl): http://localhost:8081/session
  • The first flow log entry will contain “Profession” as a session property.
  • The second flow log entry will also contain “Profession” as a session property since it was preserved when crossing the “transport barrier”.
Therefore, this property will be accessible in the areas highlighted below.
Session Property Example

Flow and Session Variables Example

See flows “MuleScopesFlow9” and “MuleScopesFlow10”.
Remember, flow and session variables behave just like invocation-scoped and session-scoped properties, respectively. We will set a flow variable called “Years” to “7500000” and a session variable called “Answer” to “42”, and see what happens.
With your app running, open the following URL (or use curl): http://localhost:8081/variables
  • The first flow log entry will contain “Years” as an invocation-scoped property (this is correct since “flow variables” is just a friendlier name for invocation properties).
  • The second flow log entry will not contain “Years” since it was lost when crossing the “transport barrier”.
  • The first flow log entry will contain “Answer” as a session-scoped property (this is correct since “session variables” is just a friendlier name for session properties).
  • The second flow log entry will also contain “Answer” as a session-scoped property (this is correct, since “session variables” is just a friendlier name for session properties) since it was preserved when crossing the “transport barrier”.
Therefore, these variables will be accessible in the areas highlighted in the two diagrams below.
Flow Variables Example
Session Variables Example
I hope this helps you understand how the MuleMessage works as well as aiding you to choose the right scope for your properties and variables.