PingOne

Custom library functions

Use the following custom library functions to process data in strings, arrays and collections.

String library

You can perform string-related operations within an expression using the following library.

String Description Input Output

boolean isNotEmpty(String <input>)

where <input> is the string to check.

Returns true if the input string is not empty ("") and not null.

  1. #string.isNotEmpty('InputData')

  2. #string.isNotEmpty('')

  1. true

  2. false

boolean isNotBlank(String <input>)

where <input> is the string to check.

Returns true if the input string is not empty (""), not null and not white space only.

  1. #string.isNotBlank('InputData')

  2. #string.isNotBlank(' ')

  1. true

  2. false

String upperCase(String <input>)

where <input> is the string being converted to upper case.

Converts all characters to uppercase. Returns all characters in upper case if input is not null. Returns null if input is null.

#string.upperCase('john')

JOHN

String lowerCase(String <input>)

where <input> is the string being converted to lower case.

Converts all characters to lowercase. Returns all characters in lower case if input is not null. Returns null if input is null.

#string.lowerCase('LOWER')

lower

String trim(String <input>)

where <input> is the string being trimmed.

Removes white space from the start and end of string if input is not null. Returns null if input is null.

#string.trim(' No Padding ')

No Padding

String substring(String <input>, int <start>, int <end>)

where:

  • <input> is the string to get the substring from

  • <start> is the position to start from

  • <end> is the exclusive position to end at

Gets a substring from the input string starting from the start position and up until the end position, not including the end position. You can use a negative value to start or end n characters from the end of the string. All position counting is zero-based. If start is not to the left of end, "" is returned. Returns null if input is null.

  1. #string.substring('example input for substring demo', 8, 13)

  2. #string.substring('example input for substring demo', -24, 13)

  3. #string.substring('example input for substring demo', -24, -19)

  1. input

  2. input

  3. input

boolean startsWith(String <input>, String <prefix>)

where:

  • <input> is the string to check

  • <prefix> is the prefix to match at the start of the input string.

Checks if the input string starts with the specified prefix and the comparison is case sensitive. Returns true if the input string starts with the prefix with the same case or if both are null.

#string.startsWith('InputData', 'In')

true

boolean endsWith(String <input>, String <suffix>)

where:

  • <input> is the string to check

  • <suffix> is the suffix to match at the end of the input string

Checks if the input string ends with the specified suffix and the comparison is case sensitive. Returns true if input string ends with the suffix with the same case or if both are null.

#string.endsWith('InputData', 'Data')

true

String[] split(String <input>, String <separators>)

where:

  • <input> is the string to split

  • <separators> are the characters to be used as delimiters to split the input string

Splits the provided text into an array based on the specified separators. Returned array won’t contain any separators. A null separator splits on white space. Returns null if input is null.

#string.split('Administrator, User, Guest', ', ')

["Administrator", "User", "Guest"]

String join(Array <values>, String <separator>)

where:

  • <values> is the array containing the values to be joined.

  • <separator> is the delimiter to use when joining the values in the input array. A null separator is treated as an empty string.

Joins the elements of the provided array into a single string containing the provided elements separated by the provided separator. Returns the joined string or null if the array is null.

#string.join(\{'Administrator', 'User', 'Guest'}, ', ')

Administrator, User, Guest

int indexOf(String <input>, String <searchStr>, int <fromIndex>)

where:

  • <input> is the string to search against

  • <searchStr> is the string to find

  • <fromIndex> is the start position in the input string to start the search from

Finds the first index of the search string within the input string. A negative start position is treated as zero, and a start position greater than the input string length only matches an empty search. An empty search string ("") always matches. Returns -1 if a match is not found.

#string.indexOf('To find and return index or return -1', 'return', -1)

12

int lastIndexOf(String <input>, String <searchStr>, int <fromIndex>)

where:

  • <input> is the string to search against

  • <searchStr> is the string to find

  • <fromIndex> is the start position in the input string to begin the search from

Finds the last index within the input string. Search starts from the start position and continues backwards. A negative start position is treated as zero, and a start position greater than the input string length searches the entire string backwards. Returns -1 if a match is not found.

#string.lastIndexOf('To find and return index or return -1', 'return', 50)

28

int length(String <input>)

where <input> is the string to find the length of.

Returns the length of the input string or 0 if input is null.

#string.length('Input')

5

String replace(String <input>, String <searchStr>, String <replacement>, int <max>)

where:

  • <input> is the string to be searched against to be replaced in.

  • <searchStr> is the string to be matched and replaced.

  • <replacement> is the string to be replaced with.

  • <max> is the maximum number of times replacement should be done. If -1, all matched values will be replaced.

Replaces all occurrences of searchStr within input according to the replacement and max values. A null reference passed to this method is a no-op.

#string.replace('input values replaced by input replacement', 'in', 'out', -1)

output values replaced by output replacement

int compare(String <str1>, String <str2>, boolean <ignoreCase>)

where:

  • <str1> is the string to compare against

  • <str2> is the string to compare

  • <ignoreCase> determines whether the comparison is case-sensitive.

Compares two strings lexicographically. Returns 0 if str1 is equal to str2 or both are null. Returns a negative number if str1 is less than str2. Returns a positive number if str1 is greater than str2.

#string.compare('Input', 'INPUT', true)

0

Number asInt(String <input>, Number <defaultIfNullOrInvalid>)

where:

  • <input> is the string representation of an integer number

  • <defaultIfNullOrInvalid> is the default value to be used if the string input is null, not a valid number, or out of range for integers

