This utility module simplifies changes to values.

The module is included with Mule runtime. To use it, you must import it into your DataWeave code, for example, by adding the line import * from dw::util::Values to the header of your script.

Introduced in DataWeave 2.2.2. Supported by Mule 4.2.2 and later.

Functions

attr

attr(Namespace | Null, String): PathElement

This function creates a PathElement to use for selecting an XML attribute and populates the type’s selector field with the given string.

Some versions of the update and mask functions accept a PathElement as an argument.

Parameters
Name Description

namespace

The namespace of the attribute to select. If not specified, a null value is set.

name

The string that names the attribute to select.

Example

This example creates an attribute selector for a specified namespace (ns0) and sets the selector’s value to "myAttr". In the output, also note that the value of the "kind" key is "Attribute".

Source
1
2
3
4
5
6
%dw 2.0
output application/json
import * from dw::util::Values
ns ns0 http://acme.com/fo
---
attr(ns0 , "myAttr")
Output
1
2
3
4
5
{
   "kind": "Attribute",
   "namespace": "http://acme.com/foo",
   "selector": "myAttr"
 }

field

field(Namespace | Null, String): PathElement

This function creates a PathElement data type to use for selecting an object field and populates the type’s selector field with the given string.

Some versions of the update and mask functions accept a PathElement as an argument.

Parameters
Name Description

namespace

The namespace of the field to select. If not specified, a null value is set.

name

A string that names the attribute to select.

Example

This example creates an object field selector for a specified namespace (ns0) and sets the selector’s value to "myFieldName". In the output, also note that the value of the "kind" key is "Object".

Source
1
2
3
4
5
6
 %dw 2.0
 output application/json
 import * from dw::util::Values
 ns ns0 http://acme.com/foo
 ---
 field(ns0 , "myFieldName")
Output
1
2
3
4
5
{
   "kind": "Object",
   "namespace": "http://acme.com/foo",
   "selector": "myFieldName"
 }

index

index(Number): PathElement

This function creates a PathElement data type to use for selecting an array element and populates the type’s selector field with the specified index.

Some versions of the update and mask functions accept a PathElement as an argument.

Parameters
Name Description

index

The index.

Example

This example creates an selector for a specified index. It sets the selector’s value to 0. In the output, also note that the value of the "kind" key is "Array".

Source
1
2
3
4
5
6
 %dw 2.0
 output application/json
 import * from dw::util::Values
 ns ns0 http://acme.com/foo
 ---
 index(0)
Output
1
2
3
4
5
{
   "kind": "Array",
   "namespace": null,
   "selector": 0
 }

mask

mask(Null, String | Number | PathElement): Any

Helper function that enables mask to work with a null value.

mask(Any, PathElement): Any

This mask function replaces all simple elements that match the specified criteria.

Simple elements do not have child elements and cannot be objects or arrays.

Parameters
Name Description

value

A value to use for masking. The value can be any DataWeave type.

selector

The PathElement selector.

Example

This example shows how to mask the value of a password field in an array of objects. It uses field("password") to return the PathElement that it passes to mask. It uses with "" to specify the value () to use for masking.

Source
1
2
3
4
5
%dw 2.0
output application/json
import * from dw::util::Values
---
[{name: "Peter Parker", password: "spiderman"}, {name: "Bruce Wayne", password: "batman"}] mask field("password") with "*****"
Output
1
2
3
4
5
6
7
8
9
10
[
   {
     "name": "Peter Parker",
     "password": "*****"
   },
   {
     "name": "Bruce Wayne",
     "password": "*****"
   }
 ]

mask(Any, String): Any

This mask function selects a field by its name.

Parameters
Name Description

value

The value to use for masking. The value can be any DataWeave type.

fieldName

A string that specifies the name of the field to mask.

Example

This example shows how to perform masking using the name of a field in the input. It modifies the values of all fields with that value.

Source
1
2
3
4
5
%dw 2.0
output application/json
import * from dw::util::Values
---
[{name: "Peter Parker", password: "spiderman"}, {name: "Bruce Wayne", password: "batman"}] mask "password" with "*****"
Output
1
2
3
4
5
6
7
8
9
10
[
   {
     "name": "Peter Parker",
     "password": "*****"
   },
   {
     "name": "Bruce Wayne",
     "password": "*****"
   }
 ]

