Configuring Jexl operators

Many lenses allow one to write a Jexl script as part of their configuration. Jexl is a friendly language offering a number of operators which can be applied to transform data (typically the payload fields ) or do comparison, and so on.

Here are a selection, there are further details at the Jexl GitHub page.

Operators.

Use these operators to perform mathematical operations on values

Operation Symbol Example

Negate

!

!true ⇒ false

Add/Concat

+

3 + 4 ⇒ 7

Subtract

-

4 - 3 ⇒ 1

Multiply

*

3 * 8 ⇒ 24

Divide

/

15 / 4 ⇒ 3.75

Divide and Floor

//

15 // 4 ⇒ 3

Modulus

%

23 % 2 ⇒ 1

Power of

^

2^3 ⇒ 8

Logical AND

&&

true && true ⇒ true

Logical OR

`+

Comparisons.

Use these expressions to compare two values, the Boolean results can be used for, for example filtering.

Operation Symbol Example

Equal

==

1 == 2 ⇒ false

Not Equal

!=

1 != 2 ⇒ true

Greater Than

>

2 > 3 ⇒ false

Greater Than or Equal

>=

3 >= 3 ⇒ true

Less Than

<

2 < 3 ⇒ true

Less Than or Equal

<=

2 ⇐ 4 ⇒ true

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}
  ],
  adult: 21
}
Example Result

users[.last == 'Jones']

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

users[.age < adult]

[\{ 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 the val does not need to be added in the () after the function name. In some cases, this value is all that is 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

split(val, delimiter[, limit)]

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

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

endsWith(val, substring[, length)]

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.

startsWith(val, substring[, position)]

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.

indexOf(val, substring[, length)]

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)

payload.name | upper

Returns val in upper case.

lower(val)

payload.name | lower

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)

payload.range | round

Returns val rounded to the nearest integer.

trunc(val)

payload.range | trunc

Returns the integer part of val.

sqrt(val)

payload.range | sqrt

Returns √val.

sign(val)

payload.range | sign

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

ceil(val)

payload.price | ceil

Returns the nearest integer greater than val

floor(val)

payload.price | floor

Returns the nearest integer less than val

abs(val)

payload.temperature_change | abs

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

exp(val)

payload.difference | exp

Returns ℯval

log(val)

payload.difference | log

Returns the natural logarithm of val, for example ln(val)

random(val)

payload.range | random

Returns val multiplied by a floating-point, pseudo-random number between 0 (inclusive) and 1 (exclusive).