# Configuring Jexl operators

You can write a Jexl script as part of the configuration of many lenses. Jexl is a friendly language offering a number of operators which can be applied to transform data (typically the payload fields ) or do comparison.

The following is a selection, for more information refer to the Jexl GitHub page.

Operators

Use these operators to perform mathematical operations on values:

Operation Symbol Example

Negate

!

!truefalse

+

3 + 47

Subtract

-

4 - 31

Multiply

*

3 * 824

Divide

/

15 / 43.75

Divide and Floor

//

15 // 43

Modulus

%

23 % 21

Power of

^

2^38

Logical AND

&&

true && truetrue

Logical OR

`+

Comparisons

Use these expressions to compare two values and get a Boolean result. For example, the results can be used for filtering.

Operation Symbol Example

Equal

==

1 == 2false

Not Equal

!=

1 != 2true

Greater Than

>

2 > 3false

Greater Than or Equal

>=

3 >= 3true

Less Than

<

2 < 3true

Less Than or Equal

<=

2 ⇐ 4true

Element in array or string

in

"cat" in ["cat", "dog", "mouse"]true

Conditional operators

Conditional operators return the second or third expression based on the result of the first expression. If the first expression ("Bob" in ["Bob", "Mary"] below) return true, "Yes" is returned. If it returns false, "No" is returned.

Example Result

"Bob" in ["Bob", "Mary"] ? "Yes" : "No"

"Yes"

Identifiers

Access variables in the payload with dot notation or by using brackets For example:

{
name: {
first: 'John'
last: 'Smith'
},
age: 55,
colleagues: [
'Mary',
'Bob',
'Ted'
],
teammate: 2
}
Example Result

name.first

"John"

colleagues[teammate]

"Ted"

name['la' + 'st']

"Smith"

Collection filtering

Arrays of objects (Collections) can be filtered by including a filter expression in brackets. Properties of each collection can be referenced by prefixing them with a leading dot. The result is an array of objects for which the filter returns a truthy value.

{
users: [
{ first: 'John', last: 'Smith', age: 20},
{ first: 'Mary', last: 'Jones', age: 46},
{ first: 'Ted', last: 'Cotter', age: 16},
{ first: 'Bob', last: 'White', age: 66}
],
}
Example Result

users[.last == 'Jones']

[\{ first: 'Mary', last: 'Jones', age: 46}]

[\{ first: 'John', last: 'Smith', age: 20}, first: 'Ted', last: 'Cotter', age: 16}]

users[first == 'John'].last

"Smith"

Lens expression functions

In addition to the general Jexl parsing functionality, Siren Investigate also exposes a number of JavaScript-like functions for use in lens expressions. Payload values, or the results from earlier parsing, are piped into the function using the | character. These values become the val parameter for the functions below meaning that the val does not need to be added in the () after the function name. In some cases, this value is all that’s needed by the function and some functions require extra parameters.

Some functions require string inputs and some require integer or floating-point inputs

Table 1. String lens expressions
Function Example Explanation

payload.IP | split('.', 3)

Splits an IP address by the '.' and returns the first 3 entries as an array.

payload.name | endsWith('smith', 10)

Returns true if val ends with substring, if length is added, that number of characters from the beginning of val is checked.

payload.name | startsWith('smith', 10)

Returns true if val begins with substring, if position is added, the substring from that position to the end of val is checked.

payload.name | indexOf('smith', 10)

Returns the position of the first character of substring if val contains substring, if length is added, val is checked from that position.

upper(val)

Returns val in upper case.

lower(val)

Returns val in lower case.

substring(val, start, end)

payload.name | substring(5, 10)

Returns the string within val found between start and end.

replace(val, substring, newSubString)

payload.name | replace('smith', 'jones')

Replaces substring with newSubString in val.

Table 2. Number lens expressions
Function Example Explanation

round(val)

Returns val rounded to the nearest integer.

trunc(val)

Returns the integer part of val.

sqrt(val)

Returns √val.

sign(val)

Returns 1 if val is positive, -1 if val is negative or 0 if val equals 0.

ceil(val)

Returns the nearest integer greater than val

floor(val)

Returns the nearest integer less than val

abs(val)

Returns the absolute value for a Number or 0 if the number is null

exp(val)

Returns ℯval

log(val)