Contact Us 1-800-596-4880

Using Transformers

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.

Transformers convert message payloads to formats expected by their destinations. Mule provides many standard transformers, which you configure using predefined elements and attributes in your Mule XML configuration file. You can also configure custom transformers using the <custom-transformer> element, in which you specify the fully qualified class name of the custom transformer class. For more information on creating and configuring a custom transformer, see Creating Custom Transformers.

The most powerful tool for transforming a message is the DataWeave Transformer, which can not only change the format of the message, but also rename, aggregate, split or rearrange the fields in it in any way you desire.

Standard transformers are easier to use than custom transformers. You don’t need to know the Java name of the transformer, and all properties are explicitly declared in a Mule configuration schema. Following is an example of declaring the standard Append String transformer, which appends string text to the original message payload:

<append-string-transformer name="myAppender" message=" ... that's good to know!"/>

If the original message payload was the string "foo", the transformer above would convert the string to "foo …​ that’s good to know!".

The Available Transformers section of this page describes all the standard transformers provided with Mule. Additionally, many transports and modules have their own transformers, such as the ObjectToJMSMessage transformer for the JMS transport.

Configuring Transformers

You can configure a transformer locally or globally. You configure a local transformer right on the endpoint or in a flow or where you want to apply it, whereas you configure a global transformer before any <model> or <flow> elements in your Mule configuration file and then reference it.

For example, the following code defines two global transformers, which are referenced from two different places:

<xm:xml-to-object-transformer name="XMLToExceptionBean" returnClass="org.mule.example.errorhandler.ExceptionBean"/>
<custom-transformer name="ExceptionBeanToErrorMessage" class="org.mule.example.errorhandler.ExceptionBeanToErrorMessage"
returnClass="org.mule.example.errorhandler.ErrorMessage"/>

...
<flow name="Error Manager">
  <inbound-endpoint address="file://./test-data/in" transformer-refs="XMLToExceptionBean ExceptionBeanToErrorMessage">
    <file:filename-wildcard-filter pattern="*.xml" />
  </inbound-endpoint>
    ...
</flow>
...
<flow name="Business Error Manager">
  <inbound-endpoint address="jms://exception.queue"/>
  <transformer ref="XMLToExceptionBean"/>
  <transformer ref="ExceptionBeanToErrorMessage"/>
  ...
</flow>

Chaining Transformers

You can chain transformers together so that the output from one transformer becomes the input for the next. To chain transformers, you create a space-separated list of transformers in the transformer-refs or responseTransformer-refs attributes or by creating multiple <transformer> elements as shown above.

For example, this chain ultimately converts from a ByteArray to InputStream:

transformer-refs="ByteArrayToString StringToObject ObjectToInputStream"

You could also configure this as follows:

<transformer ref="ByteArrayToString"/>
<transformer ref="StringToObject"/>
<transformer ref="ObjectToInputStream"/>

Note that if you specify transformer chains, any default transformers or discoverable transformers are not applied. If you want to use those transformers, you must specify them explicitly with the other chained transformers.

Transformation Best Practices

Mule has an efficient transformation mechanism. Transformers are applied to inbound or outbound endpoints, and the data is transformed just before it is sent or received from an endpoint. Transformers can be concatenated, so it is simple to perform multiple transformations on data in transit.

There is no one standard approach for how and where transformations should occur. Some maintain that because transformation should always be applied on inbound/outbound data, transformations should be available as part of the enterprise service bus instead of inside the components. This approach matches the concepts of Aspect Oriented Programming (AOP). Others conclude that it is far more efficient to encode the transformation logic into the components themselves. In the second case, however, there is no distinction between code that is related to a business process and code that is generic enough to be reused, which contradicts the philosophy of an enterprise service bus.

While there is no industry best practice, MuleSoft recommends that developers examine their transformation logic to see if it will always be used (AOP) or if it is specific to a business process. In general, if it’s always used, you should use a transformer, and if it is specific to a single business process, it should be part of the component.

Note the following cases where you should not configure a transformer:

  • Default transformers: some transports have default transformers that are called by default, but only if you don’t configure explicit transformations.

  • Discoverable transformers: some transformers can be discovered and used automatically based on the type of message. You do not configure these transformers explicitly. These include custom transformers that have been defined as discoverable. For more information, see Creating Custom Transformers.

Available Transformers

Following are the transformers available with Mule. Some transformers are specific to a transport or module. For more information, see Transports Reference and Modules Reference. For a complete reference to the elements and attributes for the standard Mule transformers, see Transformers Configuration Reference.

Basic

The basic transformers are in the org.mule.transformer.simple package. They do not require any special configuration. For details on these transformers, see Transformers Configuration Reference.

Transformer Description

BeanBuilderTransformer

(As of Mule 2.2) Constructs simple bean objects by defining the object and then setting a number of expressions used to populate the bean properties. For example:

<bean-builder-transformer name="testTransformer3" beanClass="org.mule.test.fruit.Orange">
  <bean-property property-name="brand" evaluator="mule" expression="message.payload" optional="true"/>
  <bean-property property-name="segments" evaluator="mule" expression="message.header(SEGMENTS)"/>
</bean-builder-transformer>

ByteArrayToHexString < - >
HexStringToByteArray

