Property 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 property transformer to set, remove, or copy properties on the outbound scope of a message. This transformer transforms only outbound properties. Note that you cannot manipulate inbound scope properties, as those are automatically generated by the message source. To learn more about message scopes, refer to Mule Concepts.

Complete Code Example

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

	Property Transformer	Variable Transformer	Session Variable Transformer
Use	Use to set, remove, or copy properties on the outbound scope of a message.	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.
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).	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.

Property Transformer

Variable Transformer

Session Variable Transformer

Use

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

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.

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

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.

To access the property that you have set on a message earlier in a flow, or in a different flow in the application, use a MEL expression. For example, if you want to route messages according to the timeStamp property you added to the header earlier in processing, you can use an expression in a choice router to access the outboundProperties property and route accordingly. Refer to the example below, where the expression #[message.outboundProperties=timeStamp] accesses the timeStamp property and evaluates to the value of the property.

<choice doc:name="Choice">
    <when expression="#[message.outboundProperties['timeStamp']]">
        <logger level="INFO" doc:name="Logger"/>
    </when>
    <otherwise>
    ...
    </otherwise>
</choice>

Configuration

STUDIO Visual Editor

Field Value Description XML

Field	Value	Description	XML
Display Name	Property	Customize to display a unique name for the transformer in your application.	doc:name="Property"`
Operation	Set Property	Select to set a new property on the outbound scope of your message (as shown in example above).	`<set-property>`
Remove Property	Select to delete an existing property from your message to remove it from the outbound scope.	`<remove-property>`
Copy Properties	Select to copy an existing property from the inbound scope onto the outbound scope of your message.	`<copy-properties> `
Name	String or Mule Expression	Specify the name for the property that you are creating, or identify the name of the property that you are copying or removing. If you are copying or removing properties, this field accepts a wildcard "*" character.	`propertyName="MyNewPropertyName"`
Value	String or Mule Expression	This field displays only if you are setting a new property. Specify the value using either a string or a Mule expression, as shown in the example screenshot above.	`value="MyNewPropertyValue"`

Display Name

Property

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

doc:name="Property"`

Operation

Set Property

Select to set a new property on the outbound scope of your message (as shown in example above).

<set-property>

Remove Property

Select to delete an existing property from your message to remove it from the outbound scope.

<remove-property>

Copy Properties

Select to copy an existing property from the inbound scope onto the outbound scope of your message.

`<copy-properties> `

Name

String or Mule Expression

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

propertyName="MyNewPropertyName"

Value

String or Mule Expression

This field displays only if you are setting a new property. Specify the value using either a string or a Mule expression, as shown in the example screenshot above.

value="MyNewPropertyValue"

XML Editor or Standalone

#Set property

<set-property propertyName="Authorization" doc:name="Set Authentication Header" value="#['Basic ' + org.apache.commons.codec.binary.Base64.encodeBase64String('${user}:${password}'.getBytes())]"/>

# Remove property

<remove-property propertyName="PropertyForRemoval" doc:name="Delete Property"/>


# Copy property

<copy-properties propertyName="http.*" doc:name="Copy All HTTP Headers"/>

Element	Description
set-property	Set a new property on the outbound scope of your message (as shown in example below).
remove-property	Delete an existing property from your message to remove it from the outbound scope.
copy-properties	Copy an existing property from the inbound scope onto the outbound scope of your message

Element

Description

set-property

Set a new property on the outbound scope of your message (as shown in example below).

remove-property

Delete an existing property from your message to remove it from the outbound scope.

copy-properties

Copy an existing property from the inbound scope onto the outbound scope of your message

Element Attribute	Description
doc:name	Customize to display a unique name for the transformer in your application, as shown in the example below. Note: Attribute not required in Mule Standalone configuration.
propertyName	The name of the property that you are setting, copying, or removing. Can be a string or a Mule expression. Note: If you are using the remove-property or copy-properties element, you may use a wildcard "" character. For example, a copy-properties transformer with a property name "http." will copy all properties whose names begin with "http.", from the inbound scope to the outbound scope.
value	The value of the property that you are setting. This attribute is only relevant for the set-property 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, as shown in the example below.

Note: Attribute not required in Mule Standalone configuration.

propertyName

The name of the property that you are setting, copying, or removing. Can be a string or a Mule expression.

Note: If you are using the remove-property or copy-properties element, you may use a wildcard "" character. For example, a copy-properties transformer with a property name "http." will copy all properties whose names begin with "http.", from the inbound scope to the outbound scope.

value

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

Example

In the example below, we want to connect to a web service protected by an HTTP basic authentication mechanism. In order to do that, our HTTP request needs to include a header, Authorization, which contains the username and password that allows the request go through. The properties transformer shown below sets an outbound property named Authorization and applies the value that is required to authenticate the message.

STUDIO Visual Editor

XML Editor or Standalone

<http:listener-config name="listener-config" host="localhost" port="8081"/>
<http:request-config name="request-config" host="localhost"
port="8081"/>
<flow name="PropertyTransformingFlow" doc:name="PropertyTransformingFlow">
    <http:listener config-ref="listener-config" path="/" doc:name="HTTP Connector"/>
    <set-property propertyName="Authorization" doc:name="Set Authentication Header" value="#['Basic ' + org.apache.commons.codec.binary.Base64.encodeBase64String('${user}:${password}'.getBytes())]"/>    <http:request config-ref="request-config" path="/" method="POST" doc:name="HTTP Connector"/>
</flow>

Complete Code Example

View namespace

<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.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.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"/>
<http:request-config name="request-config" host="localhost"
port="8081"/>
<flow name="PropertyTransformingFlow" doc:name="PropertyTransformingFlow">
    <http:listener config-ref="listener-config" path="/" doc:name="HTTP Connector"/>
    <set-property propertyName="Authorization" doc:name="Set Authentication Header" value="#['Basic ' + org.apache.commons.codec.binary.Base64.encodeBase64String('${user}:${password}'.getBytes())]"/>
    <remove-property propertyName="PropertyForRemoval" doc:name="Delete Property"/>
    <copy-properties propertyName="http.*" doc:name="Copy All HTTP Headers"/>
    <http:request config-ref="request-config" path="/" method="POST" doc:name="HTTP Connector"/>
</flow>

Referencing Properties Elsewhere

After you have set a new property, how can you call it and use it elsewhere in your flow?

If you select any component in your flow that precedes the creation of the property, you will see it in the Metadata Explorer, under the Outbound Properties section.
You can reference it in any field in any component that accepts Mule Expression Language (MEL), calling it through the following expression:
```
#[message.outboundProperties.propertyName]
```
In Studio, the autocomplete feature can help you out by displaying a list of available properties at that particular part of the flow.

You can reference it inside any custom Java Class, calling it through the following:

message.getOutboundProperty("propertyName");

See a basic Java Class that implements this

package org.mule.transformers;
import org.mule.api.MuleMessage;
import org.mule.api.transformer.TransformerException;
import org.mule.transformer.AbstractMessageTransformer;

public class setPropertyAsPayload extends AbstractMessageTransformer{
    /**
     * @param args
     */
    public Object transformMessage(MuleMessage message, String outputEncoding) throws TransformerException {

        String newPayload = message.getOutboundProperty("myProperty");
        return newPayload;
    }
}

This Java Class takes an existing property named myProperty and makes it into the message payload.

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

Property Transformer Reference

Configuration

STUDIO Visual Editor

XML Editor or Standalone

Example

STUDIO Visual Editor

XML Editor or Standalone

Complete Code Example

Referencing Properties Elsewhere

See Also