To better understand how Mule message processors act upon messages, it is useful to examine the state of 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 its "before and after" state 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 the state of a message as it passes through a DataMapper transformer in a flow. Running the application in debug mode in Anypoint Studio, the screenshots illustrates the state of a message using the Visual Debugger which facilitates "frozen-in-time" viewing of a message.
This document describes the details of the example within the context of Anypoint Studio, Mule ESB’s graphical user interface (GUI). Where appropriate, the XML configuration accompanies the Studio interface screenshots. This document assumes that you are familiar with Mule ESB and the http://www.mulesoft.org/documentation/display/current/Mule+Studio+Essentials[Anypoint Studio interface]. Further, it assumes you have read the Mule Message Structure document to understand the contents of a Mule message. To increase your familiarity with Anypoint Studio, consider reading http://www.mulesoft.org/documentation/display/current/Mule+Studio+Essentials[Mule Studio Essentials].
To examine the state of a message, this document uses an example application which converts the contents of a CSV file into contacts in Salesforce. Bundled as an example application in Studio, you can read the full details of its moving parts and how it works in the Connect with Salesforce Example documentation.
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 DataMapper Transformer. This transformer not only converts the format of the data from CSV to a collection, it automatically 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 DataMapper transformer. 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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 <?xml version="1.0" encoding="UTF-8"?> <mule version="EE-3.5.0" 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/ee/data-mapper http://www.mulesoft.org/schema/mule/ee/data-mapper/current/mule-data-mapper.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="email@example.com"> <sfdc:connection-pooling-profile exhaustedAction="WHEN_EXHAUSTED_GROW" initialisationPolicy="INITIALISE_ONE"/> </sfdc:config> <data-mapper:config doc:name="DataMapper" name="datamapper_grf" transformationGraphPath="datamapper.grf"/> <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"/> <data-mapper:transform config-ref="datamapper_grf" doc:name="DataMapper"/> <sfdc:create config-ref="Salesforce" doc:name="Salesforce" type="Contact"> <sfdc:objects ref="#[payload]"/> </sfdc:create> </flow> </mule>
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 itself, may also contain variables. The following sections examine the message header, payload and variable before the message encounters the DataMapper transformer.
To access this information about the state of 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 state of your messages using the Visual Debugger.
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 DataMapper; the Message Processor item indicates the next message processor in the flow that the message will encounter.
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 DataMapper, the payload contains a CSV file –
currentFile – with type
The Visual Debugger also displays any inbound and outbound properties on the message as it enters the DataMapper. The Inbound Properties on the message include metadata about the payload, including its filename, timstamp 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.
The Outbound Properties indicate similar information about the payload, and can be removed or copied by message processors in the application.
The Visual Debugger displays any variables or session variables included in the message object as it encounters the DataMapper. The File endpoint in this flow set two Variables on the message to indicate where DataMapper should move the file after processing, and the frequency with which the endpoint polls the input folder for new data.
There are no Session Variables on this message before it encounters the DataMapper.
The task of the DataMapper 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 First Name column in the CSV file converts to the First Name field in the Salesforce contact, and so on for each field. The following displays the message state as it emerges from the DataMapper.
DataMapper 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).
As Mule message processors cannot add, remove or act upon inbound properties, none has changed.
DataMapper did not set, remove or copy any outbound properties on the 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>
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>
The Set Payload transformer in a flow replaces the payload of the message with the string
1 2 3 4 5 <flow> ... <set-payload value="#['Hello, world.']" doc:name="Set Payload"/> ... </flow>
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.