Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.4)
  3. Developing

  4. Transformers

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 building blocks 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.

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.

Data Mapping

The Anypoint DataMapper transformer provides a powerful and versatile alternative to many of the standard transformers bundled with Studio. In addition to translating data from one format to another and manipulating payload values, DataMapper can map an input field (such as last_name) to a different output field (such as family_name). Multiple fields (such as title, first_name, and last_name can combine to form a composite field (such as full_name). DataMapper supports expressions that facilitate conditional value recalculation and also powerful database queries. It can also retrieve session state information to facilitate conditional message routing. For details, see DataMapper User Guide and Reference.

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, i.e. "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 will retain 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.

Script
Transformer		 Description Documentation

groovy transformer 24x16

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 transformer 24x16

JavaScript

Implements a JavaScript transformer backed by a JavaScript script engine

Script Transformer Reference

python transformer 24x16

Python

Implements a JavaScript transformer backed by a Python script engine

Script Transformer Reference

ruby transformer 24x16

Ruby

Implements a script transformer backed by a Ruby script engine

Script Transformer Reference

Transformer-24x16

Script

Implements a script transformer backed by a JSR-223-compliant script engine, such as Groovy, JavaScript, Python, or Ruby

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.

Java Object Transformer Description Documentation

Transformer-24x16

Byte-Array-to-Object

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

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Byte-Array-to-Serializable

Deserializes a byte array, thus converting it into an object

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Byte-Array-to-String

Converts a byte array to a string

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

File-to-Byte-Array

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

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

File-to-String

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

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

HTTP-Response-to-Object

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

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Java

Transforms the data from one format to another

Java Transformer Reference

Transformer-24x16

JmsMessage-to-Object Enterprise Edition

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

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Json-to-Object

Converts a Json-encoded object graph into a Java Object

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Object-to-Byte-Array

Serializes all objects except for strings, which are converted using the getBytes() method

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Object-to-HTTP-Request

Creates a valid HTTP request from the current message and includes any HTTP headers set on the current message

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Object-to-JmsMessage Enterprise Edition

Converts a Java Object into one of five types of JMS messages, depending on the object

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Object-to-Json

Converts a Java Object to a JSON-encoded object consumable by other languages

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Object-to-String

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

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Object-to-XML

Converts a Java Object into XML code using XStream

Object-to-XML Transformer Reference

Transformer-24x16

Serializable-to-Byte-Array

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

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

String-to-Byte-Array

Converts a string into a byte array

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

XML-to-Object

Uses XStream to convert XML into Java Bean graphs

XML-to-Object Transformer Reference

Content Transformers

This group of transformers modifies messages by adding to, deleting from, or converting a message payload (or a message header).

Content
Transformer		 Description Documentation

Transformer-24x16

Append string

Appends a string to a message payload

Append String Transformer Reference

Transformer-24x16

Body-to-Parameter-map

Converts the body of an HTTP request into a Map object

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Expression

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

Expression Transformer Reference

Transformer-24x16

HTTP-Response-to-String

Converts an HTTP response into a string and preserves the message header

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Message-to-HTTP-Response

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

All of the configuration fields for this transformer are covered in the Common Transformer Configuration Fields section of this page.

Transformer-24x16

Transformer Ref

References a transformer that is defined as a global element

Transformer Reference

Transformer-24x16

XSLT

Transforms XML using XSLT

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.

SAP-Specific
Transformer		 Description Documentation

Transformer-24x16

SAP-Object-to-XML Enterprise Edition

Transforms a SAP object representing a JCo function or IDoc document into its XML representation

SAP Endpoint Reference

Transformer-24x16

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

SAP Endpoint Reference

Transformer-24x16

XML-to-IDoc 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

SAP Endpoint Reference

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.

Please 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 (i.e. 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 building blocks, 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:

Transformer What it Does Documentation

Transformer-24x16

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 will receive a different payload. Typically, this attachment is treated as a separate, secondary part of the outbound payload.

Attachment Transformer Reference

Transformer-24x16

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.

Property Transformer Reference

Transformer-24x16

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.

Variable Transformer Reference

Transformer-24x16

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.

Session Variable Transformer Reference

Custom Transformers

For detailed information on configuring standard and custom Transformers with an XML editor, see Using Transformers.