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. |
Overview
A Transformer prepares a message to be processed through a Mule flow by enhancing or altering the message header or message payload. For example, if the message source that triggers your flow receives data in XML format, but a downstream message processor requires JSON-formatted data, one or more transformers positioned between the message source and the message processor can achieve the necessary translation. (Since no XML-to-JSON transformer exists, this particular example calls for a XML-to-Object transformer chained to an Object-to-JSON transformer.)
Mule Studio provides a set of standard transformers to handle the most common data transformation scenarios. Typically, these pre-packaged processors require minimal configuration. However, if your particular use case requires special settings, you can open the Properties pane for the particular transformer have selected, then modify the default configuration using the drop-down lists or text-entry fields.
| The DataMapper transformer has been deprecated. Use DataWeave instead. |
Chaining Transformers
You can sequence transformers so that the output from the first becomes the input for the next. For example, if you need to implement an A-to-D transformation, but no such pre-packaged transformer exists, you may be able to find all the pre-packaged transformers necessary to implement the chain A-to-B, B-to-C, and C-to-D, which effectively and efficiently simulates the unavailable A-to-D transformer.
Custom Transformers
Studio provides a Custom Transformer, which you can configure if no pre-packaged transformer or sequence of transformers meets your needs. This option requires you to code a Java class that performs the exact transformation you require. You then set up the Custom Transformer to reference this custom class.
Common Transformer Configuration Fields
Most transformers share a set of common configuration fields, although these fields may be distributed in different ways across the General, Advanced, and Documentation tabs of the Properties pane. The following table describes each of these common fields:
| Field | Description |
|---|---|
Display Name |
Defaults to the generic transformer name. Change the display name, which must be alpha-numeric, to reflect the transformer’s specific role, that is, "Appends time stamp ID" |
Return Class |
Specify the Java class that generates the transformer output. This value is referenced when selecting transformers automatically or checking that the transformer has returned the proper type of output. |
Ignore Bad Input |
Check this box to specify whether a transformer should pass a message it has not been able to process on to the next transformer in the transformer chain. If the box is left unchecked, the transformer retains the result generated up to that point without passing anything to the next transformer in the chain. |
Encoding |
Specify from the drop-down list the type of string encoding (such as |
Mime |
Specify from the drop-down list the MIME type used for output, such as |
Description |
Enter a detailed description of this transformer for display in a yellow help balloon that pops up when you hover your mouse over the endpoint icon. |
Transformers Available in Studio
The transformers provided on the Studio Palette fall into four broad categories, as detailed by the tables below:
Script Transformers
This type of transformer integrates a script to perform the transformation. One transformer is provided for each of the four supported scripting languages, and a fifth, generic transformer can implement a script written in any of the four languages.
| Icon | Transformer | Description |
|---|---|---|
|
Groovy |
Implements a Groovy script transformer backed by a Groovy script engine. All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page. |
|
JavaScript |
Implements a JavaScript transformer backed by a JavaScript script engine. See Script Transformer Reference. |
|
Python |
Implements a script transformer backed by a Python script engine. See Script Transformer Reference. |
|
Ruby |
Implements a script transformer backed by a Ruby script engine. See Script Transformer Reference |
|
Script |
Implements a script transformer backed by a JSR-223- compliant script engine, such as a Groovy, Javascript, Python, or Ruby. See Script Transformer Reference. |
Java Object Transformers
Each transformer in this group changes a Java object into another Java object, a Java object into some other data type (such as an HTTP request), or some non-Java data type (such as an HTTP response) into a Java object.
| Icon | Transformer | Description |
|---|---|---|
|
Byte Array to Object |
Converts a byte array to an object, either by de-serializing the array or converting it to a string). Documentation: Common Transformer Configuration Fields |
|
Byte Array to Serializable |
Deserializes a byte array, thus converting it into an object. Documentation: Common Transformer Configuration Fields |
|
Byte Array to String |
Converts a byte array to a string. Documentation: Common Transformer Configuration Fields |
|
Byte Array to MIME |
Changes the MIME type for a byte array. Documentation: Common Transformer Configuration Fields |
|
File to Byte Array |
Reads the contents of a java.io.File into a Byte array. Documentation: Common Transformer Configuration Fields |
|
File to String |
Reads the contents of a Documentation: Common Transformer Configuration Fields |
|
Java |
Transforms the data from one format to another. Documentation: Java Transformer Reference |
|
JmsMessage to Object (Enterprise Edition) |
Converts a JMS message into an object by extracting the message payload. Documentation: Common Transformer Configuration Fields |
|
JSON to Object |
Converts a Json-encoded object graph into a Java Object. Documentation: Common Transformer Configuration Fields |
|
Object to Byte Array |
Converts an object to a byte array. Documentation: Common Transformer Configuration Fields |
|
Object to String |
Converts program code types into readable text strings Used for debugging. Documentation: Common Transformer Configuration Fields |
|
Object to XML |
Converts a Java Object into XML code using XStream. Documentation: Object-to-XML Transformer Reference |
|
Serializable to Byte Array |
Converts a Java Object to a byte array by serializing the object. Documentation: Object-to-XML Transformer Reference |
|
String to Byte Array |
Converts a string into a byte array. Documentation: Common Transformer Configuration Fields |
|
XML to Object |
Uses XStream to convert XML into Java Bean graphs. Documentation: DOM/XML Transformers |
|
XML to DOM |
Converts raw bytes into an in memory representation of a DOM document. Documentation: DOM/XML Transformers |
|
DOM to XML |
Converts any type of parsed XML into raw bytes. Documentation: DOM/XML Transformers |
Content Transformers
This group of transformers modifies messages by adding to, deleting from, or converting a message payload (or a message header).
| Icon | Transformer | Description |
|---|---|---|
|
Append string |
Appends a string to a message payload. Documentation: Append String Transformer Reference |
|
Expression |
Evaluates one or more expressions within the message, then transforms the message according to the results of its evaluation. Documentation: Expression Transformer Reference |
|
Transformer Reference |
References a transformer that is defined as a global element. Documentation: Transformer Reference |
|
XSLT |
Transforms XML using XSLT. Documentation: XSLT Transformer Reference |
SAP Transformers
These transformers change SAP objects (JCo functions or IDoc documents) into their XML representations, or an XML representation into the corresponding SAP object.
| Icon | Transformer | Description |
|---|---|---|
|
SAP-Object-to-XML (Enterprise Edition) |
Transforms a SAP object representing a JCo function or IDoc document into its XML representation. Documentation: SAP Connector. |
|
XML to Function (BAPI) (Enterprise Edition) |
Reads the XML representing a JCo function from Documentation: SAP Connector. |
|
XML to IDOC (Enterprise Edition) |
Reads the XML representing an IDOC document from Documentation: SAP Connector |
Message and Variable Transformers
The four transformers in this group make special information available for specified periods as each message makes its way through a Mule application. In each case, these transformers do not modify the message directly; rather, each activates information that Mule uses to augment or modify the message. Some of these activated resources adhere to messages; others apply to the flow(s) through which a message travels. In any case, they offer a powerful means to enhance and refine Mule message processing output.
| Collectively, these four Message and Variable Transformers replace the single Message Properties Transformer, which has been deprecated. |
Note: The common characteristics of the Message and Variable Transformers:
-
Unlike most other transformers, these four transformers cannot be embedded within endpoints
-
No Global Element (that is, configuration template) exists for any of these transformers, so you must configure each instance separately
-
None of these transformers can be referenced by other Mule processors, so, in effect, you cannot use a single instance multiple times within the same flow
The following table describes the individual Message and Variable transformers:
| Icon | Transformer | Description |
|---|---|---|
|
Attachment |
In contrast to the Message Enricher Scope or the Append String Transformer, the Attachment Transformer does not add to the string that typically composes the main data payload. Instead, this transformer specifies an attachment to append to each message being processed through the flow. If the name or the value of the attachment is defined through an expression, the exact identity (and content) of the attachment can be calculated at run-time, with the possibility that each message receives a different payload. Typically, this attachment is treated as a separate, secondary part of the outbound payload. Documentation: Attachment Transformer Reference |
|
Property |
This transformer allows you to specify a property, which is typically applied to the message header. The "life span" of such a property extends from the moment it is created until the message is passed to an outbound endpoint. Documentation: Property Transformer Reference |
|
Variable |
This transformer facilitates dynamic, run-time determination of the specified variable’s value based on the content of the current message or the current state of the Mule environment. Mule can then use this value to alter the payload content or the processing steps ultimately assigned to the current message. This type of variable remains active as long as the message remains within the flow in which the variable was invoked. As soon as the message gets passed to a different flow via a transport, the variable becomes inactive. Documentation: Variable Transformer Reference |
|
Session Variable |
This transformer resembles the Variable transformer, except the Session Variable set by this transformer persists as long as the associated message remains within the Mule application, even though the message may be processed through multiple flows. Documentation: Session Variable Transformer Reference |
Custom Transformers
For detailed information on configuring standard and custom Transformers with an XML editor, see Using Transformers.
Deprecated HTTP Related Transformers
The transformers below are all related to the deprecated endpoint-based HTTP Connector. They have all been made unnecessary, as the new HTTP Connector's features cover the use cases these were built to serve.
| The transformers no longer have icons in Anypoint Studio 6 and newer. The use of XML is supported, but these transformers cannot be searched for and the icons do not appear in the transformer group in Studio 6 and newer. |
| Transformer | Description |
|---|---|
Object to HTTP Request |
Creates a valid HTTP request from the current message and includes any HTTP headers set on the current message. Documentation: Common Transformer Configuration Fields |
HTTP Response to Object |
Converts an HTTP response (that is, a string, stream, or byte array payload) into a Mule message. Documentation: Common Transformer Configuration Fields |
HTTP Response to String |
Converts an HTPP response into a string and preserves the message header. Documentation: Common Transformer Configuration Fields |
Message to HTTP Response |
Creates a valid HTTP response using the current message and its HTTP headers. Documentation: Common Transformer Configuration Fields |
Body to Parameter Map |
Converts the body of an HTTP request into a Map object. Documentation: Common Transformer Configuration Fields |