Configuring DataWeave Expressions

Configure DataWeave expressions in your integrations and implementations from the expression builder UI or from the configuration XML. Mock data for your expressions so that you can preview sample output of your expressions in Anypoint Code Builder.

DataWeave is the programming language designed by MuleSoft for data transformation and expressions in connector operations and other components that process messages (payload and attributes) and other Mule event data. When you create an implementation or integration in Anypoint Code Builder, you are creating a Mule app that runs on an instance of the Mule runtime engine.

Before You Begin

Understand the basics of the DataWeave language.

DataWeave expressions accept the following:

DataWeave functions and operators and data types that their parameters accept.

For example, the concatenation function (++) accepts strings, arrays, objects, and date-related data types.

The IDE also provides built-in documentation for functions. For example, see List DataWeave Functions and Get Documentation.
Predefined Mule event variables such as payload, attributes, vars.
DataWeave selectors for capturing the values of fields within the payload, an attribute, or a variable within the Mule event.

For more resources, see DataWeave Overview.

Open an Expression (fx) Field

Most connector operations and components provide at least one field that accepts DataWeave expressions and scripts. In the configuration panel for a component, these fields are identified by an fx above the field. In the XML, these fields have #[] markup. Expression fields accept DataWeave expressions, including DataWeave functions and Mule event data, such as payload, attributes, and vars.

To open a component’s expression field:

Open a component that accepts expressions from the canvas in your implementation or integration project.
Click fx above the field to change the field from a string field to an expression field. For example:

The markup #[] in the fx field also appears in the XML to indicate that the field is for an expression, for example:
```
<set-variable variableName="variableName" value="#[]"
              doc:name="Set variable" doc:id="ndpiap" />
```
Click inside the field to open the expression builder for the component, for example:

Use the Data, Functions, and Preview tabs to ease configuration of expressions in your components. You can preview the expression’s output without the need to run your Mule app with data from external sources:

Check the Data Structure

To review the data structure of the Mule event, including the payload, attributes, and Mule variables, use the Data tab. The tab includes any sample data and is part of the expression builder for a component’s fx field. For example:

Data tab (with autogenerated data)

Data tab (expanded)

Data tab for expression field

Data tab for expression field with mock attributes

Any autogenerated strings (such as "dictum" in the payload example) are displayed as mock values and are used to generate output for previews, such as in the Preview tab. The attribute metadata keys in the example come from an HTTP Listener configuration in the flow.

The Input/Output tab in component configuration panels provides the structure of the Mule event data as it enters the component (Input) and the structure that the component outputs (Output), for example:

Input/Output tab for a component

List DataWeave Functions and Get Documentation

To get a list of available functions from a component’s Functions tab, the fx field, or the auto-complete menu in the XML editor:

Open a component that has an fx expression field.

For guidance, see Open an Expression (fx) Field.
List available functions:
- To display a list of DataWeave functions from the Core module from an empty fx field, press Ctrl+Space in an empty fx field. For example:
- To display functions from all DataWeave modules, such as String, Array, and Core modules:
  1. Click the fx field to open the expression builder.
  2. Click the Functions tab in the expression builder, for example:
    
    DataWeave Functions Function Reference
    
    Hover over a function to get a short description:
    
    Click Details to get complete documentation:

DataWeave Functions	Function Reference
Hover over a function to get a short description:	Click Details to get complete documentation:

Preview Output of DataWeave Expressions

Preview output of DataWeave expressions from the canvas or from the XML editor. The preview feature acts on sample data that you provide from the configuration XML for the payload (payload) or Mule variables (for example, vars.somevar) in your fx (expression) field.

To provide your own sample data, see Provide Sample Data for a DataWeave Expression.

Preview Results in the UI
Preview Results from the XML Editor

Preview Results in the UI

Preview auto-generated sample data, or preview your own sample data. Preview the output in the Preview tab of the expression builder for a component’s expression field.

Preview Auto-Generated Sample Data	Preview Your Sample Data
Output results from auto-generated sample data:	Outputs results from an expression with user-created sample data:

Preview Auto-Generated Sample Data

Preview Your Sample Data

Output results from auto-generated sample data:

Functions tab for expression field

Outputs results from an expression with user-created sample data:

Data tab for expression field

You can apply DataWeave selectors and functions to your sample data. To create sample data that has the structure and data types you expect, see Provide Sample Data for a DataWeave Expression.

