Functions

Using functions, you can perform various operations on data to get desired values in your Processes and State Diagrams.

Basic functions in use

Below are the basic functions for configuring nodes in your Processes and State Diagrams.

$.math()

With the $.math() function, you can perform mathematical operations such as addition, subtraction, multiplication, and division.
For example:

• To calculate the 1+1 result, use:

  $.math(1+1)
  

• To calculate the sum of the specified parameter’s value + 10, use:

  $.math({{parameter_name}}+10)
  

• To calculate the difference between two parameters, use:

  $.math({{parameter_name1}}-{{parameter_name2}})
  

$.random(N)

The $.random(N) function returns a random number depending on the specified N, where:

• .random(0): always returns 0.
• .random(N), N>1: returns a positive random number.
• $.random(N), N<0: returns a negative random number.

$.sha1_hex

The $.sha1_hex(content) function returns sha1 in hex from a constant or task parameter if it is specified in the {{parameter_name}} format. For example, to get the sha1 in hex for the constant 100, use:

$.sha1_hex(100)

$.md5_hex

The $.md5_hex(content) function returns md5 hash in hex generated from a constant or task parameter if it is specified in the {{parameter_name}} format. For example, to get the md5 in hex for the constant 100, use:

$.md5_hex(100)

$.base64_encode

The $.base64_encode(content) function converts a constant or a task parameter in the base64 format if it is specified in the {{parameter_name}} format, where content means a constant or {{parameter_name}}.

$.unixtime()

The $.unixtime() function returns the current time in Unix Time in GMT 0. You can use arithmetic arguments to adjust the current time value.
For example:

• To return the current time in Unix Time, use:

  $.unixtime()
  

• To return Unix Time for current time + 60 min, use:

  $.unixtime(%y-%m-%d %h:%i+60:%s)
  

• To return Unix Time for the current date with the set time 02:00:00, use:

  $.unixtime(%y-%m-%d 02:00:00)
  

$.date(%y-%m-%d %h:%i:%s)

The $.date(%y-%m-%d %h:%i:%s) function converts a date in the day and time format. You can use arithmetic arguments. For example:

• To return the current date and time in the YYYY-MM-DD HH:MM:SS format, use:

  $.date(%y-%m-%d %h:%i:%s)
  

• To add +1 day to the returned date in the YYYY-MM-DD HH:MM:SS format, use:

  $.date(%y-%m-%d+1 %h:%i:%s)
  

$.unixtime().tz

With the $.unixtime().tz function, you can get the current time of a specific timezone. For example, to return the current time in Kyiv (Eastern European time zone) in the Unix Time format, use:

$.unixtime().tz('Europe/Kiev')

$.map() and $.filter()

You can use the $.map() and $.filter() Erlang functions in the Set Parameters node in a similar way to how you use the .math() and .unixtime() functions. The use of the $.map() and $.filter() functions aims at making responses from external APIs more lightweight and tasks smaller after passing through the API Call nodes.

The $.map() and $.filter() functions are used in the following constructions:

• $.map(fun(Item) -> end, arr)
• $.filter(fun(Item) -> end, value)
  where:
• fun is the supported function.
• Item is an arbitrary value and the Item value must be capitalized.
• arr is a parameter of an input task, which contains an array.
• value is a single value.

A function body follows the arrow ->, in which you can write allowed expressions using simple operations from ALLOWED_INF_EXPRS (expressions allowed in $.map() and $.filter() functions), and some functions from ALLOWED_EXT_FUNS (allowed in $.map() and $.filter() functions).

ALLOWED_EXT_FUNS

  {proplists,'_','_'},
  {base64,'_','_'},
  
  {binary, split, '_'},
  {binary, replace, '_'},

  {eutils, get_value, 2},
  {eutils, from_json, '_'},
  {eutils, to_json, 1},

  {erlang,binary_to_float,1},
  {erlang,binary_to_integer,1},

  {erlang,integer_to_binary,1},
  {erlang,integer_to_binary,2},

  {erlang,round,1},

  {erlang, is_integer, 1},
  {erlang, is_binary, 1},
  {erlang, is_list, 1},
  {erlang, is_float, 1},
  {erlang, is_boolean, 1},
  {erlang, is_number, 1},

  {erlang, hd, 1},
  {erlang, tl, 1}

