Articles in this section

Data Transformation Supported Functions

This article outlines the JMESPath functions supported by Templafy's External Data Source Transformation.

  Prerequisites

  • Admin/owner access to the Templafy tenant.
  • Data Connector and Data Transformation modules enabled.
  • External Data Source configured.

Supported Functions

These functions are part of the JMESPath community library in addition to some custom Templafy functions:

 

abs

Returns the absolute value of the provided number argument. Below the syntax:

abs(number)

Example 1: abs with a positive input

Input Expression Output
{"NumberValue": 10}

Example 2: abs with a negative input

Input Expression Output
{"NumberValue": -5}

avg

Returns the average of the elements in a provided array. Values in the array must be numbers. Below the syntax:

avg(array[number])

Example 1: avg with input as an array

Input Expression Output
{"NumberArray": [2,4,30]}

Example 2: avg with input as an object

Input Expression Output
{"Num_A": 2,"Num_B": 4, "Num_C": 30}

ceil

Returns the next highest integer value by rounding up a decimal number. Below the syntax:

ceil(number)

Example 1: ceil on a number with one digit

Input Expression Output
{"Number": 6.7}

Example 2: ceil on a number with two digits

Input Expression Output
{"Number": 3.24}

contains

Returns true if the subject (array or string) contains the provided search value. Returns false if not.

If searching an array, the function returns true if the search is equal to one of the elements. Below the syntax:

contains(arrayOrString, search_value)

Example 1: contains on an object

