Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.8)
  3. Reference
  4. Transformers

  5. Session Variable Transformer Reference

Session Variable Transformer Reference

Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version.

Use a session variable to set or remove a variable that is tied to a message for its entire lifecycle, potentially across multiple flows, applications, and even servers. Session variables can be easily propagated from one flow to another through the VM transport, or a flow reference, but not through the HTTP Connector. By contrast, variables specified through the variable transformer persist only as long as the message with which they are associated remains within the same flow. To learn more about message scopes, refer to Mule Concepts.

session variable transformer reference 7b052

Use a session variable transformer to set or remove a variable that is tied to a message for its entire lifecycle, potentially across multiple flows, applications, and even servers. Session variables can be easily propagated from one flow to another through the VM transport, or a flow reference, but not through the HTTP Connector. By contrast, variables specified through the variable transformer persist only as long as the message with which they are associated remains within the same flow. To learn more about message scopes, refer to Mule Concepts.

Complete Code Example

The session variable transformer differs from the variable transformer and the property transformer. See the table below for a comparison of these three transformers.

Session Variable Transformer Variable Transformer Property Transformer

Use: Set or remove a variable that is tied to the current message for its entire lifecycle, across multiple flows, applications, and even servers.

Use: Set or remove a variable on the message, tied to the current flow.

Use: Set, remove, or copy properties on the outbound scope of a message.

Persistence: Session variables set with a session variable transformer persist for the entire message lifecycle, regardless of transport barriers, except for the HTTP Connector which doesn’t propagate them.

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

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

Once you have set a session variable, you can invoke 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.

Note that the session variable is linked to a Mule Message, but not to a MuleEvent. This means that if you make use of an element that makes copies of the message – such as an async scope or a scatter gather component – changes in flow variables won’t be persisted in between these replicated messages, even though they started as one.

Configuration

Studio Visual Editor

session_transformer
Field Value Description

Display Name

Session Variable

Customize to display a unique name for the transformer in your application.

XML: doc:name="Session Variable"

Operation

Set Session Variable

Select to set a new session variable on your message (as shown in example screenshot above).

XML: <set-session-variable>

Remove Session Variable

Select to delete an existing session variable from your message.

XML: <remove-session-variable>

Name

String or Mule Expression

Specify the name for the session variable that you are creating, or identify the name of the session variable that you are removing. If you are removing session variables, this field accepts a wildcard "*" character.

XML: variableName="MyNewSessionVariableName"

Value

String or Mule Expression

Mule displays this field only if you are setting a new session variable. Specify the value using either a string or a Mule expression.

XML: value="MyNewSessionVariableValue"

MIME Encoding

Drop-down menu

(Optional) Set MIME encoding language.

XML: encoding="value"

MIME Type

Drop-down menu

(Optional) Set MIME type.

XML: mimeType="value"

XML Editor or Standalone

# Set session variable

<set-session-variable variableName="MyNewSessionVariableName" value="MyNewSessionVariableValue" doc:name="Session Variable"/>

# Remove session variable
<remove-session-variable variableName="NameofSessionVariabletoRemove" doc:name="Session Variable"/>
Element Description

set-session-variable

Set a new variable on your message (as shown in example above).

remove-session-variable

Delete an existing variable from your message.
Element Attribute Description

doc:name

Customize to display a unique name for the transformer in your application.

Note: Attribute not required in Mule Standalone configuration.

variableName

The name of the session variable that you are setting or removing. Can be a string or a Mule expression.

Note: If you are using the remove-session-variable element, you may use a wildcard "" character. For example, a remove-session-variable transformer with the element variableName="http." removes all variables whose names begin with "http." from the message.

value

The value of the session variable that you are setting. This attribute is only relevant for the set-session-variable element. Can be a string or a Mule expression.

Example

In many cases, messages travel across multiple flows, applications and even servers. In such cases, it can be useful to attach some kind of metadata to a message so as to track it from its origin to its final destination across all systems. In the example below, we set a session variable named messageID. This messageID contains a unique identifier that persists on the message over its entire lifecycle (unless it is explicitly removed by another session variable transformer).

Studio Visual Editor

The following example shows use of Mule Expression Language to set a value to the messageID variable. The MEL statement is:

#[java.util.UUID.randomUUID().toString()]
session_trans_example

XML Editor or Standalone

<http:listener-config name="HTTP_Listener_Configuration"
host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
<flow name="SessionVariableTransformingFlow">
    <http:listener config-ref="HTTP_Listener_Configuration"
    path="/" doc:name="HTTP"/>
    <set-session-variable variableName="messageID"
    value="#[java.util.UUID.randomUUID().toString()]"
    doc:name="Session Variable"/>
    <logger message="Variable set with #[sessionVars.messageID]"
    level="INFO" doc:name="Logger"/>
    <remove-session-variable variableName="NameofSessionVariabletoRemove"
    doc:name="Session Variable"/>
</flow>

Complete Code Example

The following example sets and removes a session variable.

Flow:

session variable flow 
<?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="SessionVariableTransformingFlow">
        <http:listener config-ref="HTTP_Listener_Configuration"
        path="/" doc:name="HTTP"/>
        <set-session-variable variableName="messageID"
        value="#[java.util.UUID.randomUUID().toString()]"
        doc:name="Session Variable"/>
        <logger message="Variable set with #[sessionVars.messageID]"
        level="INFO" doc:name="Logger"/>
        <remove-session-variable variableName="NameofSessionVariabletoRemove"
        doc:name="Session Variable"/>
    </flow>
</mule>

See Also

  • Refer to Mule Concepts to learn more about message scopes.

  • Read about related transformers, the variable transformer and the properties transformer, which you can use to set properties and variables for different scopes.

  • Learn how to use Mule Expression Language to read session variables using the sessionVars map.