Variable Transformer Reference

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version.

Use a variable transformer to set or remove a variable on the message. The scope of this variable is limited to the flow where it is set; when the message leaves the flow, the variable does not carry over to the next flow or application. (By contrast, variables specified through the session variable transformer persist as long as the message continues to be processed within your Mule application, regardless of flow.) To learn more about message scopes, refer to Mule Concepts.

Complete Code Example

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

	Variable Transformer	Session Variable Transformer	Property Transformer
Use	Use to set or remove a variable on the message, tied to the current flow.	Use to set or remove a variable that is tied to the current message for its entire lifecycle, across multiple flows, applications, and even servers.	Use to set, remove, or copy properties on the outbound scope of a message.
Persistence	Variables set with a variable transformer persist only for the current flow and cannot cross the transport barrier.	Session variables set with a session variable transformer persist for the entire message lifecycle, regardless of transport barriers.	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).

Variable Transformer

Session Variable Transformer

Property Transformer

Use

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

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

Use to set, remove, or copy properties on the outbound scope of a message.

Persistence

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

Session variables set with a session variable transformer persist for the entire message lifecycle, regardless of transport barriers.

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 variable, you can invoke it using the flowVars map in a Mule expression. For example, if you have set a variable with the name “FVname” and the value “FVvalue”, you can later invoke that variable using the expression #[flowVars['FVname']], which evaluates to FVvalue.

Configuration

STUDIO Visual Editor

Field Value Description XML

Field	Value	Description	XML
Display Name	Variable	Customize to display a unique name for the transformer in your application.	`doc:name="Variable`
Operation	Set Variable	Select to set a new variable on your message (as shown in example screenshot above).	`<set-variable>`
Remove Variable	Select to delete an existing variable from your message.	`<remove-variable>`
Name	String or Mule Expression	Specify the name for the variable that you are creating or identify the name of the variable that you are removing. If you are removing variables, this field accepts a wildcard "*" character.	`variableName="MyNewVariableName"`
Value	String or Mule Expression	This field displays only if you are setting a new variable. Specify the value using either a string or a Mule expression.	`value="MyNewVariableValue"`

Display Name

Variable

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

doc:name="Variable

Operation

Set Variable

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

<set-variable>

Remove Variable

Select to delete an existing variable from your message.

<remove-variable>

Name

String or Mule Expression

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

variableName="MyNewVariableName"

Value

String or Mule Expression

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

value="MyNewVariableValue"

XML Editor or Standalone

#Set Variable

<set-variable variableName="MyNewVariableName" value="MyNewVariableValue" doc:name="Variable"/>


#Remove Variable

<remove-variable variableName="NameofVariabletoRemove" doc:name="Variable"/>

Element	Description
set-variable	Set a new variable on your message (as shown in example above).
remove-variable	Delete an existing variable from your message.

Element

Description

set-variable

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

remove-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 variable that you are setting or removing. Can be a string or a Mule expression. Note: If you are using the remove-variable element, you may use a wildcard "" character. For example, a remove-variable transformer with a variable name "http." removes all variables with a name that begins with "http." from the message.
value	The value of the variable that you are setting. This attribute is only relevant for the set-variable element. Can be a string or a Mule expression.

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 variable that you are setting or removing. Can be a string or a Mule expression.

Note: If you are using the remove-variable element, you may use a wildcard "" character. For example, a remove-variable transformer with a variable name "http." removes all variables with a name that begins with "http." from the message.

value

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

Example

In many cases, it is useful to preserve the original payload of a message, before it is processed, for use later in the flow or to use it in an exception strategy. For this purpose, you can store the message’s payload in a variable (named, in the example below, "originalRequest") where you can retrieve it later if needed. In this example, if the HTTP connector or the groovy component fails to process the message, the logger in the flow’s exception strategy logs the failed request by retrieving it from the originalRequest variable.

STUDIO Visual Editor

Place the variable transformer building block after the inbound connector of the flow, before other processing takes place on the message.
Configure the variable transformer according to the screenshot below.
Configure the exception strategy of the flow with a logger that retrieves this variable in the event an exception occurs.

XML Editor or Standalone

<http:listener-config name="listener-config" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
<http:request-config name="request-config" host="localhost" port="8081" doc:name="HTTP Request Configuration"/>
<flow name="VariableTransformingFlow1" >
     <http:listener config-ref="listener-config" path="/" doc:name="HTTP Connector"/>
     <set-variable variableName="originalRequest" value="#[message.payload]" doc:name="Save Request"/>
     <http:request config-ref="request-config" path="/" doc:name="HTTP Connector" method="POST"/>
     <scripting:component doc:name="Groovy">
         <scripting:script engine="Groovy"/>
     </scripting:component>
     <catch-exception-strategy doc:name="Catch Exception Strategy">
         <logger level="INFO" doc:name="Log Request" message="Error processing #[flowVars['originalRequest']]" />
     </catch-exception-strategy>
</flow>

Complete Code Example

<mule xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns:scripting="http://www.mulesoft.org/schema/mule/scripting"
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.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd

http://www.mulesoft.org/schema/mule/scripting http://www.mulesoft.org/schema/mule/scripting/current/mule-scripting.xsd

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:listener-config name="listener-config" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
<http:request-config name="request-config" host="localhost" port="8081" doc:name="HTTP Request Configuration"/>
<flow name="VariableTransformingFlow1" doc:name="VariableTransformingFlow1">
      <http:listener config-ref="listener-config" path="/" doc:name="HTTP Connector"/>
      <set-variable variableName="originalRequest" value="#[message.payload]" doc:name="Save Request"/>
      <http:request config-ref="request-config" path="/" doc:name="HTTP Connector" method="POST"/>
      <scripting:component doc:name="Groovy">
         <scripting:script engine="Groovy"/>
      </scripting:component>
      <remove-variable variableName="NameofVariabletoRemove" doc:name="Variable"/>
      <catch-exception-strategy doc:name="Catch Exception Strategy">
         <logger level="INFO" doc:name="Log Request" message="Error processing #[flowVars['originalRequest']]" />
      </catch-exception-strategy>
</flow>

Variable Transformer Reference

Configuration

STUDIO Visual Editor

XML Editor or Standalone

Example

STUDIO Visual Editor

XML Editor or Standalone

Complete Code Example

See Also