Parses the string argument as a signed decimal integer (min -2147483648 and max 2147483647).

The characters in the string must all be decimal digits, except that the first character can be an ASCII minus sign (-) to indicate a negative value or an ASCII plus sign (+) to indicate a positive value. If input is null or not a valid integer, defaultIfNullOrInvalid is returned.

  1. #string.asInt('12', 0)

  2. #string.asInt('NaN', 0)

  3. #string.asInt('9876543210123456789', 0)

  1. 12

  2. 0

  3. 0

Number asLong(String <input>, Number <defaultIfNullOrInvalid>)

where:

  • <input> is the string representation of a Long number

  • <defaultIfNullOrInvalid> is the default value to be used if string input is null, not a valid number, or out of range for Longs

Parses the string argument as a signed decimal long (min -9223372036854775808 and max 9223372036854775807).

The characters in the string must all be decimal digits, except that the first character can be an ASCII minus sign (-) to indicate a negative value or an ASCII plus sign (+) to indicate a positive value. If input is null or not a valid Long, defaultIfNullOrInvalid is returned.

  1. #string.asLong('12', 0)

  2. #string.asLong('NaN', 0)

  3. #string.asLong('9876543210123456789', 0)

  1. 12

  2. 0

  3. 0

Number asBigInt(String <input>, Number <defaultIfNullOrInvalid>)

where:

  • <input> is the string representation of a BigInteger number

  • <defaultIfNullOrInvalid> is the default value to be used if string input is null, not a valid number, or out of range for BigInteger

Translates the decimal string representation of a BigInteger into a BigInteger.

The string representation consists of an optional minus sign followed by a sequence of one or more decimal digits. The character-to-digit mapping is provided by Character.digit. If input is null or not a valid Big Integer, defaultIfNullOrInvalid is returned.

  1. #string.asBigInt('1234567890987654321', 0)

  2. #string.asBigInt('NaN', 0)

  1. 1234567890987654321

  2. 0

Number asFloat(String <input>, Number <defaultIfNullOrInvalid>)

where:

  • <input> is the string representation of a Float number

  • <defaultIfNullOrInvalid> is the default value to be used if string input is null, not a valid number, or out of range for Floats

Parses the string argument as a signed decimal float. If input is null, not a valid Float, or Infinity, defaultIfNullOrInvalid is returned.

  1. #string.asFloat('12.5', 0)

  2. #string.asFloat('NaN', 0)

  3. #string.asFloat('1234567899876543210123456789987654321019.12', 0)

  1. 12.5

  2. 0

  3. 0

Number asDouble(String <input>, Number <defaultIfNullOrInvalid>)

where:

  • <input> is the string representation of a Double number

  • <defaultIfNullOrInvalid> is the default value to be used if string input is null, not a valid number, or out of range for doubles

Parses the string argument as a signed decimal double. If input is null, not a valid number within the range of Double, or Infinity, defaultIfNullOrInvalid is returned.

  1. #string.asDouble('1234567899876543210123456789987654321019.12', 0)

  2. #string.asDouble('NaN', 0)

  1. 1234567899876543210123456789987654321019.12

  2. 0

Number asBigDecimal(String <input>, Number <defaultIfNullOrInvalid>)

where:

  • <input> is the string representation of a BigDecimal number

  • <defaultIfNullOrInvalid> is the default value to be used if string input is null, not a valid number, or out of range for BigDecimal

Translates the string representation of a BigDecimal into a BigDecimal.

The string representation consists of an optional sign, (+ or -), followed by a sequence of zero or more decimal digits (the integer), optionally followed by a fraction, optionally followed by an exponent. The fraction consists of a decimal point followed by zero or more decimal digits. The string must contain at least one digit in either the integer or the fraction. The exponent consists of the character e or E followed by one or more decimal digits.

The value of the exponent must lie between -Integer.MAX_VALUE (Integer.MIN_VALUE+1) and Integer.MAX_VALUE, inclusive. If input is null or not a valid BigDecimal, defaultIfNullOrInvalid is returned.

  1. #string.asBigDecimal('1234567890987654321.14', 0)

  2. #string.asBigDecimal('NaN', 0)

  1. 1234567890987654321.14

  2. 0

String asBase64Encoded(String <input>)

where <input> is the string to be encoded.

Encodes the input string into a new string using the Base64 encoding scheme. Returns the encoded string if input is not empty, or else input is returned as-is.

#string.asBase64Encoded('Test Value for encoding')

VGVzdCBWYWx1ZSBmb3IgZW5jb2Rpbmc=

String asBase64Decoded(String <input>)

where <input> is the Base64 encoded string to be decoded.

Decodes a Base64 encoded string into a new string using the Base64 encoding scheme. Returns the encoded string if input is not empty, or else input is returned as-is. This will return null if the input string is not in the valid Base64 schema.

#string.asBase64Decoded('VGVzdCBWYWx1ZSBmb3IgZW5jb2Rpbmc=')

Test Value for encoding

String asUrlEncoded(String <input>)

where <input> is the string to be encoded.

Translates a string into application/x-www-form-urlencoded format using UTF-8 encoding scheme. Returns the encoded string if input is not empty, or else input is returned as-is.

#string.asUrlEncoded('username=johndoe+admin')

username%3Djohndoe%2Badmin

String asUrlDecoded(String <input>)

where <input> is the URL encoded string to be decoded.

