Functions
Expression Language (EL) also supports a series of pre-defined functions for more advanced operations upon variables and primitive values. These functions can be found in the rules builder and in any platform expression builder. The table below contains the full list of all supported functions as well as their descriptions.
Numeric Functions
| EL Expression | Description | Usage | Result |
|---|---|---|---|
| n:abs(Number) | Returns the absolute value of the parameter Number | ${n:abs(23-47)} | 24 |
| n:number_formatted(Number, Decimal Places) | Returns Number formatted according to the Decimal Places parameter | ${n:number_formatted(23.76653, 2)} | 23.77 |
| n:round(Number, Decimal Places) | Returns Number rounded to the specified number of decimal places | ${n:round( 23.76653,-1)} | 20.0 |
| n:sqrt(Number) | Returns the square root of Number | ${n:sqrt(9)} | 3 |
| n:to_integer(Object) | Returns Integer, corresponding to input (rounded) Object | ${n:to_integer(23.76653)} | 24 |
| n:to_integer_trunc(Object) | Returns Integer, corresponding to input Object | ${ n:to_integer_trunc(23.76655)} | 23 |
| n:to_number(Object) | Returns Number, corresponding to input object. In most of cases we use it to convert String to Number | ${n:to_number(‘12’)} | 12.0 |
| n:to_string(Object) | Returns string representation of input Object. | ${n:to_string(12)} | 12 (already an object of String type) |
| n:max(Integer, Integer) or n:max(Number, Number) | Returns the maximum of two integers or two numbers | ${n:max(55, 22)} | 55 |
| n:min(Integer, Integer) or n:min(Number, Number) | Returns the minimum of two integers or two numbers | ${n:min(55, 22)} | 22 |
| n:decimal_format(Format String, Value) | Returns value after being formatted using the supplied Format String. The Value parameter can be Text, Integer or Number | ${n:decimal_format('#,##0.00','1234.5')} | 1,234.50 |
Trigonometric Functions
A set of angle-based functions.
| EL Expression | Description | Usage | Result |
|---|---|---|---|
| n:arccos(Angle) | Returns the arccosine of the parameter Angle | ${n:arccos(0)} | 1 |
| n:arcsin(Angle) | Returns the arcsine of the parameter Angle | ${n:arcsin(90)} | 1 |
| n:arctan(Angle) | Returns the arctangent of the parameter Angle | ${n:arctan(90)} | 1 |
| n:cos(Angle) | Returns the cosine of the parameterAngle | ${n:cos(0) | 1 |
| n:tan(Angle) | Returns the tangent of the parameterAngle | ${n:tan(45)} | 1 |
| n:sin(Angle) | Returns the sine of the parameterAngle | ${n:sin(90)} | 1 |
String Functions
The following functions deal primarily with modification and testing of text strings.
| EL Expression | Description | Usage | Result |
|---|---|---|---|
| n:concat(Value, Value, Value) | Returns String of concatenated objects | ${n:concat( '(Update:',_local.count,")")} | (Update:52) |
| n:empty_string(String) | Returns true if String is null or empty, false otherwise | ${n:empty_string(param.Add)} | True when param Variable is empty |
| n:char_new_line() | Returns a new line character | ${Value 1} ${n:char_new_line()} ${Value2} | Value1 Value2 |
| n:compare(Comparable Object 1, Comparable Object 2) | Returns 1 if Comparable Object 1 > Comparable Object 2, -1 if Comparable Object 1 < Comparable Object 2, and 0 otherwise. Objects may be of type Integer, Long, Double, Number, Calendar, or Address. In case of addresses the function returns 0 when addresses are the same and -1 otherwise | ${n:compare(1,2)} ${n:compare(2,1)} ${n:compare(_local.date1,_local.date2)} | -1 1 -1 (if _local.date1 is earlier than _local.date2), 1 ((if _local.date2 is earlier than _local.date1)) 0(if both dates are the same) |
Weather Functions
The following functions are used to call weather conditions from external services.
| EL Expression | Description | Usage | Result |
|---|---|---|---|
| nx: noaa_observation(Location) | Returns a weather information map {station, location, temperatureF, temperatureC, humidity, pressureIn, windDirection, windSpeedMph, dewpointF, dewpointC, visibilityM, weather} | ${nx:noaa_observation(object.location).weather} ${nx:noaa_observation(object.location).temperatureC} ${nx:noaa_observation(object.location).temperatureF} | Partly Cloudy 16 61 *Results depend on object.location value |
Time Functions
A critical piece of any monitoring application is time based activity and calculation, the following functions deal with calculating time difference and converting time and calenser functions into usable formats.
For many of the Usage examples, ‘message.time’ is used and set at 20th February 2017 2:33:32AM.
More detail on date and time formats can be found here: Java Simple Date Format
| EL Expression | Description | Usage | Result |
|---|---|---|---|
| n:time_add(Calendar, Seconds) | Adds Seconds to the provided datetime Calendar | ${n:time_add(message.time, 110)} | 20 Feb 2017 2:35:22AM |
| n:time_add_days(Calendar, Days) | Adds Days to the provided datetime Calendar | ${n:time_add_days(message.time,9)} | 2/1/2017 2:33AM |
| n:time_add_months(Calendar, Months) | Adds Months to the provided datetime Calendar | ${n:time_add_days(message.time,2)} | 4/20/2017 02:33 |
| n:time_clone(Calendar) | Returns a copy of the supplied datetime Calendar | ${n:time_clone(message.time)} You should use such expression in Set Variable action. Newly created variable will be initialized as message.time value. | 20 Feb 2017 2:33:32AM |
| n:time_range(Calendar,Calendar) | Returns time interval for search operations FromDate and ToDate. | ${n:time_range(n:now(), message.time)} Required for Find, Select and Calculate Actions. Returns WHERE condition with BETWEEN operator. You can also use system constants for filtering in routine actions* | WHERE time BETWEEN n:now() and message.time *time is a filter variable |
| n:time_difference(StartDate, EndDate) | Returns the time difference between EndDate and StartDate in seconds | ${n:time_difference(n:now(), message.time)} | 1645 |
| n:time_formatted(Calendar, Format, TimeZoneID) | Returns formatted time according to the provided Format and TimeZoneID parameters | ${n:time_formatted(message.time,"HH:mm" , "PST")} | 02:33 |
| n:time_period_secs(Seconds) | Returns time period string based on supplied Seconds value | ${n:time_period_secs(1645} | 0d, 0h, 27m, 25s |
| n:to_calendar(Text, Time Zone, Format) | Returns Calendar object, after parsing Text date/time value using Time Zone and Format | ${n:to_calendar(22/02/2017, 'US/Pacific', 'dd/MM/yyyy')} | Wednesday, 22 February 2017, 12:00:00 AM |
| n:to_calendar_epoch(EpochSeconds) | Returns Calendar object, corresponding to input EpochSeconds parameter | ${n:to_calendar_epoch(1)} | 31 Dec 1969, 4:00:01 PM *in US/Pacific time |
| n:now() | Returns the current time, unformatted | ${n:now()} | Wed, 2 Feb 2017 3:02:47 AM PDT |
| n:now_PST() | Returns the current time for the US Pacific timezone | ${n:now_PST()} | Wed, 2 Feb 2017 03:02:47 AM PDT |
Mapping Functions
Mapping functions used primarily to place assets on a map given various inputs.
| EL Expression | Description | Usage | Result |
|---|---|---|---|
| nx:reverse_geocode(Location) | Returns a reverse-geocoded Address based on Location parameter | ${nx:reverse_geocode(37.793790, -122.395240)} | 1 Market Street |
| nx:reverse_geocode_strict(Location) | Returns reverse-geocoded nearest Street Address based on Location parameter; if there is no street nearby, returns ‘’ | ${ nx:reverse_geocode_strict(37.793790, -126) | ‘’ (Pacific Ocean) |
| nx:geocode(Address) | Returns geocoded Location based on Address parameter | nx:geocode(1 Market Street, San Francisco, Ca, USA) | 37.793790, -122.395240 |
| n:latitude(Location) | Returns the latitude of a given location | ${n:latitude(n:lat_lng(37.33,43.33))} | 37.33 |
| n:longitude(Location) | Returns the longitude of a given location | ${n:longitude(n:lat_lng(37.33,43.33))} | 43.33 |
| n:lat_lng(Latitude, Longitude) | Returns a LatLng object with the given coordinates | ${n:lat_lng(37.33,43.33))} | An object of Location type. Required for data conversion: when a device sends us latitude and longitude and we need one field of location type. |
| n:distance(Point 1, Point 2) | Returns the distance between two points on a map | ${n:distance( n:lat_lng(33.33, 43.33), n:lat_lng(33.33,44.33 ) )} | 77623.9283268718 |
Bitwise Functions
Compare different bits with any number – more detail needed.
| EL Expression | Description | Usage | Result |
|---|---|---|---|
| n:bit_and(Value 1, Value 2) | Returns the resultant value of a bitwise and operation between the two values | ${n:bit_and(8,12)} | 8 because 8 is 1000 and 12 is 1100 |
| n:bit_lshift(Value 1, Number of Bits) | Returns value after Value 1 is shifted left by specified number of bits | ${n:bit_lshift(15,1)} | 30 |
| n:bit_not(Value 1) | Returns value after inverting all bits from Value 1 | ${n:bit_not(6)} | -7 |
| n:bit_or(Value 1, Value 2) | Returns value after bitwise or operation | ${n:bit_or(6,12)} | 14 = 1110 because 6 is 110 and 12 is 1100 |
| n:bit_rshift(Value 1, Number of Bits) | Returns value after Value 1 is shifted right by specified number of bits | ${n:bit_rshift(15,1)} ${n:bit_rshift(-6,1)} |
7 -3 |
| n:bit_urshift(Value 1, Number of Bits) | Returns value after Value 1 is unsigned shifted right by specified number of bits | ${n:bit_urshift(15,1)} ${n:bit_urshift(-6,1)} |
7 9223372036854775805 |
| n:bit_xor(Value 1, Value 2) | Returns value after bitwise xor operation | ${n:bit_xor(6,12)} | 10 = 1010 because 6 is 110 and 12 is 1100 |
General Usage Functions (Advanced)
A number of more advanced functions to address specific requirements (more information needed)
| EL Expression | Description | Usage | Result |
|---|---|---|---|
| na:allocate(Dimension,Value) | Returns new one-dimensional array with length=Dimension and values=Value | ${na:allocate(3,5)} Such call should be used in Set Variable action. Lets say we added a new local variable named “array” | ${_local.array[0]} = 5 ${_local.array[1]} = 5 ${_local.array[2]} = 5 |
| na:set(Array,Index,Value) | Set an element of Array into Value by Index.The function returns a new array with one changed element. Other elements will be copied without changes. | ${na:set(_local.array,2,7)} Such call should be also used in Set Variable action. Let’s say we added a new local variable named “new_array” | ${_local.array[0]} = 5 ${_local.array[1]} = 5 ${_local.array[2]} = 7 |
| na:length(Array) | Returns length of Array | ${na:length(_local.array)} | 5 |
| ns:media_id(ServiceContext,MediaName) | Returns ID of media lib element. ServiceContext parameter value must be “_services” | ${ns:media_id(_services,'Car')} | 717 |
| ns:document_id(ServiceContext,DocumentName) | Returns ID of document library element. ServiceContext parameter value must be “_services” | ${ns:document_id(_services,'New Doc’)} | 1538 |
| ns:py_evaluate( , , , ) | Executes Python code of version 2.7 | ${ns:py_evaluate(python_test.python_test_code,python_test.python_test_name ,python_test.python_test_value , python_test.python_test_result_name)} In my example “python_test.python_test_code” variable value is: def power (a): return a * a res = str(power (int(b))) python_test.python_test_name value is: b python_test.python_test_value value is: 15 python_test.python_test_result_name value is: res |
225 |
Media Function
The media function is used to reference media like images into an object field
| EL Expression | Description | Usage | Result |
|---|---|---|---|
| n:media_ref(ImageName) | Returns a reference to the image from the media library with name ImageName | ${n:media_ref(‘Kitten Picture’} |  |
*Instead of n:time_range function you can use the following constants: YESTERDAY, THIS_WEEK, LAST_WEEK,THIS_MONTH, LAST_MONTH, THIS_QUARTER, LAST_QUARTER, THIS_YEAR, LAST_YEAR, LAST_24_HOURS, LAST_48_HOURS, LAST_72_HOURS, LAST_7_DAYS, LAST_30_DAYS, TODAY, OLDER_THAN_10_DAYS, OLDER_THAN_30_DAYS, OLDER_THAN_90_DAYS