JMESPath Functions

append

array append(array $input, any $items)

Appends $items to the end of the $input array.

current_time

datetime current_time(number|string $offset)

Gets the current time in UTC as a datetime object and adds $offset hours to it. There is no limit for $offset, so it possible to add 30 days. The $offset argument can be a double, but will be converted to an integer. If $offset is a string, it must have an integer format.

For the examples of this function, we assume that the current time is 2021-02-19T12:00:00Z.

datasource

json_object datasource(string $dataSource, string $column, string $value)

Fetches data from the specified $dataSource, filtering by $value lookup in $column.

divide

number divide(number $left, number $right)

Divides $left by $right.

format

string format(number|string|datetime $data, string $format, string $culture)

Formats the input $data into a string following the rules defined by $format and $culture.
$format is expected as a composite formatting string to use for parsing.
$culture should be a language culture name, based on ISO-639-1 (ie. ‘en-US‘, ‘es-ES‘). If it is null or an empty string, then invariant culture is used.

The function is similar to the following C# code.

string.Format(new CultureInfo($culture), $"{{0:{$format}}}", $data);

get_property

any get_property(json_object $object, string $key)

Returns the Value for the property with name $key in the JSON $object.
Compared to the dot accessor (“.”), get_property allows you to provide a string instead of “knowing” the property name beforehand (ie. object.property vs get_property(object, "property")).

{
    "FirstName": "John",
    "LastName": "Doe",
    "Age": 30,
    "Status": {
        "Enabled": true
    },
    "Roles": [
        "User",
        "Admin"
    ]
}

get_rest_api

json_object get_rest_api(string $baseUri, json_object $uriParameters, boolean $throwOnError)

Sends a GET request to the specified $baseUri using $uriParameters to fill out its query, and returns a JSON with the result.
The $baseUri parameter should present its query portion as placeholders, akin to string_interpolate.
In case of failure, the $throwOnError flag determines whether to allow the error to reach JMES (true) or just return null (false).

get_rest_api(
"https://exampleservice.com/api?id={userId}",
{ "userId": 123456 },
`true`)

group_adjacent

array group_adjacent(array $entry, &groupExpression)

Groups adjacent elements of an input array based on &groupExpression. The functions returns an array of arrays, where each nested array contains grouped entries of $entry.

{
    "entry": [
        { "a": "foobar", "id": 1234},
        { "a": "foo", "id": 56789},
        { "a": "bar", "id": 56789},
        { "a": "baz", "id": 1234},
        { "a": "foo-bar", "id": 1234}
    ]
}

group_adjacent(entry, &id)

[
    [
        { "a": "foobar", "id": 1234 }
    ],
    [
        { "a": "foo", "id": 56789 },
        { "a": "bar", "id": 56789 }
    ],
    [
        { "a": "baz", "id": 1234 },
        { "a": "foo-bar", "id": 1234 }
    ]
]

has_value

bool has_value(any $entry)

Returns an indication of whether or not $entry has a value, based on the following critera:

• $entry is a boolean and its value is true.
• $entry is a string and it is not null nor has the value ‘false’.
• $entry is a number and is greater than 0.
• $entry is not null.

if

any if(any $condition, any $trueValue, any $falseValue)

Similar to its Excel counterpart, if returns $trueValue if $condition is true and otherwise returns $falseValue.

The evaluation for $condition follows the same rules as for has_value.

items

array items(json_object $object)

Converts the JSON $object into an array of its properties, where each is broken into an array of 2: its name and its value.

{
    "obj": {
        "name1": "value1",
        "name2": "value2"
    }
}

[
    [ "name1", "value1" ],
    [ "name2", "value2" ]
]

join_hide

string join_hide(string $separator, string[] $arr)

Concatenates the elements of $arr, using the specified $separator between each. Whitespace or null strings in $arr are ignored.
Returns an empty string if any parameter is invalid.

list_join

array list_join(array $leftArray, array $rightArray, &leftEvaluateBy, &rightEvaluateBy)

Groups the two input lists on each their expression followed by joining the two grouped lists with respect to the selected evaluation criteria. Entries that do not have matching keys, either in $leftArray or $rightArray, are shown in the result with no matching counterpart.

Returns a joined list with entries: index, list of entries from the $leftArray and a list of entries from the $rightArray for each possible combination from the join.

From the following data as inputJson:

{
    "people": [
        { "name": "foo", "teamId": 1 },
        { "name": "bar", "teamId": 1 },
        { "name": "baz", "teamId": 2 },
        { "name": "foobar", "teamId": 3 }
    ],
    "teams": [
        { "name": "foo-bar-team", "id": 1 },
        { "name": "baz-team", "id": 2 },
        { "name": "baz-team-2", "id": 2 },
        { "name": "foobar-team-10", "id": 10 }
    ]
}