Decodes an application/x-www-form-urlencoded string using UTF-8 encoding scheme. Returns the decoded string if input is not empty, or else input is returned as it is. Returns null if the input string cannot be decoded due to any illegal characters.

#string.asUrlDecoded('username%3Djohndoe%2Badmin')

username=johndoe+admin

String format(String <format>, String…​ <args>)

where:

  • <format> is the format supported by java.util.Formatter

  • <args> are the arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The number of arguments is variable and can be zero

Returns a formatted string using the specified format string and arguments. Returns null if a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions.

  1. #string.format('UserId: %s, Full Name: %s, %s', 'johndoe','John', 'Doe')

  2. #string.format('Hex for 10 is %X', 10)

  1. UserId: johndoe, Full Name: John, Doe

  2. Hex for 10 is A

String uuidAsBase64Guid(String <input>, String <defaultIfNullOrInvalid>)

where:

  • <input> is a string representation of a UUID. Invalid if not compatible with regex /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/

  • <defaultIfNullOrInvalid> is the default value to be used if input is null or not a valid UUID

Translates the string representation of a UUID to a GUID in Base64 format. If input is null or not a valid UUID, <defaultIfNullOrInvalid> is returned.

  1. #string.uuidAsBase64Guid('7754d487-1fc3-4206-9e95-ce012f1586e5', null)

  2. #string.uuidAsBase64Guid('invalid', 'lZkqAJgEv0ueGKboT/JFVg==')

  1. h9RUd8MfBkKelc4BLxWG5Q==

  2. lZkqAJgEv0ueGKboT/JFVg==

String firstNonEmpty(String <value1>, String…​ <value2…​10>)

where:

  • <value1> is the input value to test. Can be null or empty

  • <value2…​10> are additional and optional input values to test. Can be null or empty

Returns the first value in the input values which is not empty ('') or null. If all input values are null or empty, then null is returned. There must be at least one input value and the rest are optional. You can enter a maximum of 10 input values.

  1. #string.firstNonEmpty(null, '', 'firstNonEmpty', 'secondNonEmpty')

  2. #string.firstNonEmpty('', '')

  1. firstNonEmpty

  2. null

String firstNonBlank(String <value1>, String…​ <value2…​10>)

where:

  • <value1> is the input value to test. Can be null, empty or blank.

  • <value2…​10> are additional and optional input values to test. Can be null, empty or blank

Returns the first value in the input values which is not empty (''), null or whitespace only. If all input values are null, empty or blank then null is returned. There must be at least one input value and the rest are optional. You can enter a maximum of 10 input values.

  1. #string.firstNonBlank(null, '', ‘ ‘, 'firstNonEmpty', 'secondNonEmpty')

  2. #string.firstNonBlank('', ‘ ‘, '')

  1. firstNonEmpty

  2. null

Date and time library

You can parse, format, and process the date and time within an expression. Dates use the ISO 8601 format in UTC.

Examples of valid dates:

  • 2023-01-01T23:59:59Z

  • 2023-01-01T23:59:59.123Z

  • 2023-01-01T23:59:59.123456Z

  • 2023-01-01T23:59:59+800

Default output formats are in UTC:

  • 2023-01-01T23:59:59.001Z

  • 2023-01-01Z

  • 23:59:59Z

If you input the ISO 8601 format incorrectly, the system returns null.

This library accepts DateTime with millisecond precision greater than 3, but the output always truncates to millisecond precision of 3.

Additional input formats not documented above are not officially supported and subject to change without notice.
String Description Input Output

String addDays(String <inputDate>, int <days>)

where:

  • <inputDate> is the date in a supported ISO 8601 format.

  • <days> is the number of days to add. Can be negative to decrement.

Adds a number of days to the date represented by a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

  1. #datetime.addDays('2021-01-31T01:01:01Z', 1)

  2. #datetime.addDays('2021-03-01Z', -1)

  1. 2021-02-01T01:01:01.000Z

  2. 2021-02-28T00:00:00.000Z

String addMonths(String <inputDate>, int <months>)

where:

  • <inputDate> is the date in a supported ISO 8601 format.

  • <months> is the number of months to add. Can be negative to decrement.

Adds a number of months to the date represented by a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

  1. #datetime.addMonths('2020-12-31T01:01:01.001Z', 2)

  2. #datetime.addMonths('2021-02-28T01:01:01Z', -1)

  1. 2021-02-28T01:01:01.001Z

  2. 2021-01-28T01:01:01.000Z

String addYears(String <inputDate>, int <years>)

where:

  • <inputDate> is the date in a supported ISO 8601 format.

  • <years> is the number of years to add. Can be negative to decrement.

Adds a number of years to the date represented by a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format, or has invalid date range or values.

#datetime.addYears('2021-01-31T01:01:01Z', 1)

2022-01-31T01:01:01.000Z

String addHours(String <inputDate>, int <hours>)

where:

  • <inputDate> is the date in a supported ISO 8601 format.

  • <hours> is the number of hours to add. Can be negative to decrement.

Adds a number of hours to the date represented by a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.addHours('2020-12-31T23:59:59.001Z', 3)

2021-01-01T02:59:59.001Z

String addMinutes(String <inputDate>, int <minutes>)

where:

  • <inputDate> is the date in a supported ISO 8601 format.

  • <minutes> is the number of minutes to add. Can be negative to decrement.

Adds a number of minutes to the date represented by a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.addMinutes('2021-01-31T23:59:59Z', 10)

2021-02-01T00:09:59.000Z

String addSeconds(String <inputDate>, int <seconds>)

