Map

You can use the Map processor function to manage input fields by including or excluding fields forwarded by the function. The input fields can be modified using formulas. New fields are created using formulas, based on input fields, or by adding new information.

The Map function has two main features:

Manage input fields, to keep all input fields in the output, or to exclude all or some input fields from the output.
Map fields, to modify fields using formulas. New fields can be created, based on input fields and formulas.

Map function configuration with Field name dropdown expanded

Manage input fields

You have three options for handling how input fields are sent to the output:

Keep all - Sends all fields to the output.
Exclude all - All fields are excluded from the output.
Exclude some - Select the fields to be excluded from the output by selecting them in the Fields to exclude drop-down list, or type the field name into the Add field box and click the + button.

Note!

String literals inside formulas should be inside double quotes ("). Single quotes are not supported.

Map fields

To create new fields or modify existing fields:

Enter the name of a new field, or the name of an existing field that you want to modify, in Enter field name. Select the field name from the drop-down list or type the field name into the Add field box and click the + button.
Enter a formula in the Formula input field.
Once you click into Formula, the Formulas to select and Fields drop-down lists appear.
Add Functions, Operations, or Fields as needed for your specific field transformation.
Click Preview to view the resulting output.

When you are referencing fields in the payload, you must use interpolation syntax: 'payload.value', which refers to the property of the payload. The Map function also supports calls to meta and state streams. The expected map fields entry syntax is the following:

$(payload.value) – Turns the content into a string.
@(payload.value) – Keeps the data type of the content.

Interpolation is handled via specific logic used by Usage Engine. All entered expressions are handled according to the built-in rules of the service. For more information, see Variable insertion.

Formulas

The formulas are divided into two parts: Formulas to select and Fields. Formulas to select contains Functions and Operators.

Functions

Functions include:

Numeric: floor, ceil, min, max, round, modulo
String: length, trim, lowercase, upperCase, slice, split
Boolean: not
Misc: length, Number, firstDefined, firstNonNull

Operators

Operators include:

Numeric: +, -, *, /
Boolean: and, or, <, <=, =, !=, =>, >
Branching: if

Fields

Fields include a list of all input fields.

Constants

The following constants are available:

undefined
null
true
false

Data literals

1.23 numbers (supporting decimal notation)

"Hello world" string literals are quoted in double quotes

Branching

if condition then x else y gives x if condition is true, and y otherwise

Numeric functions and operations

Operation	Description

Operation	Description
min(x, …)	outputs smallest of the given input values
max(x, …)	outputs biggest of the given input values
round(x)	round to the nearest integer
round (x,y)	round to the nearest decimal place indicated in y
floor(x)	rounds the input value to the smallest integer
ceil(x)	rounds the input value to the biggest integer
modulo(x, y)	outputs x modulo y
x + y	numeric addition
x - y	numeric subtraction
x * y	numeric multiplication
x / y	numeric division

Round function options

The round function uses the following syntax: ROUND(number, num_digits). The following arguments are accepted:

number — This is a required parameter. Enter the number to be rounded off.
num_digits — This is an optional parameter. The number of digits to which the number argument is to be processed.

String functions and operations

Operation	Description

Operation	Description
upperCase(s)	Converts the input string(s) to upper case.
lowerCase(s)	Converts the input string(s) to lowercase.
trim(s)	Removes leading and trailing spaces from the input string(s).
length(s)	Gives the length of the input string(s).
x + y	Concatenates strings x and y.
slice(x, y)	Gets the substring of x, starting at index y (y = 0 is first character).
slice(x, y, z)	Gets a slice of z characters from the string x, starting at index y (iy= 0 is first character).
split(xx, yy)	Allows for strings to be split by a specific substring into an array. Example: split(“foo.bar”, “.”) will generate an array containing [“foo”,“bar”]

Array operations

Operation	Function

Operation	Function
length(x)	Gives the length of x.
slice(x, y)	Gets the slice of x, starting at index y (y = 0 is first character).
slice(x, y, z)	Gets a slice of z elements from the array x, starting at index y (y = 0 is first character).

Logical (boolean) functions and operations

Operation	Description

Operation	Description
not(x)	Negation of x.
x and y true	If both x and y are true.
x = y true	If x equals y.
x != y true	If x is not equal to y.
x < y true	If x is strictly smaller than y.
x <= y true	If x is smaller than or equal to y.
x > y true	If x is strictly bigger than y.
x => y true	If x is bigger than or equal to y.

Note!

Only = and != comparisons will work for arrays and objects.

The character pairs !=, <=, and => are automatically converted to the Unicode symbols ≠, ≤, ≥.

General operations

Function	Description

Function	Description
firstDefined(x, …)	Gives the leftmost value that is defined (that is, not equal to `undefined`).
firstNonNull(x, …)	Gives the leftmost value that is defined and not `null`.
foo	Lookup the value of input field `foo`.
foo.bar	Lookup the value of field `bar` nested inside input `foo`.

Conversion operations

Number(x) converts x to a number (if x is a string representing a number)

"" + x will convert a number x to a string and add it to the corresponding string