Input Expression Output
{"EmployeeNotes": "Steven was promoted to sales manager in March. 
Mr. Buchanan has completed the courses Successful Telemarketing
and International Sales Management."}

Example 2: contains with an existent result on an array of objects

Input Expression Output
{"OrderDetails": [
  {
  "OrderID": 1234,
  "ProductID": "11"
  },
{
  "OrderID": 1248,
  "ProductID": "42"
  }
 ]}

Example 3: contains on a non-existent result on an array of objects

Input Expression Output
{"OrderDetails": [
  {
  "OrderID": 1234,
  "ProductID": "11"
  },
{
  "OrderID": 1248,
  "ProductID": "42"
  }
 ]}

ends_with

Returns true if the subject ends with the specified string, otherwise returns false. Below the syntax:

ends_with(Subject_string, Search_string)

Example 1: end_with yielding to a result

Input Expression Output
{"Title": "Sales Manager"}

Example 2: end_with not yielding to a result

Input Expression Output
{"Title": "Manager Assistant"}

find_first

Returns the zero-based index of the first occurrence where the searched substring appears in the subject (or null if it does not appear). Start and End parameters are optional and allow for restricting the index range in which the substring must be found. If omitted, start will default to 0, and end will default to length(subject)-1, which is the end of the subject string. Below the syntax:

find_first(Subject_string, Substring, Start, End)

Example 1: find_first with one match

Input Expression Output
{"Location": "201-Office-New York City"}

Example 2: find_first with multiple matches

Input Expression Output
{"ProdList": "AB|CD|EF|GH"}

Example 3: find_first with multiple matches and with a start parameter

Input Expression Output
{"ProdList": "AB|CD|EF|GH"}

Example 4: find_first with a start and end parameters

Input Expression Output
{"ProdList": "AB|CD|EF|GH"}

Example 5: find_first with a start and end parameters not yielding to a result

Input Expression Output
{"ProdList": "AB|CD|EF|GH"}

find_last

Returns the zero-based index of the last occurrence where the searched substring appears in the subject (or null if it does not appear). Start and End parameters are optional and allow for restricting the index range in which the substring must be found. If omitted, start will default to 0, and end will default to length(subject)-1, which is the end of the subject string. Below the syntax:

find_last(Subject_string, Substring, Start, End)

Example 1: find_last with one match

Input Expression Output
{"Location": "201-Office-New York City"}

Example 2: find_last with multiple matches

Input Expression Output
{"ProdList": "AB|CD|EF|GH"}

Example 3: find_last with multiple matches, start and end parameters

Input Expression Output
{"ProdList": "AB|CD|EF|GH"}

Example 4: find_last with start and end parameters not yielding to a result

Input Expression Output
{"ProdList": "AB|CD|EF|GH"}

floor

Returns the next lowest integer value by rounding down a decimal number.

Syntax

floor(number)

Example 1: floor on a number with one digit

Input Expression Output
{"Number": 6.7}

Example 2: floor on a number with two digits

Input Expression Output
{"Number": 3.24}

format

Custom Templafy function.

Formats the provided number or datetime value into a string following the defined format and optional culture parameters. 

For numbers, format strings are defined here.

For datetime values, format strings are defined here.

Culture is a language culture name defined by ISO-63901. If the culture parameter is omitted, then the invariant culture is used. Below the syntax:

format(number, format, culture) or format(datetime, format, culture)

Example 1: format with en-US culture

Input Expression Output
{"UnitPrice": 18.2000}

Example 2: format with es-ES culture

Input Expression Output
{"UnitPrice": 18.2000}

Example 3: format with no culture set

Input Expression Output
{"UnitPrice": 18.2000}

Example 4: format with specific datetime formatting

Input Expression Output
{"Date": "02-19-2021"}

from_items

Returns an object from a provided array of key value pairs. Below the syntax:

from_items(array[])

Example

Input Expression Output
{"Orders": [["ProdA",5],["ProdB",2],["ProdC",10]]}

group_by

Groups an array of objects using the provided expression parameter as the grouping key. The result is an object whose keys are the unique set of strings from the grouping parameter, and the values are an array of objects matching the specified group criteria. 

Any object from the input that does not match the group criteria will not be included in the output. Below the syntax:

group_by(array[object], expression)

Example

Input Expression Output
{"orders": [
{
    "OrderID": 1234,
  "ProductID": "11"
   },
{
  "OrderID": 1248,
  "ProductID": "42"
  },
{
  "OrderID": 1253,
  "ProductID": "11"
  },
 ]}

items

Returns an array of key-value pairs for a provided input object. Each pair is returned as a two-item array where the first item is the key, and the second item is the value. Below the syntax:

items(object{})

Example

Input Expression Output
{"OrderAmt": {"ProdA": 5, "ProdB": 2, "ProdC": 10}}

join

Returns all elements of the specified array joined together using the provided argument as a separator between each. Below the syntax:

join(Separator, array[string])

Example 1: join with an array of strings

Input Expression Output
{"Products":["AB", "CD", "EF", "GH"]}

Example 2: join with an object as an input

Input Expression Output
{"FirstName": "Lisa", "LastName": "Crosby"} 

keys

Returns an array containing the keys of a provided object. 

Note: the keys associated with a provided object are inherently unordered. This means that keys will not be returned in any specific order. Below the syntax:

keys(object{})

Example 1: keys with an empty object

Input Expression Output
{"EmptyObject": {}}

Example 2: keys with an object

Input Expression Output
{"Products": {"AB": 2, "CD":5, "EF": 10}}

length

Returns the length of the given argument using the following types of rules:

  1. string: returns the number of code points in the string (this essentially means number of Unicode characters).
  2. array: returns the number of elements in the array.
  3. object: returns the number of key-value pairs in the object.

Below the syntax:

length(subject)

Example 1: length of a string

Input Expression Output
{"String": "This is a string!"}

Example 2: length of an array of strings

Input Expression Output
{"Products":["AB", "CD", "EF", "GH"]}

Example 3: length of an object

Input Expression Output
{"OrderAmt": {"ProdA": 5, "ProdB": 2, "ProdC": 10}}

Example 4: length of an array of objects

Input Expression Output
{"OrderDetails": [
  {
  "OrderID": 1234,
  "ProductID": "11"
  },
{
  "OrderID": 1248,
  "ProductID": "42"
  }
 ]}

lower

Returns the lowercase provided string. Below the syntax:

lower(string)

Example 1: lower of an all-caps string

Input Expression Output
{"String": "VALUE"}

Example 2: lower of a string with mix uppercase/lowercase characters

Input Expression Output
{"String": "User TYped string"}

map

Applies the specified expression to each element in the provided array. Below the syntax:

map(expression, array[])

Example

Input Expression Output
{"OrderDetails": [
  {
  "OrderID": 1234,
  "Price": 1400
  },
{
  "OrderID": 1248,
  "Price": 980
  },
{
  "OrderID": 1249,
  "OtherField": "value"
  }
 ]}

max

Returns the highest found number in the provided array argument. An empty array will return a value of null. Below the syntax:

max(array[number]) or max(array[string])

Example 1: max on an array of numbers

Input Expression Output
{"Numbers": [-2, 3.2, 1.01]}

Example 2: max an array of strings

Input Expression Output
{"Strings": ["a","b","c"]}

max_by

Returns the maximum element in a provided array using the defined expression as the comparison key.  Below the syntax:

max_by(array[elements], expression)

Example

Input Expression Output
{"OrderDetails": [
  {
  "OrderID": 1234,
  "Quantity": 5
  },
{
  "OrderID": 1248,
  "Quantity": 41
  },
{
  "OrderID": 1248,
  "Quantity": 27
  }
 ]}

merge

Returns one object with the defined objects merged. This function combines multiple objects into one where the first object is the base, and the subsequent objects override or add to the base object. Below the syntax:

merge(object1, object2,...)

Example 1: merge of two objects

Input Expression Output
{
"Object_one": {
"one": "a",
"two": "b"
},
"Object_two":{
"three": "c",
"four": "d"
}
}

Example 2: merge of three objects

Input Expression Output
{
"Object_one": {
"one": "a",
"two": "b"
},
"Object_two":{
"three": "c",
"four": "d"
},
"Object_three":{
"three": "override",
"five": "e"
}
}

min

Returns the lowest found number in the provided array. Below the syntax:

min(array[number]) or min(array[string])

Example 1: min on an array of numbers

Input Expression Output
{"Numbers": [-2, 3.2, 1.01]}

Example 2: min on an array of strings

Input Expression Output
{"Strings": ["a","b","c"]}

min_by

Returns the minimum element in a provided array using the defined expression as the comparison key. Below the syntax:

min_by(array[elements], expression)

Example

Input Expression Output
{"OrderDetails": [
  {
  "OrderID": 1234,
  "Quantity": 5
  },
{
  "OrderID": 1248,
  "Quantity": 41
  },
{
  "OrderID": 1248,
  "Quantity": 27
  }
 ]}

not_null

Returns the first argument that does not resolve to null. This function accepts one or more arguments and will evaluate them in order until a non-null argument is encountered. If all arguments values resolve to null, then a value of null is returned. Below the syntax:

not_null(argument1, argument2, ...)

Example 1: not_null not yielding to a result

Input Expression Output
{"a": null,
"b": null,
"c": "string",
"d": []}

Example 2: not_null yielding to a result

Input Expression Output
{"a": null,
"b": null,
"c": "string",
"d": []}

pad_left

Adds characters to the beginning of a specified string to return a string of at least the specified width. The optional pad string parameter specifies the character that will be added, but if not specified, a space will be used. Below the syntax:

pad_left(subject_string, width, pad_character)

Example 1: pad_left on a string with a width

Input Expression Output
{"a": "string"}

Example 2: pad_left on a string with a with and a pad_character resulting in adding characters

Input Expression Output
{"a": "string"}

Example 3: pad_left on a string with a with and a pad_character resulting in doing nothing

Input Expression Output
{"a": "string"}

pad_right

Adds characters to the end of a specified string to return a string of at least the specified width. The optional pad string parameter specifies the character that will be added, but if not specified, a space will be used. Below the syntax:

pad_right(subject_string, width, pad_character)

Example 1: pad_right on a string with a width

Input Expression Output
{"a": "string"}

Example 2: pad_right on a string with a with and a pad_character resulting in adding characters

Input Expression Output
{"a": "string"}

Example 3: pad_right on a string with a with and a pad_character resulting in doing nothing

Input Expression Output
{"a": "string"}

replace

Replaces the occurrences of the specified old substring with the defined new substring in a given subject string. 

If the count option parameter is added, it will determine how many occurrences of the old substring are to be replaced. If omitted, all instances will be replaced. Below the syntax:

replace(subject_string, old_substring, new_substring, count)

Example

Input Expression Output
{"Summary": "The SVP of Marketing, James, is in charge of all marketing efforts. 
James reports result to the CEO every quarter.
One of James's duties is social marketing."}

reverse

Reverses the order of the specified string or array. Below the syntax:

reverse(string) or reverse(array[])

Example 1: reverse on a string 

Input Expression Output
{"string": "AB|CD|EF"}

Example 2: reverse on an array

Input Expression Output
{"array": [1,2,3,4]}

sort

Returns a sorted list of elements in an array. The input array must be a list of strings or numbers. Below the syntax:

sort(array[number]) or sort(array[string])

Example 1: sort on an array of numbers

Input Expression Output
{"Numbers": [4, 7, -2, 0.1]}

Example 2: sort on an array of strings

Input Expression Output
{"Strings": ["Orange", "Banana", "Apple", "Grape"]}

sort_by

Sorts an array by the provided expression as the sort key. For each element of the array, the expression is evaluated, and the resulting value is used when sorting the elements. The result of the expression must be a number or a string. Below the syntax:

sort_by(array[elements], expression)

Example

Input Expression Output
{"people": [
{"name":"AB", "tenure": 2},
{"name":"CD", "tenure": 7},
{"name":"EF", "tenure": 1}
]}

split

Given a subject string, this function breaks up the string on occurrence of the provided search string and returns an array containing each partial string between occurrences of the search string.

The optional count parameter specifies the max number of split points in the string. If omitted, all instances of the search parameter are split. Below the syntax:

split(SubjectString, SearchString, Count)

Example 1: split of a string with a SearchString parameter

Input Expression Output
{"ProdList": "AB|CD|EF|GH"}

Example 2: split of a string with a SearchString and a count parameter

Input Expression Output
{"String": "red-blue-yellow-green-orange-purple"}

start_with

Returns true if the provided subject string starts with the specified prefix string, otherwise returns false. Below the syntax:

starts_with(SubjectString, prefix)

Example

Input Expression Output
{"String": "Value"}

sum

Returns the sum of the provided array. Below the syntax:

sum(array[number])

Example 1: sum on an array of numbers

Input Expression Output
{"Numbers": [1, 4, 20, 5]}

Example 2: sum on an array of objects

Input Expression Output
{"OrderDetails": [
  {
  "OrderID": 1234,
  "Quantity": 11
  },
{
  "OrderID": 1248,
  "Quantity": 42
  }
 ]}

to_array

Returns a one element array containing the passed argument. If the argument is already an array, the passed in value will be returned. Below the syntax:

to_array(argument)

Example 1: to_array on a string

Input Expression Output
{"String": "String Value"}

Example 2: to_array on a number

Input Expression Output
{"Number": 20}

to_datetime

Returns a standardized datetime object from a provided string. The format parameter is expected as a datetime format string to use for parsing the provided string following this standard. The culture parameter is a language culture name to define the output date format based on ISO-639-1. Below the syntax:

to_datetime(string, format, culture)

Example

Input Expression Output
{"DateString": "3 Feb 2021"}

to_number

Returns the parsed number of an input string. If a number is passed, that number value will be returned. Any other data types passed will return null. Below the syntax:

to_number(argument)

Example 1: to_number on a numeric string

Input Expression Output
{"OrderQuantity": "47"}

Example 2: to_number on a non-numeric string

Input Expression Output
{"OrderQuantity": "47 units"}

to_string

Returns the JSON encoded value of the object. If a string is provided, it will return the passed as a string value. Below the syntax:

to_string(argument)

Example 1: to_string on a number

Input Expression Output
{"OrderID": 1234}

Example 2: to_string on null

Input Expression Output
{"ShippingID": null}

Example 3: to_string on an array

Input Expression Output
{"Numbers": [1, 4, 20, 5]}

trim

Removes the leading and trailing characters from a given subject string found in the optional characters parameter. If this is not present, whitespace characters are removed from the subject string. Below the syntax:

trim(SubjectString, characters)

Example 1: trim on a string without character parameter

Input Expression Output
{"Email": "email@example.com  "}

Example 2: trim on a string with a character parameter

Input Expression Output
{"String": "subject string"}

trim_left

Removes the leading characters from a given subject string found in the optional characters parameter. If the characters parameter is not present, whitespace characters are removed from the subject string. Below the syntax:

trim_left(SubjectString, characters)

Example 1: trim_left on a string without character parameter

Input Expression Output
{"Email": "email@example.com "}

Example 2: trim_left on a string with a character parameter

Input Expression Output
{"String": "subject string"}

trim_right

Removes the trailing characters from a given subject string found in the optional characters parameter. If the characters parameter is not present, whitespace characters are removed from the subject string. Below the syntax:

trim_right(SubjectString, characters)

Example 1: trim_right on a string without character parameter

Input Expression Output
{"Email": " name@example.com  "}

Example 2: trim_right on a string with a character parameter

Input Expression Output
{"String": "subject string"}

type

Returns the JavaScript data type of the provided argument as a string value. Possible return values are:

  • number
  • string
  • boolean
  • array
  • object
  • null

Below the syntax:

type(argument)

Example 1: type on a boolean

Input Expression Output
{"subject": false}

Example 2: type on a string

Input Expression Output
{"subject": "customer name"}

Example 3: type on an array

Input Expression Output
{"subject": ["abc":123, "def":456]}

upper

Returns the uppercase subject string. Below the syntax:

upper(SubjectString)

Example

Input Expression Output
{"String": "string value"}

values

Returns the values of the provided object. Below the syntax:

values(object{})

  Note

The values associated with a provided object are inherently unordered. This means that values will not be returned in any specific order.

Example

Input Expression Output
{"Products": {"AB": 2, "CD":5, "EF": 10}}

zip

Accepts one or more arrays as arguments and returns an array of arrays in which the i-th array contains the i-th element from each of the argument arrays. The returned array is truncated to the length of the shortest argument array. Below the syntax:

zip(array[any], array[any], ...)

Example 1: zip on two arrays of numbers

Input Expression Output
{"array_one":[1,2,3],
 "array_two": [4,5,6]}

Example 2: zip on two arrays of strings

Input Expression Output
{"A_Products": ["AB": 2, "CD":5, "EF": 10],

 "B_Products": ["GH": 7, "IJ": 4, "KL": 12, "MN":42]}

Example 3: type on an array of objects

Input Expression Output
{"OrderDetails": [
  {
  "OrderID": 1234,
  "Quantity": 11
  },
{
  "OrderID": 1248,
  "Quantity": 42
  }
 ]}
External data sources JMESPath admin_role
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.