Configuring DataWeave Expressions

Configure DataWeave expressions in your integrations and implementations from Expression Builder, Transformation Builder, or from the configuration XML. DataWeave is the programming language designed by MuleSoft for data transformation and expressions in connector operations and other components that process messages, such as payload and attributes, and other Mule event data.

The *Expression Field*, *Expression Builder*, and *Transformation Builder* button location highlighted in a component

1	Expression Field: Enter a DataWeave expression or script in a component configuration panel.
2	Expression Builder: Simplify and enhance the process of creating and managing expressions within your Mule applications.
3	Transformation Builder: Create DataWeave transformations in your Mule applications in a visual interface.

If you create an implementation or integration in Anypoint Code Builder, you create a Mule app that runs on an instance of the Mule runtime engine.

Anypoint Code Builder integrates DataWeave expressions and transformations into the Mule app development process and supports these features:

Hierarchical mapping
Object-to-object and array-to-array transformations
Concatenation of strings, numbers, and booleans
Type conversions

Anypoint Code Builder supports these transform mapping use cases:

Object to Object
Primitive to Primitive
Object to Primitive
Primitive to Object
Object to Array
Array to Object
Type conversion Object to Object
Concatenation of simple fields
Array to Array (same level)

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 the Expression Field

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

To open a component expression field (fx):

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

The markup #[] in the fx field also appears in the XML to indicate that the field is for an expression.
```
<set-variable variableName="variableName" value="#[]"
              doc:name="Set variable" doc:id="ndpiap" />
```
Click the Expression Builder button to configure the component.

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

Open Expression Builder

Expression Builder simplifies the process of creating and managing expressions within your Mule applications. The builder provides a visual interface to create DataWeave expressions and transformations.

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 Expression Builder for a component 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 the Expression 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 Expression Builder.
  2. Click the Functions tab.
    
    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 Expression Builder for a component 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:

Open Transformation Builder

Create DataWeave transformations in your Mule applications with the Transformation Builder tool.

The *Transformation Builder* window and its sections highlighted

Click on Transformation Builder.
In the Transformation Workspace section, drag the source field from the input payload to the target field to map the source data to the target data.

The mapped fields display a green dot and are highlighted to indicate that the mapping is successful. The Script section updates with the new mapping, and the Output Preview"* section displays the output of the transformation.

If needed, map multiple source field to a target field, and then the Transform Builder concatenates them.
Click the More Actions icon to refresh metadata or remove all mappings.
Verify the input sample generated from the field mapping.

You can select the generated sample or provide your own sample data.

Provide Sample Data for a DataWeave Expression

Test and preview DataWeave expressions locally in Anypoint Code Builder. Add sample data for Mule variables such as payload in fx fields to preview outputs without running your application.

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 data the expression expects.
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:

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

See Important 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 in Expression Builder:
1. From the canvas, click the component that contains your sample data to open Expression Builder for that field.
2. Click xf of the component that has sample data to open 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" />

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.