Evaluating:

list_join(inputJson.people, inputJson.Teams, &teamId, &id)

Would give us the following result:

[
    {
        "__index": 0,
        "left": [
            { "name": "foo", "teamId": 1 },
            { "name": "bar", "teamId": 1 }
        ],
        "right": [
            { "name": "foo-bar-team", "id": 1 }
        ]
    },
    {
        "__index": 1,
        "left": [
            { "name": "baz", "teamId": 2 }
        ],
        "right": [
            { "name": "baz-team", "id": 2 },
            { "name": "baz-team-2", "id": 2 }
        ]
    },
    {
        "__index": 2,
        "left": [
            { "name": "foobar", "teamId": 3 }
        ],
         "right": [ ]
     },
    {
        "__index": 3,
        "left": [],
        "right": [
            { "name": "foobar-team-10", "id": 10 }
        ]
    }
]

list_range_fill

array list_range_fill(array $entry, int &keySelector, int &stepFunction, &constructor)

Takes a list of items containing (string)name and (integer)value, and fills missing values between $entry values. The &keySelector expression points to the value element in $entry. The &stepFunction expression is used to calculate the next values. If &keySelector and &stepFunction does is not integers an error is returned. The functions orders $entry numerically and alphabetically.

The constructor is used when filling elements in the returned list. It consists of three elements:

• __previous: the previous item from the input list. This is only used for the second item of $entry onwards. It contains Name and Value of this item.
• __next: the next item from the input list, e.g. on element two, this will point to element three. It contains Name and Value of this item.
• __key: the calculated value from using &stepFunction.

Filling elements in the return list is performed iteratively. The first iteration initiates the list, and defines __previous as the first item in $entry and __next as the second item in $entry. __key is updated using &stepFunction for each iteration, until __key equals the value of __next. __previous is then defined as __next and __next as the next item in $entry (if any).

The function returns an array of items that consists of:

• Name: Name of the previous item in $entry.
• previousValue: Value of the previous item in $entry. This field is only provided when Value (see below) is between two values in $entry.
• nextValue: Value of the next item in $entry. This field is only provided when Value (see below) is between two values in $entry.
• Value: Current value, as either calculated by &stepFunction or initialized by the first item in $entry.

From the following expression based on input data input:

list_range_fill(input, &Value, &add(@,`1`), &{Name:__previous.Name, previousValue:__previous.Value, nextValue:__next.Value, Value: __key})

We get the following correct result on Integer values:

{
     { "Name": "A", "Value": 2015 },
     { "Name": "B", "Value": 2017 },
     { "Name": "C", "Value": 2020 }
 }

[
    { "Name": "A", "Value": 2015 },
    { "Name": "A", "Value": 2016, "previousValue": 2015, "nextValue": 2017 },
    { "Name": "B", "Value": 2017 },
    { "Name": "B", "Value": 2018, "previousValue": 2017, "nextValue": 2020 },
    { "Name": "B", "Value": 2019, "previousValue": 2017, "nextValue": 2020 },
    { "Name": "C", "Value": 2020 }
]

If our input had string values instead, we would get an error:

{
     { "Name": "A", "Value": "2015" },
     { "Name": "B", "Value": "2017" },
     { "Name": "C", "Value": "2020" }
 }

merge

json_object merge(args[]:json_object $objects)

“Merges” the JSON $objects into a single one, following a concatenation (arrays/objects) or replacement (values) logic in order of the arguments provided.

{
    "PersonalInfo": {
        "FirstName": "John",
        "LastName": "Doe",
        "Age": 30
    },
    "UserInfo": {
        "Enabled": false,
        "Roles": [
            "User"
        ]
    },
    "NewUserInfo": {
        "Enabled": true,
        "Roles": [
            "Admin"
        ]
    }
}

merge(@.PersonalInfo, @.UserInfo)

{
    "FirstName": "John",
    "LastName": "Doe",
    "Age": 30,
    "Enabled": false,
    "Roles": [
        "User"
    ]
}

merge(@.PersonalInfo, @.UserInfo, @.NewUserInfo)

{
    "FirstName": "John",
    "LastName": "Doe",
    "Age": 30,
    "Enabled": true,
    "Roles": [
        "User",
        "Admin"
    ]
}

multiply

number multiply(number $left, number $right)

Multiplies $left with $right.

numbered_props_to_array

array numbered_props_to_array(json_object $object)