proplists - let's take a closer look at the get_value and delete functions. For example, we need to get a value from the test and increase it by 1. To do this, we'll use the following code:

Test = proplists:get_value(<<"test">>, Item),
[{<<"test">>, Test + 1} | proplists:delete(<<"test">>, Item)]

In this example, we've written the "test" value to the Test variable. As the Item is a list, we added a new test variable with the "Test +1" value to the head of the list and removed the old test variable from the Item. Note that we'll have both test variables processed in the code without removing the old variable.

base64 - note the use of encode and decode functions; they are used the same way as in other languages:

Test = proplists:get_value(<<"test">>, Item),
[{<<"base64">>, base64:encode(Test)} | Item]

Analogous to the previous example, we've got a value from the test and written it to the Test variable. Then, we updated the base64 value with the new base64 value and added it to the Item.

binary - split and replace functions are available. They allow splitting a string and replacing it with another string.

eutils - internal Corezoid library. It offers the following functions:

• get_value - similar to proplists and serves the same purpose;
• from_json - converts JSON to list;
• to_json - converts list to JSON.

For example, if your task contains the following data:

[{"test":"{\"a\":1}"}, {"test":"{\"a\":2}"}, {"test":"{\"a\":4}"}]. 

you can use the following code:

Test0 = eutils:get_value(<<"test">>, Item),
Test1 = eutils:from_json(Test0),
[{<<"a">>, eutils:get_value(<<"a">>, Test1)} | Item]

The code takes the test value, converts the string to a list, and assigns the Test1 the following value

[
{<<"a">>, 1}
]

We take the "a" value and remove it from the test, then we add it to the Item.

erlang - only the functions for converting binary to number and vice versa are available.

ALLOWED_INF_EXPRS

 '+',
  '-',
  '*',
  '/',
  'bnot',
  'div',
  'rem',
  'band',
  'bor',
  'bxor',
  'bsl',
  'bsr',
  'not',
  'and',
  'or',
  'xor',
  'andalso',
  'orelse',
  '==',
  '/=',
  '=<',
  '<',
  '>=',
  '>',
  '=:=',
  '=/=',
  '++',
  '--'

Examples

Multiplying all array elements by a specified value ($.map() function)

1. In the Set Parameters node input, take a task containing the a array:

   "a": [1,2,3]
   

2. In the Set Parameters node, enter the $.map() function :

   "b": "$.map(fun(Item) -> Item*2 end, {{a}})"
   

Each а array element is multiplied by 2, and the results are written to the b array:

"b": "[2,4,6]"

Filtering out uneven numbers and writing even numbers ($.filter() function)

1. Set the b task:

   [1,2,3,4,5,6,7,8,9,10,11,12,13,14]
   

2. In the Set Parameters node, write the $.filter() function:

   "b1": "$.filter(fun(Item) when Item rem 2 < 1 -> true; (_) -> false end, {{b}})"
   

The response is:

"b1":[2,4,6,8,10,12,14]

Conversion of an array with objects containing the "fieldName" key into an array that includes only values of this key:

1. Generic method:

   $.map(fun(E) -> FieldName = eutils:get_value(<<"fieldName">>, E), FieldName end, {{arr}})
   

2. Simplified method:

   $.map(fun(E) -> eutils:get_value(<<"fieldName">>, E) end, {{arr}})
   

Conversion reverse to the one in the previous example - an array of simple primitives is conversed to an object array:

1. By declaring a key-value pairs collection:

   $.map(fun(Value) -> #{<<"fieldName1">> => Value, <<"fieldName2">> => Value} end, {{arr}})
   

2. By declaring a tuples collection:

   $.map(fun(Value) -> [{<<"fieldName1">>, Value}, {<<"fieldName2">>, Value}] end, {{arr}})