Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.8)
  3. Key Concepts

  4. Mule Message Transformation

Mule Message Transformation

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.

To better understand how Mule message processors act upon messages, it is useful to examine a message before and after it is processed. When a transformer converts the content of a message payload from one data structure to another, or from one data format to another – for example, JSON to Java Object, Map to CSV, or Java Object to XML – you may wonder exactly how Mule has changed, removed or added to the contents of a message. Reviewing a message "before and after" should help you to be better able to work with the message further in the flow.

This document uses an example application and draws upon the content of the Mule Message Structure document to examine a message as it passes through a Transform Message component in a flow. Running the application in debug mode in Anypoint Studio, the screenshots illustrates the innards of a message using the Visual Debugger which facilitates "frozen-in-time" viewing of a message.

Background

This document describes the details of the example within the context of Anypoint Studio , Mule’s graphical user interface (GUI). Where appropriate, the XML configuration accompanies the Studio interface screenshots. This document assumes that you are familiar with Mule and the Anypoint Studio interface. Further, it assumes you have read the Mule Message Structure document to understand the contents of a Mule message.

Revealing a Mule Message by Example

To examine a Mule message, this document uses an example application which converts the contents of a CSV file into contacts in Salesforce. You can view examples in Exchange.

Briefly, the File Endpoint polls the input folder for new files every ten seconds. When it spots a new file, it reads the content, then passes the data to the Transform Message component, which uses DataWeave code to transform the message payload. This component not only converts the format of the data from CSV to a collection, it maps the input fields from the CSV file – FirstName, LastName, etc. – to output fields that Salesforce uses in a collection. Each mapping earns an arrow which helps you to visualize the activity that occurs within the Transform Message component. When it has converted all the contacts in the file to a collection of Salesforce-friendly data, the application uses a Salesforce Connector to push data into your Salesforce account. The connector’s configurations specify the operation – Create – and the sObject type – Contact – which dictate exactly how the data uploads to Salesforce; in this case, it creates new contacts.

Studio Visual Editor

message+state

Studio XML Editor

<mule xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:data-mapper="http://www.mulesoft.org/schema/mule/ee/data-mapper" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:file="http://www.mulesoft.org/schema/mule/file" xmlns:sfdc="http://www.mulesoft.org/schema/mule/sfdc" xmlns:spring="http://www.springframework.org/schema/beans" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
http://www.mulesoft.org/schema/mule/sfdc http://www.mulesoft.org/schema/mule/sfdc/current/mule-sfdc.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://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">
    <sfdc:config doc:name="Salesforce" name="Salesforce" password="password" username="salesforceuser@email.com">
        <sfdc:connection-pooling-profile exhaustedAction="WHEN_EXHAUSTED_GROW" initialisationPolicy="INITIALISE_ONE"/>
    </sfdc:config>
    <flow doc:description="Upload a csv file of contact information into Salesforce as new contacts." doc:name="Contacts_to_SFDC" name="Contacts_to_SFDC">
        <file:inbound-endpoint doc:name="File Input" moveToDirectory="src/test/resources/output" path="src/test/resources/input" pollingFrequency="10000" responseTimeout="10000"/>
        <dw:transform-message doc:name="Transform Message">
          <dw:set-payload><![CDATA[%dw 1.0
            %output application/java
            ---
            {
              Phone: payload.Phone,
              FirstName: payload.FirstName,
              LastName: payload.LastName,
            	Email: payload.Email
            }
            ]]>
          </dw:set-payload>
        </dw:transform-message>
        <sfdc:create config-ref="Salesforce" doc:name="Salesforce" type="Contact">
            <sfdc:objects ref="#[payload]"/>
        </sfdc:create>
    </flow>
</mule>

Before Transforming the Message

As discussed in the Message Structure document, a Mule message consists of two main parts:

  • a message header, in which properties reside

  • a message payload which contains the data that Mule processes

The Mule message object, which contains the Mule message, may also contain variables . The following sections examine the message header, payload and variables before the message encounters the Transform Message component in the above example.

To access this information about the message header and payload, we set breakpoints on the message processors in the application, then ran the application in debug mode in Studio. Studio’s Visual Debugger displays the messages’s header and payload information in the Mule Debugger Console, below the canvas.

Learn more about how to examine the contents of your messages using the Visual Debugger .

Message Header

The Message (see image below) contains data from the header of the message (i.e. metadata). In this example, you can see the message’s identifiers and determine if there are attachments, which would be arrays if they existed.

Note that the Message Processor name indicates a Value of Transform Message; the Message Processor item indicates the next message processor in the flow that the message will encounter.

message

Message Payload

The payload (see image below), not surprisingly, contains the payload of the message, or rather, the data that the Mule application processes. Before it encounters the Transform Message component, the payload contains a CSV file – currentFile – with type java.io.File.

payload

Properties

The Visual Debugger also displays any inbound and outbound properties on the message as it enters the Transform Message component. The Inbound Properties on the message include metadata about the payload, including its filename, timestamp, and the endpoint through which it entered the application, MULE_ORIGINATING_ENDPOINT. Inbound properties are read-only and cannot be added, removed or copied by message processors in the application.

inbound

The Outbound Properties indicate similar information about the payload, and can be removed or copied by message processors in the application.

outbound

Variables

The Visual Debugger displays any variables or session variables included in the message object as it encounters the Transform Message component. The File endpoint in this flow set two Variables on the message to indicate where the Transform Message component should move the file after processing, and the frequency with which the endpoint polls the input folder for new data.

variables

There are no Session Variables on this message at this point.

session

After Transforming the Message

The task of the Transform Message component in this application is to convert the contents of the CSV file into a Java object that Salesforce can process. Further, it maps the contents so that the value in the Name column in the CSV file converts to the Name field in the Salesforce contact, and so on for each field. The following displays the message as it emerges from this component.

Message Header

The Transform Message component has made no changes to the message header contents.

message2

Message Payload

The Transform Message component has dramatically changed the payload! Now an array list of maps (image below, top), the contacts from the CSV file appear as values of each hashmap. Expanding the contents further, each hashmap contains a key-value pair (below, bottom).

payload2
keyValuePair

Properties

As Mule message processors cannot add, remove or act upon inbound properties, none has changed.

inbound2

The Transform Message component did not set, remove or copy any outbound properties on the message.

outbound2

Variables

The Transform Message component did not add or remove any Variables or Session Variables.

variables2
session2

More Examples

Setting a Variable on a Message

The Variable transformer in a flow sets the payload of the message as a minPrice variable on the message. Recall that the Message Processor item indicates the next message processor in the flow that the message will encounter.

<flow>
...
    <set-variable doc:name="Variable" value="#[payload]" variableName="minPrice"/>
...
</flow>

BEFORE

beforeVariable

AFTER

afterVariable

Setting a Property on a Message

The Property transformer in a flow sets the payload of the message as a size property on the message.

<flow>
...
    <set-property doc:name="Property" propertyName="size" value="small"/>
...
</flow>

BEFORE

beforeProperty

AFTER

afterProperty

Setting a Payload on a Message

The Set Payload transformer in a flow replaces the payload of the message with the string Hello, World.

BEFORE

beforeSetPayload

AFTER

afterSetPayload

To access the property or variable that you have set on a message earlier in a flow, or in a different flow in the application, use a MEL expression.

Learn more in the Mule Message Structure document, under the heading Setting and Using Properties and Variables.

See Also