A pair of transformers that convert between byte arrays and hex strings.

ByteArrayToMuleMessage < - >
MuleMessageToByteArray

A pair of transformers that convert between byte arrays and Mule messages.

ByteArrayToObject < - >
ObjectToByteArray

A pair of transformers that convert between byte arrays and objects. If the byte array is not serialized, ByteArrayToObject returns a String created from the bytes as the returnType on the transformer.

ByteArrayToSerializable < - >
SerializableToByteArray

A pair of transformers that serialize and deserialize objects.

CombineCollectionsTransformer

Takes a payload which is a Collection of Collections and turns into a single List. For example, if the payload is a Collection which contains a Collection with elements A and B and another Collection with elements C and D, this turns them into a single Collection with elements A, B, C, and D.

ExpressionTransformer

Evaluates one or more expressions on the current message and return the results as an Array. For details, see Mule Expression Language MEL.

MessagePropertiesTransformer

A configurable message transformer that allows users to add, overwrite, and delete properties on the current message.

ObjectArrayToString < - >
StringToObjectArray

A pair of transformers that convert between object arrays and strings. Use the configuration elements <byte-array-to-string-transformer> and <string-to-byte-array-transformer>.

ObjectToInputStream

Converts serializable objects to an input stream but treats java.lang.String differently by converting to bytes using the String.getBytes() method.

ObjectToOutputHandler

Converts a byte array into a String.

ObjectToString

Returns human-readable output for various kinds of objects. Useful for debugging.

StringAppendTransformer

Appends a string to an existing string.

StringToObjectArray

Converts a string to an object array. Use the configuration element <string-to-byte-array-transformer>.

XML

The XML transformers are in the org.mule.module.xml.transformer package. They provide the ability to transform between different XML formats, use XSLT, and convert to POJOs from XML. For information, see XML Module Reference.

Transformer Description

XmlToObject < - > ObjectToXml

Converts XML to a Java object and back again using XStream.

JAXB XmlToObject < - > JAXB ObjectToXml

Converts XML to a Java object and back again using the JAXB binding framework (ships with JDK6)

XSLT

Transforms XML payloads using XSLT.

XQuery

Transforms XML payloads using XQuery.

DomToXml < - > XmlToDom

Converts DOM objects to XML and back again.

XmlToXMLStreamReader

Converts XML from a message payload to a StAX XMLStreamReader.

XPath Extractor

Queries and extracts object graphs using XPath expressions using JAXP.

JXPath Extractor

Queries and extracts object graphs using XPath expressions using JXPath.

XmlPrettyPrinter

Allows you to output the XML with controlled formatting, including trimming white space and specifying the indent.

JSON

The JSON transformers are in the org.mule.module.json.transformers package. They provide the ability to work with JSON documents and bind them automatically to Java objects. For information, see Native Support for JSON.

Scripting

The Scripting transformer transforms objects using scripting, such as JavaScript or Groovy scripts. This transformer is in the org.mule.module.scripting.transformer package.

Encryption

The encryption transformers are in the org.mule.transformer.encryption package.

Transformer Description

Encryption < - > Decryption

A pair of transformers that use a configured EncryptionStrategy implementation to encrypt and decrypt data.

Compression

The compression transformers are in the org.mule.transformer.compression package. They do not require any special configuration.

Transformer Description

GZipCompressTransformer < - > GZipUncompressTransformer

A pair of transformers that compress and uncompress data.

Encoding

The encoding transformers are in the org.mule.transformer.codec package. They do not require any special configuration.

Transformer Description

Base64Encoder < - > Base64Decoder

A pair of transformers that convert to and from Base 64 encoding.

XMLEntityEncoder < - > XMLEntityDecoder

A pair of transformers that convert to and from XML entity encoding.

Email

The Email transport provides several transformers for converting from email to string, object to MIME, and more. For details, see Email Transport Reference.

File

The File transport provides transformers for converting from a file to a byte array (byte[]) or a string. For details, see File Transport Reference.

HTTP

The HTTP connector provides several transformers for converting an HTTP response to a Mule message, map or string, and for converting a message to an HTTP request or response. For details, see HTTP Connector.

JDBC

*Enterprise*

The Mule Enterprise version of the JDBC transport provides transformers for moving CSV and XML data from files to databases and back. For details, see JDBC Transport Reference.

JMS

The JMS Transport Reference and Mule WMQ Transport Reference (enterprise only) both provide transformers for converting between JMS messages and several different data types.

Strings and Byte Arrays

The Multicast Transport Reference and TCP Transport Reference both provide transformers that convert between byte arrays and strings.

XMPP

The XMPP transport provides transformers for converting between XMPP packets and strings. For details, see XMPP Transport Reference.

Custom

Mule supports the ability to build Custom Transformer. Build custom transformers to meet specific data conversion needs in your application.

Common Attributes

Following are the attributes that are common to all transformers.

returnClass

This specifies the name of the Java class that the transformer returns.

ignoreBadInput

If set to true, the transformer ignores any data that it does not know how to transform, but any transformers following it in the current chain is called. If set to false, the transformer also ignores any data that it does not know how to transform, but no further transformations takes place.

MIME Type

This MIME type is set on all messages that this transformer produces.

Encoding

This encoding is set on all messages that this transformer produces.