where:

  • <inputDate> is the date in a supported ISO 8601 format.

  • <seconds> is the number of seconds to add. Can be negative to decrement.

Adds a number of seconds to the date represented by a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format or has invalid date range or values.

#datetime.addSeconds('2021-02-28Z', 1)

2021-02-28T00:00:01.000Z

int getDayOfMonth(String <inputDate>)

where <inputDate> is the date in a supported ISO 8601 format.

Returns day-of-month, a value from 1 to 31 for valid input or -1 if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.getDayOfMonth('2021-01-31T23:59:59Z')

31

int getMonth(String <inputDate>)

where <inputDate> is the date in a supported ISO 8601 format.

Returns the month from 1 to 12 for valid input or -1 if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.getMonth('2021-02-28Z')

2

int getYear(String <inputDate>)

where <inputDate> is the date in a supported ISO 8601 format.

Returns value for the year for valid input or -1 if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.getYear('2021-01-31T23:59:59Z')

2021

int getHour(String <inputDate>)

where <inputDate> is the date in a supported ISO 8601 format.

Returns the hour of the day as a value between 0 and 23 for valid input or -1 if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.getHour('2021-01-31T23:59:59Z')

23

int getMinute(String <inputDate>)

where <inputDate> is the date in a supported ISO 8601 format.

Returns the minute of the hour as a value between 0 to 59 for valid input or -1 if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.getMinute('2021-01-31T23:59:59Z')

59

int getSecond(String <inputDate>)

where <inputDate> is the date is ISO 8601 format.

Returns the second of the minute as a value between 0 to 59 for valid input or -1 if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.getSecond('2020-12-30T23:59:59.001Z')

59

String now()

Obtains the current date-time in default ISO 8601 output format.

#datetime.now()

<Current date and time in default ISO 8601 format>

String toDateTime(int <year>, int <month>, int <dayOfMonth>, int <hour>, int <minute>, int <second>)

where:

  • <year> is the year to represent

  • <month> is the month-of-year to represent, from 1 (January) to 12 (December)

  • <dayOfMonth> is the day-of-month to represent, from 1 to 31

  • <hour> is the hour-of-day to represent, from 0 to 23

  • <minute> is the minute-of-hour to represent, from 0 to 59

  • <second> is the second-of-minute to represent, from 0 to 59

Obtains the date and time from the provided year, month, day, hour, minute, and second and returns valid date and time in default ISO 8601 output format.

Returns null if the value for any field is incorrect or out of range, such as day-of-month being invalid for the provided month or year.

#datetime.toDateTime(2021, 1, 31, 10, 15, 0)

2021-01-31T10:15:00.000Z

String toDate(String <inputDate>)

where <inputDate> is the date in a supported ISO 8601 format.

Transforms the date and time in a supported ISO 8601 format to a UTC date in the format yyyy-MM-ddX. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.toDate('2021-02-28Z')

2021-02-28Z

String toTime(String <inputDate>)

where <inputDate> is the date in a supported ISO 8601 format.

Transforms the date and time in a supported ISO 8601 format to a UTC time in the format HH:mm:ss[.SSS]X. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.toTime('2021-01-31T23:59:59Z')

23:59:59Z

String format(String <inputDate>, String <pattern>)

where:

  • <inputDate> is the date in a supported ISO 8601 format.

  • <pattern> is a valid pattern supported by Java 8 DateTimeFormatter.

Transforms the date and time in a supported ISO 8601 format to the date and time in the specified format. Returns null if the input dateTime or format is not valid. For more information, see the available formats in the Reference section. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format, has invalid date range or values, or if pattern is null or invalid.

  1. #datetime.format('2021-01-01T09:15:00Z', 'EEEE, dd MMMM; h:mm a')

  2. #datetime.format('2021-02-28Z', "QQQQ 'of year' yyyy")

  1. Friday, 01 January; 9:15 AM

  2. 1st quarter of year 2021

int compare(String <inputDateTime1>, String <inputDateTime2>)

where:

  • <inputDateTime1> is the primary date-time in a supported ISO 8601 format to compare with

  • <inputDateTime2> is the other date-time in a supported ISO 8601 format to compare to

Both values are treated as null if null, empty, blank, or not a supported ISO 8601 format.

Compares this date and time to another date and time, including the chronology. Returns 0 if they are the same, a negative number if the former date is earlier, and a positive number if the former date is later.

  1. #datetime.compare('2021-01-01T00:00:00Z', '2021-01-01T00:00:00Z')

  2. #datetime.compare('2021-01-01T00:00:01Z', '2021-01-01T00:00:00Z')

  1. 0

  2. 1

Number daysBetween(String <inputDateTime1>, String <inputDateTime2>, Number <defaultIfNotDate>)

where:

  • <inputDateTime1> is the primary date-time in a supported ISO 8601 format to compare with

  • <inputDateTime2> is the other date-time in a supported ISO 8601 format to compare to

  • <defaultIfNotDate> is the default value to return if either of the input date-time are null, empty, blank or not a supported ISO 8601 format

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported ISO 8601 format.

Calculates the number of days between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for <defaultIfNotDate> is returned.

  1. #datetime.daysBetween('2021-01-01T00:00:00Z', '2021-01-01T08:45:00Z', -1)

  2. #datetime.daysBetween('2021-01-01T00:00:01Z', '2021-01-03T10:30:00Z', -1)

  3. #datetime.daysBetween('2021-01-03T00:00:01Z', '2021-01-01T10:30:00Z', -1)

  1. 0

  2. 2

  3. -2

