Session Variable Transformer Reference

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

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

Field Value Description

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"`

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

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

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.

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()]

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:

<?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>

Session Variable Transformer Reference

Configuration

Studio Visual Editor

XML Editor or Standalone

Example

Studio Visual Editor

XML Editor or Standalone

Complete Code Example

See Also