DataWeave Scripts

DataWeave 2.1 is compatible with Mule 4.1. Standard Support for Mule 4.1 ended on November 2, 2020, and this version of Mule will reach its End of Life on November 2, 2022, when Extended Support ends.

Deployments of new applications to CloudHub that use this version of Mule are no longer allowed. Only in-place updates to applications are permitted.

MuleSoft recommends that you upgrade to the latest version of Mule 4 that is in Standard Support so that your applications run with the latest fixes and security enhancements.

DataWeave is the primary data transformation language for Mule flows. You can write standalone DataWeave scripts in Transform Message components, or you can write inline DataWeave expressions to transform data in-place and dynamically set the value of various properties, such as configuration fields in an event processor or global configuration element. Inline DataWeave expressions are enclosed in #[ ] code blocks. For example, you can use a DataWeave expression to set conditions in a Choice router or to set the value of a Set Payload or Set Variable component.

The DataWeave code in this example sets a timestamp variable to the current time using the DataWeave now() function:

Example: Simple Inline DataWeave Script

<set-variable value="#[now()]" variableName="timestamp" doc:name="Set timestamp" />

You can also store DataWeave code in external files and read them into other DataWeave scripts, or you can factor DataWeave code into modules (libraries) of reusable DataWeave functions that can be shared by all the components in a Mule app.

The Structure of DataWeave Scripts

DataWeave scripts and files are divided into two main sections:

The Header, which defines directives that apply to the body expression (optional).
The Body, which contains the expression to generate the output structure.

When you include a header, the header appears above the body separated by a delimiter consisting of three dashes: ---.

Here is an example of a DataWeave file with an output directive declared in the header, followed by a DataWeave expression to create a user object that contains two child key/value pairs:

Example: Simple DataWeave Script

%dw 2.0
output application/xml
---
{
  user: {
    firstName: payload.user_firstname,
    lastName: payload.user_lastName
  }
}

DataWeave Header

This example shows keywords (such as import and var) you can use for header directives.

DataWeave Script

