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

  5. Variable Transformer Reference

Flow 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.
variable transformer reference bf224

Use a variable transformer to set or remove a variable on the message. The scope of this "flow variable" is limited to the flow where it is set, and accessed in Mule Expression Language by the identifier flowVars. For example, access an integer myInt using #[flowVars.myInt].

Flow Scope versus Session Scope

When the message leaves the flow, the flow variable, set by the Variable Transformer discussed here, does not carry over to the next flow or application.

By contrast, session variables specified using 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: Set or remove a variable on the message, tied to the current flow.

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

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

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

After you 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.

Configuring the Variable Transformer

Studio Visual Editor

variable_transformer
Field Value Description

Display Name

Variable

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

XML: doc:name="Variable

Operation

Set Variable

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

XML: <set-variable>

Remove Variable

Select to delete an existing variable from your message.

XML: <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.

XML: 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.

XML: value="MyNewVariableValue"

MIME Encoding

Drop-down menu

(Optional) Indicates the MIME encoding language. Only appears when setting a variable.

XML: encoding="language"

MIME Type

Drop-down menu

(Optional) Indicates the MIME type. Only appears when setting a variable.

XML: mimeType="value"

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 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 - Store Variable, Output in Exception Strategy

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 whole or part of 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 (blank on purpose here) fails to process the message, the logger in the flow’s exception strategy logs the failed request by retrieving it from the originalRequest variable.

Create the Example Application

  1. Place the variable transformer processor after the inbound connector of the flow, before other processing takes place on the message.

    variable+transformer+example

  2. Configure the variable transformer, setting the variable to the message’s inboundProperties where the query parameters that may be passed in the request are stored:
    Display Name: Save Request
    Name: originalRequest
    Value: #[message.inboundProperties] OR for the whole payload, #[message.payload], which is the same as #[payload]

    set+variable

  3. Configure the exception strategy of the flow with a logger that retrieves this variable in the event an exception occurs:
    Name: Log Request
    Message: Error processing #[flowVars['originalRequest']]

    Studio_FlowVars_Logger

  4. This is an example of the exception output to the Studio console after hitting configured HTTP endpoint with some query parameters, http://localhost:8084/?name=aaron&age=32:

INFO  2016-09-30 20:03:03,121 [[variable-transformer-test].listener-config.worker.01] org.mule.api.processor.LoggerMessageProcessor: Error processing {connection=keep-alive, http.scheme=http, host=localhost:8084, accept-language=en-US,en;q=0.8,es;q=0.6, accept=text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8, http.method=GET, http.relative.path=/, user-agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 Safari/537.36, http.request.path=/, http.uri.params=ParameterMap{[]}, upgrade-insecure-requests=1, http.query.string=name=aaron&age=32, http.remote.address=/127.0.0.1:56483, http.request.uri=/?name=aaron&age=32, http.version=HTTP/1.1, http.query.params=ParameterMap{[name=[aaron], age=[32]]}, http.listener.path=/, accept-encoding=gzip, deflate, sdch}

Complete Example App Code - Store Variable, Output in Exception Strategy

variable transformer flow 
<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="8084" 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" allowedMethods="GET"/>
      <set-variable variableName="originalRequest" value="#[message.inboundProperties]" doc:name="Save Request"/>
      <http:request config-ref="request-config" path="/" doc:name="HTTP Connector" method="POST">
            <http:request-builder>
                <http:query-param paramName="originalRequest" value="#[message.inboundProperties.'http.query.params'.aaron]"/>
            </http:request-builder>
        </http:request>
      <scripting:component doc:name="Groovy">
         <scripting:script engine="Groovy"><![CDATA[println $(originalRequest)]]></scripting:script>
      </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>
      </mule>

See Also

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

  • Read about related transformers, the session 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 flow variables using the flowVars map.