DataWeave 2.0: Introduction to Transformations

  • November 23, 2020

DataWeave is the MuleSoft expression language for accessing and transforming data that travels through a Mule application. It’s tightly integrated with the Mule Runtime Engine, which runs the scripts and expressions in your Mule app.

What is a Mule event?

A Mule event contains the core information processed by the runtime. It travels through components inside your Mule app following the configured application logic.

NOTE: A Mule event is immutable, so every change to an instance of a Mule event results in the creation of a new instance.

A Mule Event is composed of these objects:

  • A message payload and its associated attributes
  • Variables that are Mule Event metadata used in your flow
    DataWeave1

How DataWeave scripts act on data in a Mule Event

DataWeave scripts act on data in the Mule Event. DataWeave is used most often to access and transform data in the message payload. For example, after a component in your app retrieves data from one system, you can use DataWeave to modify and output selected fields in that data to a new data format, and then use another component in your app to pass on that data to another system.

DataWeave supports many formats, including Java, JSON, XML, dw (for testing a DataWeave expression), CSV and xlsx. The DataWeave expression is a data model for the output. It’s not dependent on the types of input and output, just their structure.

NOTE: The examples in this article use Anypoint Studio 7.7 and the Mule Server 4.3.0 EE Runtime.

The most complex transformations are performed in the “Transform Message” processor, which can be drag-and-dropped to the canvas from the Core module, as shown below.

DataWeave2

In the Properties tab of a transform message, the default output type is set to application/java as Mule, the runtime engine of Anypoint Platform, is a lightweight Java-based enterprise service bus (ESB).

DataWeave3

Until the target is expecting another format, such as JSON or XML, you should leave this set to Java only. Doing so ensures no internal marshaling and unmarshalling is done, giving better performance.

To change the output data type, change the application/java to the required data type. In the example below, we’ll change JSON input into different output data formats.

NOTE: Before importing any data type, you won’t have examples or a schema section in the Package Explorer.

DataWeave4

It’s automatically created and populated once you import an example or schema of data, as shown below.

DataWeave5
DataWeave6

Examples of basic data structures

DataWeave7

In JSON, objects are denoted with curly braces and an array with square braces, and properties are written as key-value pairs delimited by a colon and separated by a comma.

DataWeave8

When writing an expression for XML input, by default, only XML elements — not attributes — are created as JSON fields or Java object properties. Use the “@” sign to reference the attributes, as shown in the exhibit above.

Output in type JAVA

DataWeave9

In the input section, check out the data type and format and preview the output by clicking the Preview button in the upper right corner. (This will work only if you’ve imported an example while defining a data type in the input section of the Transform Message component.)

DataWeave10

Output in type JSON

Changing only /java to /json will convert the output in JSON format, which can be verified using the Preview tab.

DataWeave11

Output in type XML

XML format must have a root object. So using /xml instead of /json, you get the following error because we don’t have a root element.

DataWeave12

After adding the root object, you’ll get the desired output in the Preview section.

DataWeave13

If you want to add any attribute to the target output, you can do so as the following exhibit shows. Here, we added attribute currency = USD to the price.

DataWeave14

Output in CSV format

For CSV type output, there shouldn’t be either a root object or a nested object (such as ‘plane,’ in the above example).

DataWeave15

Types of DataWeave errors

There are two types of DataWeave errors:

  1. Scripting errors are a problem with the syntax of a DataWeave Expression. These errors are comparatively easy to handle.
  2. Formatting errors are a problem with how the transformation from one format to another is written. For example, a script to output XML that doesn’t specify a data structure with a single root node.

If you get an error, transform the input to application/dw. If the transformation is successful, the error is likely a formatting error.

— By Sanket Kangle