Map
Use the Map processor-type Function to manage input fields, that is, to include or exclude 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.
A screenshot of an example configuration in Map illustrates what it can do:
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 field name(s) in the Fields to exclude drop-down list.
Note!
String literals inside formulas should be inside double quotes ("). Single quotes are not unsuppported!
Map Fields
You can create new fields and modify existing ones, by doing the following:
- Enter the name of a new field, or the name of an existing field that you want to modify, in the Field name input field.
The names of the input fields, which are shown in the preview data, are available in the drop-down list. - 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 references to fields are made in the payload, interpolation syntax must be used: 'payload.value', which refers to the property of the payload. The mapper also supports calls to meta and state streams. 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 by the use of specific logic used by the Usage Engine Cloud Edition system. All entered expressions are handled in accordance 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.
Quotes Use
All entered strings must be used with double quotes ("), single quotes are not supported!
Functions include the following:
- Numeric: floor, ceil, min, max, round, modulo
- String: length, trim, lowercase, upperCase, slice, split
- Boolean: not
- Misc: length, Number, firstDefined, firstNonNull
Operators include the following:
- Numeric: +, -, *, /
- Boolean: and, or, <, <=, =, !=, =>, >
- Branching: if
Fields includes a list of all input fields.
Constants
These 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 |
|---|---|
| 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 arguments that are accepted are the following:
- 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 |
|---|---|
| upperCase(s) | convert input string s to upper case |
| lowerCase(s) | convert input string s to lower case |
| trim(s) | remove leading and trailing spaces from input string s |
| length(s) | gives the length of input string s |
| x + y | concatenate strings x and y |
| slice(x, y) | get the substring of x, starting at index y (y = 0 is first character) |
| slice(x, y, z) | get 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 |
|---|---|
| length(x) | gives the length of x |
| slice(x, y) | get the slice of x, starting at index y (y = 0 is first character). |
| slice(x, y, z) | get 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 |
|---|---|
| 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 |
|---|---|
| firstDefined(x, …) | gives the leftmost value that is defined (that is, not equal to |
| firstNonNull(x, …) | gives the leftmost value that is defined and not |
| foo | lookup value of input field |
| foo.bar | lookup value of field |
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