Nav

Transformers

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.
Note : To specify an array type, postfix the class name with square brackets '[]', as in 'org.mule.tck.testmodels.fruit.Orange[]'.

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 UTF-8 or US ASCII, etc.) used for output.

Mime

Specify from the drop-down list the MIME type used for output, such as text/plain or application/json.

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 icon

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 icon

JavaScript

Implements a JavaScript transformer backed by a JavaScript script engine. See Script Transformer Reference.

Python icon

Python

Implements a script transformer backed by a Python script engine. See Script Transformer Reference.

Ruby icon

Ruby

Implements a script transformer backed by a Ruby script engine. See Script Transformer Reference

Script icon

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

Byte Array to Object

Converts a byte array to an object, either by de-serializing the array or converting it to a string).

byte-array-to-serializable

Byte Array to Serializable

Deserializes a byte array, thus converting it into an object.

byte-array-to-string

Byte Array to String

Converts a byte array to a string.

byte-array-to-mime

Byte Array to MIME

Changes the MIME type for a byte array.

file-to-byte-array

File to Byte Array

Reads the contents of a java.io.File into a Byte array.

file-to-string

File to String

Reads the contents of a java.io.File into a java.lang.String object.

java-transformer-icon

Java

Transforms the data from one format to another.

jms-message-to-object

JmsMessage to Object (Enterprise Edition)

Converts a JMS message into an object by extracting the message payload.

json-to-object

JSON to Object

Converts a Json-encoded object graph into a Java Object.

object-to-byte-array

Object to Byte Array

Converts an object to a byte array.

object-to-string

Object to String

Converts program code types into readable text strings Used for debugging.

object-to-xml

Object to XML

Converts a Java Object into XML code using XStream.

Serializable to Byte Array

Serializable to Byte Array

Converts a Java Object to a byte array by serializing the object.

string-to-byte-array

String to Byte Array

Converts a string into a byte array.

xml-to-object

XML to Object

Uses XStream to convert XML into Java Bean graphs.

Documentation: DOM/XML Transformers

xml-to-dom

XML to DOM

Converts raw bytes into an in memory representation of a DOM document.

Documentation: DOM/XML Transformers

dom-to-xml

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-icon

Append string

Appends a string to a message payload.

expression-transformer-icon

Expression

Evaluates one or more expressions within the message, then transforms the message according to the results of its evaluation.

transformer-reference-icon

Transformer Reference

References a transformer that is defined as a global element.

Documentation: Transformer Reference

xslt-transformer-icon

XSLT

Transforms XML using XSLT.

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

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-sap-function-bapi

XML to Function (BAPI) (Enterprise Edition)

Reads the XML representing a JCo function from java.io.InputStream, java.lang.String or byte[] to build the SAP object expected by the SAP transport.

Documentation: SAP Connector.

xml-to-sap-idoc

XML to IDOC (Enterprise Edition)

Reads the XML representing an IDOC document from java.io.InputStream, java.lang.String, or byte[] to build the SAP object expected by the SAP transport.

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-transformer-icon

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.

property-icon

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.

variable-icon

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.

session-variable-icon

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.

Custom Transformers

For detailed information on configuring standard and custom Transformers with an XML editor, see Using 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.

HTTP Response to Object

Converts an HTTP response (that is, a string, stream, or byte array payload) into a Mule message.

HTTP Response to String

Converts an HTPP response into a string and preserves the message header.

Message to HTTP Response

Creates a valid HTTP response using the current message and its HTTP headers.

Body to Parameter Map

Converts the body of an HTTP request into a Map object.