Number weeksBetween(String <inputDateTime1>, String <inputDateTime2>, Number <defaultIfNotDate>)

where:

  • <inputDateTime1> is the primary date-time in a supported ISO 8601 format to compare with

  • <inputDateTime2> is the other date-time in a supported ISO 8601 format to compare to

  • <defaultIfNotDate> is the default value to return if either of the input date-time are null, empty, blank, or not a supported ISO 8601 format

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported ISO 8601 format.

Calculates the number of weeks between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for <defaultIfNotDate> is returned.

  1. #datetime.weeksBetween('2021-01-01T00:00:00Z', '2021-01-01T08:45:00Z', -1)

  2. #datetime.weeksBetween('2021-01-01T00:00:01Z', '2021-01-15T10:30:00Z', -1)

  3. #datetime.weeksBetween('2021-01-15T00:00:01Z', '2021-01-01T10:30:00Z', -1)

  1. 0

  2. 2

  3. -2

Number monthsBetween(String <inputDateTime1>, String <inputDateTime2>, Number <defaultIfNotDate>)

where:

  • <inputDateTime1> is the primary date-time in a supported ISO 8601 format to compare with

  • <inputDateTime2> is the other date-time in a supported ISO 8601 format to compare to

  • <defaultIfNotDate> is the default value to return if either of the input date-time are null, empty, blank, or not a supported ISO 8601 format

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported ISO 8601 format.

Calculates the number of months between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for <defaultIfNotDate> is returned.

  1. #datetime.monthsBetween('2021-01-01T00:00:00Z', '2021-01-01T08:45:00Z', -1)

  2. #datetime.monthsBetween('2021-01-01T00:00:01Z', '2021-02-01T10:30:00Z', -1)

  3. #datetime.monthsBetween('2021-02-01T00:00:01Z', '2021-03-01T10:30:00Z', -1)

  1. 0

  2. 1

  3. 1

Number yearsBetween(String <inputDateTime1>, String <inputDateTime2>, Number <defaultIfNotDate>)

where:

  • <inputDateTime1> is the primary date-time in a supported ISO 8601 format to compare with

  • <inputDateTime2> is the other date-time in a supported ISO 8601 format to compare to

  • <defaultIfNotDate> is the default value to return if either of the input date-time are null, empty, blank, or not a supported ISO 8601 format

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported ISO 8601 format.

Calculates the number of years between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for <defaultIfNotDate> is returned.

  1. #datetime.yearsBetween('2021-01-01T00:00:00Z', '2021-01-01T08:45:00Z', -1)

  2. #datetime.yearsBetween('2021-01-01T00:00:01Z', '2022-01-01T10:30:00Z', -1)

  3. #datetime.yearsBetween('2022-01-01T00:00:01Z', '2021-01-01T10:30:00Z', -1)

  1. 0

  2. 1

  3. -1

String periodBetween(String <inputDateTime1>, String <inputDateTime2>, String <defaultIfNotDate>)

where:

  • <inputDateTime1> is the primary date-time in a supported ISO 8601 format to compare with. The value is inclusive.

  • <inputDateTime2> is the other date-time in a supported ISO 8601 format to compare to. The value is exclusive.

  • <defaultIfNotDate> is the default value to return if either of the input date-time are null, empty, blank, or not a supported ISO 8601 format.

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported ISO 8601 format.

Calculates the period between input dates represented as amount of time in years, months, and days using ISO 8601 period format P[nY][nM][nD].

The letter P starts the period, n] is an integer representing the number of years, months, and days, represented by Y, M, and D, respectively.

A zero period is represented as zero days, or P0D. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time is null, empty, blank or not a supported ISO 8601 format, the value provided for <defaultIfNotDate> is returned.

The period is calculated by removing complete months, then calculating the remaining number of days, adjusting to ensure that both have the same sign. The number of months is then split into years and months based on a 12 month year.

  1. #datetime.periodBetween('2021-01-01T00:00:00Z', '2021-01-01T00:00:00Z', -1)

  2. #datetime.periodBetween('2021-01-01Z', '2022-02-11Z', -1)

  1. P0D

  2. P1Y1M10D

String toUnixTimestamp(String <inputDateTime>)

where <inputDateTime> is the date-time in a supported ISO 8601 format.

<inputDateTime> is treated as null if null, empty, blank, or not a supported ISO 8601 format.

Transforms the date-time in a supported ISO 8601 format to the number of seconds from the epoch of 1970-01-01T00:00:00Z. This returns null if <inputDateTime> is null, empty, blank, or not a supported ISO 8601 format.

  1. #datetime.toUnixTimestamp('2020-12-31Z')

  2. #datetime.toUnixTimestamp('2020-12-31T23:59:59Z')

  3. #datetime.toUnixTimestamp('2020-12-31T23:59:59.001Z')

  1. 1609372800

  2. 1609459199

  3. 1609459199

String fromUnixTimestamp(Number <epochSeconds>)

where <epochSeconds> is the number of seconds from the epoch of 1970-01-01T00:00:00Z.

Builds date-time using the number of seconds from the epoch of 1970-01-01T00:00:00Z to a UTC date-time in default ISO 8601 format. Returns null if <epochSeconds> is null.

#datetime.fromUnixTimestamp(1609459199)

2020-12-31T23:59:59.000Z

String parse(String <inputDateTime>, String <format>, Object <options>)

