Mule School: The MuleMessage, Property Scopes and Variables

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 and compare to each other, and how to choose the right one for their use cases.

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

We'd love to hear your opinion on this post


15 Responses to “Mule School: The MuleMessage, Property Scopes and Variables”

  1. […] Mule School: The MuleMessage, Property Scopes and Variables […]

  2. i was looking for syntax to read http inbound properties. unfortunately i couldn’t see anything in logger message section. i am using Mule Studio 1.3.1

    • Good morning, Maheboob

      In order to read HTTP inbound properties, you can use the Mule Header Expression evaluator. For example, if you received and HTTP POST request, and wanted to know what HTTP Method was invoked, you should read the “http.method” inbound property. Therefore, your logger message section should contain the following:

      HTTP Method invoked was #[header:INBOUND:http.method]

      Greetings,
      Victor

  3. Thanks Victor. I finally got this working by using expression #[message.inboundProperties[‘http.request’]] which i believe is latest way of doing it. Anyway, point i was trying to make was that those examples dont work in studio 1.3.1, at least.

  4. Hi,
    how can I read and display a session variable in an html page? I want to show the username after login.
    Thanks

  5. Hi!

    When I login in my web, if I refresh the web (F5), I have to login again.. how can I keep the session with Mule? Can I use session variables?

    Thanks!!

  6. Thx, great article. Help me a lot.
    Resolve problem with loosing outbound properties at VM inbound endpoint(aka crossing VM ‘transport boundaries’).

  7. Great Article

  8. Excellent article. Cleared my doubts about mule properties and variables. I have a doubt. How can we define/access variables using expression-component?

  9. Thanks so much for sharing this with us!

  10. Thank you for sharing valuable information. Nice post.

  11. Excellent post !! Helped me a lot.
    How are invocation properties different from Flow variables?

  12. Thanks for giving explanation.

  13. Thank you for the blog post it does clarify a lot about types of variables, but I notice the examples you use to proof that session variables can cross transport barriers is by crossing to flow with VM transport. I created a mule flow with HTTP inbound end point, but I find that the second flow (with the HTTP inbound end point) cant access the session variable of the calling flow. I have posted a question in the following forum to ask for clarification and conformation of my understanding. https://forums.mulesoft.com/questions/58209/how-to-access-session-variable-from-a-second-flow.html

  14. what is the difference between “Session property” vs “Outbound property” ? Both behaves same way as in the next flow.