Preview Results from the XML Editor

To preview the results from the configuration XML, place the cursor within your DataWeave code, click the Show Code Actions icon, and then click Run Preview:

Anypoint Code Builder opens a new Preview Output tab with the result of the function:

Provide Sample Data for a DataWeave Expression

To test and preview DataWeave expressions in your components locally, without running your application to retrieve Mule event data from an external source, add sample data for Mule variables, such as payload in fx fields.

You can create sample data in the following formats:

JSON
XML
CSV

To avoid errors when you run your app with real data, provide sample data that matches the basic structure, format, and data type of the real data the expression will receive.
Your sample data is overwritten when you reopen the component from the canvas.

To create sample data for a Mule variable:

Open your project.
In the XML editor, hover over the Mule event variable (such as payload), for example:
Click Quick Fix to open the Quick Fix menu.
Select Create sample data for your-value, such as Create sample data for payload, for example:
In the menu that opens, select a format, such as JSON, for the sample data.

The IDE opens a tab for your sample data.
Add content in the selected format to the sample data file. For example, for JSON:

Notice that the file name is payload.json. Files for your sample data and for the autocreated sample data are stored in the project directory src/test/resources.

See the Important note before adding sample data.

Hover over the value in the XML editor to display the structure, data keys, and data types of your sample data, for example:
Preview your sample data from the expression builder UI:
1. From the canvas, click the component that contains your sample data to open the expression builder for that field.
2. Click the expression field of the component that has sample data to open the expression builder for that field.
3. Click Preview to display the sample data. For example:
  
  You can modify the value. For example, add DataWeave selectors or functions:
  
  The example now returns an array of id values.

Address DataWeave Errors

When your DataWeave code contains a syntactic or semantic error, Anypoint Code Builder highlights the error and offers a suggested fix. Issues include:

Add a Missing Import Directive for a DataWeave Module
Fix an Undefined Function Error

Add a Missing Import Directive for a DataWeave Module

Many DataWeave modules require an explicit import directive in the expression. Only the Core module doesn’t require this directive.

For example, if you don’t import the String module to which this function belongs, the function camelize( "hello world") produces an error Unable to resolve the reference of 'camelize'.

<set-payload value='#[ camelize( "hello world")]' doc:name="Set payload" doc:id="vyvcds" />

The expression builder identifies the error. For example:

To fix this issue, click to add the import directive automatically, for example:

The XML for the fix is similar to this example:

<set-payload value='#[%dw 2.0
import camelize from dw::core::Strings
---
 camelize( "hello world")]' doc:name="Set payload" doc:id="vyvcds" />

Fix an Undefined Function Error

Anypoint Code Builder flags undefined functions automatically.

For example, in this code, DataWeave flags an error with toUpper:

When you place your cursor on the function, DataWeave provides information about the error:

Information about the undefined function error

To fix this issue:

Click the error to display the popup.
Click Quick Fix, and then click Create Function.

Anypoint Code Builder automatically adds a function definition with the ??? placeholder for you to define your function:
```
fun toUpper(param0: String) = ???
```

Update the function to use the upper function to return the provided String in uppercase characters:

<set-payload value="#[%dw 2.0
fun toUpper(param0: String) = upper(param0)
output application/json
---
toUpper('hello')]" doc:name="Set payload" doc:id="xiyfpa" />

Import a DataWeave Library

Use Anypoint Code Builder to import DataWeave libraries from Exchange into your Mule application.

A DataWeave library is a reusable package of DataWeave modules, mapping files, and resource files, such as JSON, XML, and CSV files.

You can import a DataWeave library the same way you import any other asset from Exchange:

Open your integration project in Anypoint Code Builder.
Open the Command Palette.
Show me how
- Use the keyboard shortcuts:
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- In the desktop IDE, select View > Command Palette.
- In the cloud IDE, click the (menu) icon, and select View > Command Palette.
Enter import and select the following command:
```
MuleSoft: Import Asset from Exchange
```
Select DataWeave Library.

To search for a library, type the search term and press Enter. For example, enter DataWeave:
Select the DataWeave library from the Assets From Exchange menu.
Select a version of the DataWeave library.

The status bar shows the progress.

When complete, Anypoint Code Builder shows a message that the dependency was successfully added to the project.