where:

  • <inputDateTime> is the date with or without time to parse in a format other than ISO 8601

  • <format> is the custom format supported by Java DateTimeFormatter used for the specified <inputDateTime>

  • <options> is an optional JSON object with default values for allowed date-time fields which cannot be obtained from the <inputDateTime> format. Supported fields are zoneid - if <inputDateTime> doesn’t contain any zone information, users can configure the zoneid to be used in the input options JSON, or else UTC will be used.

<inputDateTime> is treated as null if null, empty, blank, or not a supported ISO 8601 format.

Parses <inputDateTime> in a format other than ISO 8601 as specified by <format>, and uses any default values specified in <options> if required to transform it to a date-time in ISO 8601 format.

Will return null if <inputDateTime>:

  • Is null

  • Is not in a valid format

  • Cannot be transformed to ISO 8601 if it lacks any required fields such as day, month, or year

  • Any of those fields are out of range
Parsing date with format yyyy-MM-dd without zone information which uses UTC as default zone

#datetime.parse('2022-01-01', 'yyyy-MM-dd', null)

Parsing date with format yyyy-MM-dd without zone information but with zone defaults configured using options

#datetime.parse('2022-01-01', 'yyyy-MM-dd', \{'zoneid': 'America/Vancouver'})

Parsing date with format yyyy-MM-dd z with zone information

#datetime.parse('2022-01-01 PST', 'yyyy-MM-dd z', null)

Parsing date with format dd/MM/yyyy HH:mm:ss without zone information which uses UTC as default zone

#datetime.parse('03/12/2021 09:30:45', 'dd/MM/yyyy HH:mm:ss', null)

  1. 2022-01-01T00:00:00.000Z

  2. 2022-01-01T08:00:00.000Z

  3. 2022-01-01T08:00:00.000Z

  4. 2021-12-03T09:30:45.000Z

String toDateTimeInTimezone(String <inputDateTime>, String <timezone>, String <pattern>)

where:

  • <inputDateTime> is the date in a supported ISO 8601 format.

  • <timezone> is a valid zone ID supported by Java 8. Parsing matches the zone ID as follows:

    1. If the zone ID equals Z, the result is UTC.

    2. If the zone ID consists of a single letter, the zone ID is invalid.

    3. If the zone ID equals GMT, UTC, or UT, then the result is a timezone with the same ID and rules equivalent to UTC.

Zone IDs must match regular expression characters. If the zone ID is not in the Java 8 configured set of IDs, it is invalid. The detailed format of the region ID depends on the group supplying the data. The default set of data is supplied by the IANA Time Zone Database (TZDB).

IANA TZDB has region IDs of the form <area>/<city>, such as Europe/Paris or America/New_York. This is compatible with most IDs from Time Zone. * <pattern> is a pattern supported by Java 8 DateTimeFormatter. For available formats, see the References section.

<inputDateTime> is treated as null if null, empty, blank, or not a supported ISO 8601 format.

Transforms the date-time in a supported ISO 8601 format to date-time in the specified timezone in the required format if specified, or the default format yyyy-MM-dd’T’HH:mm:ss[.SSS]Z.

Will return null if:

  • <inputDateTime> is null, empty, or blank

  • <inputDateTime> is not a supported ISO 8601 format, or has invalid dates or values

  • <timezone> or <pattern> are null or invalid
Change time zone to America/Vancouver with default pattern

#datetime.toDateTimeInTimezone('2023-01-01T04:30:30.000Z', 'America/Vancouver', null)

Change time zone to +100 with default pattern

#datetime.toDateTimeInTimezone('2023-01-01T04:30:30Z', '+0100', null)

Change time zone to America/Vancouver with custom pattern

#datetime.toDateTimeInTimezone('2023-01-01T04:30:30.123Z', 'America/Vancouver', 'dd-MM-YYYY hh:mm a')

  1. 2022-12-31T20:30:30-0800

  2. 2023-01-01T05:30:30.000+0100

  3. 31-12-2022 08:30 PM

Data library

You can process data in arrays and collections using the following library.

When using a collection format, some of the following methods which perform operations between two arrays or collections determine data type automatically based on Java defaults. For example, 3 is treated as integer, 3.5 as a double and c as a string. However, array comparison is based on the array data types.

#data.containsAll(new int[] {2,4,6,8,10}, new int[] {2,8}) returns as true because both are int arrays.

#data.containsAll(new int[] {2,4,6,8,10}, {2,8}) returns as true because the first argument is an int array and the second argument uses int by default.

#data.containsAll(new float[] {2.1,4.1,6.1,8.1,10.1}, {2.1,8.1}) returns as false because the first argument is a float array and the second argument is a double, which is the default for floating point numbers.

#data.containsAll(new double[] {2.1,4.1,6.1,8.1,10.1}, {2.1,8.1}) returns as true because the first argument is a double array and the second argument is treated as a double by default.

#data.containsAll({2.1,4.1,6.1,8.1,10.1}, {2.1,8.1}) returns as true because both arguments are collections and use the default data types.
String Description Input Output

int indexOf(Array <srcArray>, <valueToFind>)

where:

  • <srcArray> is the array to search through

  • <valueToFind> is the value to find.

Finds and returns the index of the valueToFind in the input array. Returns -1 if not found or if srcArray is null.

  1. #data.indexOf(new int[] {2,4,6,8,10}, 6)

  2. #data.indexOf({'This', 'is', 'String', 'collection'}, 'is')

  1. 2

  2. 1

boolean isNotEmpty(Array <srcArray>)