Get a new array of objects based on the properties from the JSON $object, where each name is considered to have an explicit (or implicit) ordering representation that defines its resulting position in the array.
This order index is taken from the name’s suffix, which is considered 0 when absent.
ie.: "Name" -> "Name", 0 / "NameIndex9" -> "NameIndex", 9.

{
    "a": "a",
    "b": "b",
    "c": "c"
}

[
    {
        "a": "a",
        "b": "b",
        "c": "c"
    }
]

{
    "a": "0",
    "b1": "b",
    "c2": "c2",
    "c1": "c",
    "a2": "a2"
}

[
    {
        "a": "0"
    },
    {
        "b": "b",
        "c": "c"
    },
    {
        "c": "c2",
        "a": "a2"
    }
]

parent

json_object parent(any $entry)

Returns the first json object that is a parent of $entry.
If $entry has no object as an ancestor, null is returned.

replace

string replace(string $input, string $old, string $new)

Replace $old ocurrences in $input with $new.

safe_mode

safe_mode(input, &expression)

Use safe_mode function and stay on safe side if there is any exception in the transformation block send as “input” parameter.
The function changes the behavior of exceptions to return null and not result in an invalid transformation. 

safe_not_null

any safe_not_null(any $entry, &expressions[])

Similar to a COALESCE function, safe_not_null evaluates $entry against a set of expressions, returning on the first one that provides a non-null answer.
More specifically, $entry is used as input data, which would define the “scope” available for the evaluation of each expression (see example provided).
In the case of unsuccessful evaluation (i.e. all expressions evaluate to null or fail), it returns null.

Example:

{ "str": "Take this and not this" }

safe_not_null(@, &to_number(@.str, 'en-UK'), &substring(@.str, `0`, `9`), &has_value(@.str))

'Take this'

service

json_object service(string $service, string $operation, any $payload)

Fetches data from an external service by calling a Connected $Service‘s $operation with $payload.

For operations utilizing GET, $payload must be a flat key/value object.

split

json_object split(array $input, integer $count)

Splits $input into two arrays “first” and “last”, one with $count elements and the other with all the elements left.
If $count = 0, then “first” would contain all the elements in $input.
If $count > 0, then “first” would take only the first $count elements.
If $count < 0, then “last” would be the one to fill first.

split_on

array split_on(string $input, boolean $ignore_empty, args[]:string $separators)

Simliar to a string.Split in many programming languages, split_on breaks down the string $input into an array using the string separators provided as parameters, with the flag $ignore_empty defining whether “empty” strings are included (false) or not (true).

string_interpolate

string string_interpolate(string $input, array|object $parameters)

Similar to operations like format or print, interpolate replaces the positional tokens in $input with the $parameters given, matching by index (array) or property name (object).

substring

string substring(string $text, integer $index, integer $length)

Returns a substring of $text, starting at $index and up to $length characters or until the end of $text. If $text is null, the function will return null.
If $index is greater than the length of $text, the function will return an empty string.

subtract

number subtract(number $left, number $right)

Subtracts $right from $left.

take_or_default

array take_or_default(array $array, integer $count, any $default)

Takes the first $count elements from $array.
If the array is smaller, then $default will be used to pad the remaining elements.

template

string template(string $id, string $stage, any $inputData)

Generates a base64-encoded document based on the provided DocuMotor template $id, its $stage (or null if none), and $inputData.
This data does not have any specific restrictions to its shape: it canbe either a json_object, a simple value, or nothing at all.

to_datetime

datetime to_datetime(string $data, string $format, string $culture)

Converts a string to a standardized datetime object.
$format is expected as a datetime format string to use for parsing.
$culture should be a language culture name, based on ISO-639-1 (ie. ‘en-US‘, ‘es-ES‘).

to_dictionary

json_object to_dictionary(array $input, expr &key, expr &value)

Converts $array into an object. The value of each property in the object is an array with the results of $valueExpression allowing for multiple elements to have the same result in $keyExpression.

{
    "a": [
        {
            "key": "b",
            "value": 1
        },
        {
            "key": "c",
            "value": 2
        }
    ]
}

to_dictionary(a, &key, &{newValue:value})

{
    "b": [
        {
            "newValue": 1
        }
    ],
    "c": [
        {
            "newValue": 2
        }
    ]
}

to_number

number to_number(string|number $data, string $culture)

Converts a string to either an integer or a double depending on the format of the string.
$culture should be a language culture name, based on ISO-639-1 (ie. ‘en-US‘, ‘es-ES‘).
If $data is already a number, the number is returned.
If $data is not a string or number, then null is returned.