%dw 2.0
import * from dw::core::Arrays
var myVar=13.15
fun toUser(obj) = {
  firstName: obj.field1,
  lastName: obj.field2
}
type Currency = String { format: “##“}
ns ns0 http://www.abc.com
output application/xml
---
/*
 * Body here.
 * /

%dw: DataWeave version is optional. Default is 2.0.

Example: %dw 2.0
output: Commonly used directive that specifies the mime type that the script outputs.

Example: output application/xml

Valid values: Data DataWeave Output Formats and Writer Properties.

Default: If no output is specified, the default output is determined by an algorithm that examines the inputs (payload, variables, and so on) used in the script:
1. If there is no input, the default is output application/java.
2. If all inputs are the same mime type, the script outputs to the same mime type. For example, if all input is application/json, then it outputs output application/json.
3. If the mime types of the inputs differ, and no output is specified, the script throws an exception so that you know to specify an output mime type.
  
  Note that only one output type can be specified.
import: For importing a DataWeave function module. See DataWeave Functions.
var: Global variables for defining constants that you can reference throughout the body of the DataWeave script:
Example
```
%dw 2.0
var conversionRate=13.15
output application/json
---
{
 price_dollars: payload.price,
 price_localCurrency: payload.price * conversionRate
}
```
For details, see DataWeave Variables.
type: For specifying a custom type that you can use in the expression.

For a more complete example, see Type Coercion with DataWeave.

ns: Namespaces, used to import a namespace.

Example

%dw 2.0
output application/xml

ns ns0 http://www.abc.com
ns ns1 http://www.123.com
---
{
    ns0#myroot: {
         ns1#secondroot: "hello world"
    }
}

fun: For creating custom functions that can be called from within the body of the script.

Example

%dw 2.0
output application/json
fun toUser(user) = {firstName: user.name, lastName: user.lastName}
---
{
  user: toUser(payload)
}

Including Headers in Inline DataWeave Scripts

You can include header directives when you write inline DataWeave scripts by flattening all the lines in the DataWeave script into a single line. For smaller DataWeave scripts, this allows you to quickly apply header directives (without having to add a separate Transform Message component to set a variable), then substitute the variable in the next Event processor.

For example, here is the Mule configuration XML to create the same valid XML output as the previous Transform Message component:

Example: Simple Inline DataWeave Script

<set-payload value="#[output application/xml --- { myroot: payload } ]" doc:name="Set Payload" />

Note that the DataWeave documentation provides numerous transformation examples.

DataWeave Body

The DataWeave body contains an expression that generates the output structure. Note that MuleSoft provides a canonical way for you to work on data with the DataWeave model: a query, transform, build process.

Here is simple example that provides JSON input for a DataWeave script:

Example: JSON Input

{
    "message": "Hello world!"
}

This DataWeave script takes the entire payload of the JSON input above and transforms it to the application/xml format.

Example: Script that Outputs application/xml

%dw 2.0
output application/xml
---
payload

The next example shows the XML output produced from the DataWeave script:

Example: XML Output

<?xml version='1.0' encoding='UTF-8'?>
<message>Hello world!</message>

The script above successfully transforms the JSON input to XML output.

Errors (Scripting versus Formatting Errors)

A DataWeave script can throw errors due to DataWeave coding errors and due to formatting errors. So when transforming one data format to another, it is important to keep in mind the constraints of both the language and the formats. For example, XML requires a single root node. If you use the DataWeave script above in the attempt to transform this JSON input to XML, you will receive an error (Unexpected internal error) because the JSON input lacks a single root:

Example: JSON Input

{
    "size" : 1,
    "person": {
      "name": "Yoda"
    }
}

A good approach to the creation of a script is to normalize the input to the JSON-like application/dw format. In fact, if you get an error, you can simply transform your input to application/dw. If the transformation is successful, then the error is likely a formatting error. If it is unsuccessful, then the error is a coding error.

This example changes the output format to application/dw:

Example: DataWeave Script that Outputs application/dw

%dw 2.0
output application/dw
---
payload

You can see that the script successfully produces application/dw output from the JSON input example above:

Example: application/dw Output

{
  size: 1,
  person: {
    name: "Yoda"
  }
}

So you know that the previous error (Unexpected internal error) is specific to the format, not the coding. You can see that the application/dw output above does not provide a single root element, as required by the XML format. So, to fix the script for XML output, you need to provide a single root element to your script, for example:

Example: Script that Outputs application/xml

%dw 2.0
output application/xml
---
{
    "myroot" : payload
}

Now the output meets the requirements of XML, so when you change the output directive back to application/xml, the result produces valid XML output.

Example: XML Output Containing a Single XML Root

<?xml version='1.0' encoding='UTF-8'?>
<myroot>
  <size>1</size>
  <person>
    <name>Yoda</name>
  </person>
</myroot>

Escaping Special Characters

In DataWeave, you use the backslash (\) to escape special characters that you are using in an input string.

There are only a few special characters within a string:

$: You need to escape any use of of $ in a string. Otherwise, DataWeave treats the $ as an unnamed parameter for a function and returns the error Unable to resolve reference of $..
": For a string that is surrounded by double quotes, you need to escape any double quote that is part of the string, for example, "a\"bcdef". Here, the second double-quote is part of the string that starts with an a and ends with f.
' For a string that is surrounded by single quotes, you need to escape any single quote that is part of the string: for example, 'abcd\'e"f'. In this example, the second single quote is part of the string that starts with an a and ends with f. Notice that you do not need to escape the double quote in this case.
`: For a string that is surrounded by backticks (supported in DataWeave version 2), you must escape any backtick that is part of the string: for example, `abc\`def`.
\: Because the backslash is the character you use to escape other special characters, you need to escape it with a separate backslash to use it in a string, for example,\\.
\n: For inserting a new line.
\t: For inserting a tab.
\u: For inserting a unicode character, such as \u25c4.

Rules for Declaring Valid Identifiers

To declare a valid identifier, its name must meet the following requirements:

It must begin with a letter of the alphabet (a-z), either lowercase or uppercase.
After the first letter, the name can contain any combination of letters, numbers, and underscores (_).
The name cannot match any DataWeave reserved keyword (see Reserved Keywords for a complete list).

Here are some examples of valid identifiers:

myType
abc123
a1_3BC_22
Z___4
F

The following table provides examples of invalid identifiers and a description of what makes them invalid:

Identifier Issue

Identifier	Issue
`123456`	Cannot start with a number.
`value$`	Cannot contain special characters.
`_number`	Cannot start with an underscore.
`type`	Cannot be a reserved keyword.

123456

Cannot start with a number.

value$

Cannot contain special characters.

_number

Cannot start with an underscore.

type

Cannot be a reserved keyword.

Reserved Keywords

Valid identifiers cannot match any of the reserved DataWeave keywords:

and
as
async
case
default
do
else
enum
false
for
fun
if
import
input
is
ns
null
or
output
private
throw
true
type
unless
using
var
yield

Examples

The input strings in the DataWeave scripts escape special characters, while the output escapes in accordance with the requirements of the output format, which can vary depending on whether it is application/json, application/xml, application/csv, or some other format.

This example escapes the internal double quotation mark that is surrounded by double quotation marks.

DataWeave Example

%dw 2.0
output application/json
---
{
    "a": "something",
    "b": "dollar sign (\$)",
    "c": 'single quote (\')',
    "c": "double quote (\")",
    "e": `backtick (\`)`
}

Notice that the JSON output also escapes the double quotation marks to make the output valid JSON but does not escape the other characters:

JSON Output

{
  "a": "something",
  "b": "dollar sign ($)",
  "c": "single quote (')",
  "c": "double quote (\")",
  "e": "backtick (`)"
}

The following example escapes the same characters but outputs to XML.

DataWeave Example

%dw 2.0
output application/xml
---
{
  xmlExample:
  {
     "a": "something",
     "b": "dollar sign (\$)",
     "c": 'single quote (\')',
     "d": "double quote (\")",
     "e": `backtick (\`)`
   }
}

The XML output (unlike JSON output) is valid without escaping the double quotation marks:

XML Output

<?xml version='1.0' encoding='UTF-8'?>
<xmlExample>
  <a>something</a>
  <b>dollar sign ($)</b>
  <c>single quote (')</c>
  <d>double quote (")</d>
  <e>backtick (`)</e>
</xmlExample>

DataWeave Comments

Comments that use a Java-like syntax are also accepted by DataWeave.

// My single-line comment here.

/*
 * My multi-line comment here.
 */

dwl File

In addition to specifying DataWeave scripts in the Transform and other components, you can also specify the scripts in a .dwl file. In Studio projects, your script files are stored in src/main/resources.

In the Mule app XML, you can use the ${file::filename} syntax to send a script in a dwl file through any XML tag that expects an expression. For example, see the when expression="${file::someFile.dwl}" in the Choice router here:

<http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/test">
  <http:response >
    <http:body ><![CDATA[#[${file::transform.dwl}]]]></http:body>
  </http:response>
</http:listener>
<choice doc:name="Choice"  >
  <when expression="${file::someFile.dwl}" >
    <set-payload value="It's greater than 4!" doc:name="Set Payload"  />
  </when>
  <otherwise >
    <set-payload value="It's less than 4!" doc:name="Set Payload" />
  </otherwise>
</choice>

Gartner names MuleSoft a Leader

Unleash the power of Salesforce Customer 360 through integration

Anypoint Platform Fundamentals

The world of AI is a world of APIs