where <srcArray> is the array to check.

Checks if the input array is not empty and not null.

  1. #data.isNotEmpty(new int[] {2,4,6,8,10})

  2. #data.isNotEmpty({'This', 'is', 'String', 'collection'})

  1. true

  2. true

boolean containsAll(Array <srcData>, Array <searchData>)

where <searchData> is the array of values to be searched for in the <srcData> array.

Returns true if all elements of searchData are contained in srcData.

  1. #data.containsAll(new int[] {2,4,6,8,10}, new int[] {2,8})

  2. #data.containsAll(new int[] {2,4,6,8,10}, {2,8})

  3. #data.containsAll({2,4,6,8,10}, {2,9})

  4. #data.containsAll(new float[] {2.1,4.1,6.1,8.1,10.1}, {2.1,8.1})

  5. #data.containsAll(new double[] {2.1,4.1,6.1,8.1,10.1}, {2.1,8.1})

  1. true

  2. true

  3. false

  4. false

  5. true

boolean containsAny(Array <srcData>, Array <searchData>)

where <searchData> is the array of values to be searched for in the <srcData> array.

Returns true if there is at least one common element in both arrays.

  1. #data.containsAny({2,4,6,8,10}, {2,9,11})

  2. #data.containsAny(new int[] {2,4,6,8,10}, {2,9,11})

  3. #data.containsAny({2,4,6,8,10}, new int[] {1,9})

  1. true

  2. true

  3. false

Array removeAll(Array <srcData>, Array <dataToRemove>)

where <dataToRemove> is the array of values to be removed from the <srcData> array.

Removes the elements in dataToRemove from srcData and returns a new array.

  1. #data.removeAll(new int[] {2,4,6,8,10}, new int[] {2,6,11})

  2. #data.removeAll({2,4,6,8,10}, {2,6,11})

  1. [4,8,10]

  2. [4,8,10]

Array retainAll(Array <srcData>, Array <dataToRetain>)

where:

  • <srcData> is the array from which values are to be removed

  • <dataToRetain> is the array of values to be retained if they also exist in <srcData>

Retains only the elements that exist in both srcData and dataToRetain.

  1. #data.retainAll(new int[] {2,4,6,8,10}, new int[] {2,6,11})

  2. #data.retainAll({2,4,6,8,10}, new int[] {2,6,11})

  1. [2,6]

  2. [2,6]

Array union(Array <array1>, Array <array2>)

where:

  • <array1> is the first array to which elements will be added to

  • <array2> is the second array whose elements will be appended to first array.

Returns a new array containing the second array appended to the first array.

  1. #data.union(new int[] {2,4,6,8,10}, new int[] {1,10,11})

  2. #data.union(new int[] {2,4,6,8,10}, {1,10,11})

  1. [2,4,6,8,10,1,10,11]

  2. [2,4,6,8,10,1,10,11]

int size(Array <inputArray>)

where <inputArray> is the array for which the size is determined.

Returns the size of the input array.

  1. #data.size(new int[] {2,4,6,8,10})

  2. #data.size({2,4,6,8,10})

  1. 5

  2. 5

boolean equals(Array <array1>, Array <array2>)

where <array1> is the first array which is compared against <array2>.

Tests two arrays for value-equality and returns true if both arrays have the same size and all corresponding pairs of elements in the two arrays are equal.

  1. #data.equals(new int[] {2,4,6,8,10}, new int[] {2,4,6,8,10})

  2. #data.equals({2,4,6,8,10}, new int[] {2,4,6,8,10})

  1. true

  2. true

Regex library

You can use regular expressions in operations with the following library.

String Description Input Output

String replaceFirst(String <input>, String <regex>, String <replacement>)

where:

  • <input> is the string to search and replace in

  • <regex> is the regular expression to which this string is to be matched

  • <replacement> is the string to be substituted for the first match

Replaces the first substring of the text string that matches the given regular expression with the given replacement. A null reference passed to this method is a no-op and returns null.

  1. #regex.replaceFirst('upper case', '()( +)([a-z])', '$1_$3')

  2. #regex.replaceFirst('upper case AND lower case', '()( +)([a-z])', '$1_$3')

  1. upper_case

  2. upper_case AND lower case

String replaceAll(String <input>, String <regex1>, String <replacement1>, …​, String <regexN>, String <replacementN>)

where:

  • <input> is the string to search and replace in

  • <regex1> is the regular expression to which this string is to be matched

  • <replacement1> is the string to be substituted for each match

  • <regex[2…​N]> is an optional additional regular expression to which this string is to be matched

  • <replacement[2…​N]> is an optional additional string to be substituted for each match. If replacement is missing, the corresponding regex string won’t be altered.

The first pair of find-replace arguments are mandatory and the rest are optional.

Replaces each substring of the text string that matches the given regular expression with the given replacement. You can use this for 1 or more find and replace options. The first pair of find-replace arguments are mandatory and the rest are optional.

  1. #regex.replaceAll('upper case AND lower case', '()( +)([a-z])', '$1_$3')

  2. #regex.replaceAll('numeric data to be replaced with textual data [1, 2]', 'to be', '', '1', 'one', '2', 'two')

  1. upper_case AND lower_case

  2. numeric data replaced with textual data [one, two]

boolean matches(String <input>, String <regex>)

where:

  • <input> is the string to be matched with

  • <regex> is the regular expression to which the string is matched

Checks if the entire input string matches the regex pattern. If a null is passed as input, it returns false.