mask(Any, Number): Any

This mask function selects an element from array by its index.

Parameters
Name Description

value

The value to mask. The value can be any DataWeave type.

index

The index to mask. The index must be a number.

Example

This example shows how mask acts on all elements in the nested arrays. It changes the value of each element at index 1 to false.

Source
1
2
3
4
5
%dw 2.0
output application/json
import * from dw::util::Values
---
[[123, true], [456, true]] mask 1 with false
Output
1
2
3
4
5
6
7
8
9
10
[
   [
     123,
     false
   ],
   [
     456,
     false
   ]
 ]

update

update(Object, String): Any

This update function updates a field in an object with the specified string value.

The function returns a new object with the specified field and value.

Parameters
Name Description

objectValue

The object to update.

fieldName

A string that provides the name of the field.

Example

This example updates the name field in the object {name: "Mariano"} with the specified value.

Source
1
2
3
4
5
%dw 2.0
import * from dw::util::Values
output application/json
---
{name: "Mariano"} update "name" with "Data Weave"
Output
1
2
3
{
  "name": "Data Weave"
}

update(Object, PathElement): Any

This update function updates an object field with the specified PathElement value.

The function returns a new object with the specified field and value.

Parameters
Name Description

objectValue

The object to update.

fieldName

A PathElement that specifies the field name.

Example

This example updates the value of a name field in the object {name: "Mariano"}. It uses field("name") to return the PathElement that it passes to update. It uses with "Data Weave" to specify the value (Data Weave) of name.

Source
1
2
3
4
5
%dw 2.0
import * from dw::util::Values
output application/json
---
{name: "Mariano"} update field("name") with "Data Weave"
Output
1
2
3
{
  "name": "Data Weave"
}

update(Array, Number): Any

Updates an array index with the specified value.

This update function returns a new array that changes the value of the specified index.

Parameters
Name Description

objectValue

The array to update.

indexToUpdate

The index of the array to update. The index must be a number.

Example

This example replaces the value 2 (the index is 1) with 5 in the the input array [1,2,3].

Source
1
2
3
4
5
%dw 2.0
import * from dw::util::Values
output application/json
---
[1,2,3] update 1 with 5
Output
1
2
3
4
5
6
[
   1,
   5,
   3
 ]

update(Array, String): Any

This update function updates all objects within the specified array with the given string value.

Parameters
Name Description

objectValue

The array of objects to update.

indexToUpdate

A string providing the name of the field to update.

Example

This example updates value of the role fields in the array of objects.

Source
1
2
3
4
5
%dw 2.0
import * from dw::util::Values
output application/json
---
[{role: "a", name: "spiderman"}, {role: "b", name: "batman"}] update "role" with "Super Hero"
Output
1
2
3
4
5
6
7
8
9
[{
   "role": "Super Hero",
   "name": "spiderman"
 },
 {
   "role": "Super Hero",
   "name": "batman"
}]

update(Array, PathElement): Any

This update function updates the specified index of an array with the given PathElement value.

The function returns a new array that contains given value at the specified index.

Parameters
Name Description

objectValue

The array to update.

indexToUpdate

The index of the array to update. The index must be specified as a PathElement.

Example

This example updates the value of an element in the input array. Notice that it uses index(1) to return the index as a PathElement, which it passes to update. It replaces the value 2 at that index with 5.

Source
1
2
3
4
5
%dw 2.0
import * from dw::util::Values
output application/json
---
[1,2,3] update index(1) with 5
Output
1
2
3
4
5
6
[
   1,
   5,
   3
 ]

update(Array | Object | Null, Array<String | Number | PathElement>): Any

Updates the value at the specified path with the given value.

Parameters
Name Description

objectValue

The value to update. Accepts an array, object, or null value.

path

The path to update. The path must be an array of strings, numbers, or `PathElement`s.

Example

This example updates the name of the user.

Source
1
2
3
4
5
%dw 2.0
import * from dw::util::Values
output application/json
---
{user: {name: "Mariano"}} update ["user", field("name")] with "Data Weave"
Output
1
2
3
4
5
6
{
   "user": {
     "name": "Data Weave"
   }
 }

update(Null, Number | String | PathElement): Any

Helper function that enables update to work with a null value.