#regex.matches('upper case', '()( +)([a-z])')

true

Array findAllMatches(String <input>, String <regex>)

where:

  • <input> is the string to search in

  • <regex> is the regular expression to which the string is matched

Find all matching substrings in the input string matching the regex pattern.

#regex.findAllMatches('upper case AND lower case', '()( +)([a-z])')

["upper case", "lower case"]

Crypto library

You can perform crypto operations such as hashing using the following library.

String Description Input Output

String hmacHexDigest(String <data>, String <key>, String <algorithm>)

where:

  • <data> is the string value to be hashed and must not be null

  • <key> is the string secret key to use and must not be null

  • <algorithm> is the hashing algorithm to use and must not be null

Supported algorithms are HmacMD5, HmacSHA1, HmacSHA224, HmacSHA256, HmacSHA384 and HmacSHA512.

Creates a hash for the required data with Hashed Message Authentication Code (HMAC) using the specified secret key and cryptographic hashing function algorithm.

Returns the hash or digest as a string containing only hexadecimal digits.

Supported algorithms for hashing functions are HmacMD5, HmacSHA1, HmacSHA224, HmacSHA256, HmacSHA384, and HmacSHA512.

#crypto.hmacHexDigest('data', 'secretKey', 'HmacMD5')

6659dfc3b860b836c087e3fd82c0d16b

Core library

You can perform basic conditional expressions using if-else and switch alternatives.

String Description

Any ifelse(Boolean <condition>, Any <value>, Boolean <elseifCondition<1…​10>>, Any <elseifValue<1…​10>>, Any <elseValue>)

where:

  • <condition> is the primary If conditional expression which should evaluate to a boolean value. If it is not boolean, every attempt will be made to convert it to a boolean value.

  • <value> is the value to use if the primary condition evaluates to true.

  • <elseifCondition<1…​10>> is an elseIf conditional expression which should evaluate to a boolean value. If it is not boolean, every attempt will be made to convert it to a boolean value. The elseIfValue should always follow the elseIf condition.

  • <elseifValue<1…​10>> is the value to use if the related elseIf condition evaluates to true.

  • <elseValue>> is the value to use if none of the conditions evaluate to true.

Library function for an If-Else statement. Expressions provided for If and elseIf conditions should evaluate to a boolean value and if not, every attempt will be made to convert the evaluated value to boolean.

If the condition evaluates to a Number, any value greater than 0 will be treated as True, or else false. If the condition evaluates to a String, the values true, on, y, t, yes are treated as true irrespective of the case, and otherwise false. If the condition evaluates to something other than Boolean, Number or String, it will be treated as false.

The If statement and elseIf statement is a pair: a condition and a value to be used if condition evaluates to true. The elseIf statements are optional, and can enter 0 to 10 elseIf statements as needed.

The elseValue to be used if no condition evaluates to true is also optional and is always the last parameter in the method.

Any switchExpr(Any <valueToFind>, Any <choiceToMatch1>, Any <valueToReturn1>, Any <choiceToMatch<2…​10>>, Any <valueToReturn<2…​10>>, Any <defaultValue>)

where:

  • <valueToFind> is the value against which all the choices are compared with to identify the match.

  • <choiceToMatch1> is the choice to match.

  • <valueToReturn1> is the value to use or return if the valueToFind matches the corresponding valueToMatch.

  • <choiceToMatch<2…​10>> are additonal and optional choices to match.

  • <valueToReturn<2…​10>> is the value to use or return if the valueToFind matches the corresponding choiceToMatch<n>.

  • <defaultValue> is the value to use if no matching choice is found for valueToFind. If this is not provided, null is returned.

Library function for a switch statement. A <valueToFind> is compared against 1 or more choices to match (<choiceToMatch<1…​10>>).

If a match is found, the value corresponding to the matched choice (<valueToReturn<1…​10>>) is returned. If no match is found, <defaultValue> is returned if provided, or else null.

<choiceToMatch<n>> and <valueToReturn<n>> are a pair and there should be a minimum of 1 pair and not exceed 10 pairs. A default value can be provided as the last parameter to the method.

Examples

String Input

Any ifelse(Boolean <condition>, Any <value>, Boolean <elseifCondition<1…​10>>, Any <elseifValue<1…​10>>, Any <elseValue>)

 
{
  user: {
    type: "User"
  }
}
#core.ifelse(user.type == 'Administrator', 'Full Access', user.type == 'User', 'Restricted Access', 'No Access')

returns Restricted Access

{
  user: {
    memberOfGroupIDs: ["User"],
    type: "Dev"
  }
}
#core.ifelse(#data.indexOf(user.memberOfGroupIDs, 'Administrator') >= 0, 'Full Access',
	#data.indexOf(user.memberOfGroupIDs, 'User') >= 0,
	#core.ifelse(user.type == 'SRE', 'Power Access', user.type == 'Dev', 'Debugging Access', 'Read Access'), 'No Access')

returns Debugging Access

Any switchExpr(Any <valueToFind>, Any <choiceToMatch1>, Any <valueToReturn1>, Any <choiceToMatch<2…​10>>, Any <valueToReturn<2…​10>>, Any <defaultValue>)

 
{
  user: {
    type: "Administrator"
  }
}
#core.switchExpr(user.type, 'Administrator', 'Full Access')

returns Restricted Access

{
  user: {
    type: "User"
  }
}
#core.switchExpr(user.type, 'Administrator', 'Full Access', 'User', 'Restricted Access', 'No Access')

returns Restricted Access