--- title: Custom library functions description: Use the following PingOne Expression Language custom library functions to process data in strings, arrays, and collections. component: pingone page_id: pingone:pingone_expression_language:p1_expressionlang_custom_library_functions canonical_url: https://docs.pingidentity.com/pingone/pingone_expression_language/p1_expressionlang_custom_library_functions.html revdate: April 25, 2025 page_aliases: ["p1_expressionlang_string_library.adoc", "p1_expressionlang_date_time_library.adoc", "p1_expressionlang_data_library.adoc", "p1_expressionlang_regex_library.adoc", "p1_expressionlang_crypto_library.adoc", "p1_expressionlang_core_library.adoc"] section_ids: exp-lang-string-lib: String library exp-lang-date-time-lib: Date and time library exp-lang-data-lib: Data library exp-lang-regex-lib: Regex library exp-lang-crypto-lib: Crypto library exp-lang-core-lib: Core library examples: Examples --- # 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 )`where `` 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 )`where `` 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 )`where `` 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 )`where `` 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 )`where `` 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 , int , int )`where:- `` is the string to get the substring from - `` is the position to start from - `` 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 , String )`where:- `` is the string to check - `` 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 , String )`where:- `` is the string to check - `` 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 , String )`where:- `` is the string to split - `` 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 , String )`where:- `` is the array containing the values to be joined. - `` 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 , String , int )`where:- `` is the string to search against - `` is the string to find - `` 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 , String , int )`where:- `` is the string to search against - `` is the string to find - `` 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 )`where `` 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 , String , String , int )`where:- `` is the string to be searched against to be replaced in. - `` is the string to be matched and replaced. - `` is the string to be replaced with. - `` 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 , String , boolean )`where:- `` is the string to compare against - `` is the string to compare - `` 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 , Number )`where:- `` is the string representation of an integer number - `` 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 , Number )`where:- *\* is the string representation of a Long number - *\* 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 , Number )`where:- *\* is the string representation of a BigInteger number - *\* 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 , Number )`where:- *\* is the string representation of a Float number - *\* 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 , Number )`where:- *\* is the string representation of a Double number - *\* 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 , Number )`where:- *\* is the string representation of a BigDecimal number - *\* 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 )`where *\* 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 )`where *\* 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 )`where *\* 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 )`where *\* 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 , String…​ )`where:- *\* is the format supported by java.util.Formatter - *\* 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 , String )`where:- *\* 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}/` - *\* 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, *\* 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 , String…​ )`where:- *\* is the input value to test. Can be null or empty - *\* 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 , String…​ )`where:- *\* is the input value to test. Can be null, empty or blank. - *\* 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 , int )`where:- `` is the date in a supported ISO 8601 format. - `` 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 , int )`where:- `` is the date in a supported ISO 8601 format. - `` 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 , int )`where:- `` is the date in a supported ISO 8601 format. - `` 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 , int )`where:- `` is the date in a supported ISO 8601 format. - `` 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 , int )`where:- `` is the date in a supported ISO 8601 format. - `` 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 , int )`where:- `` is the date in a supported ISO 8601 format. - `` 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 )`where `` 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 )`where `` 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 )`where `` 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 )`where `` 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 )`where `` 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 )`where `` 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()` | *\* | | `String toDateTime(int , int , int , int , int , int )`where:- `` is the year to represent - `` is the month-of-year to represent, from `1` (January) to `12` (December) - `` is the day-of-month to represent, from `1` to `31` - `` is the hour-of-day to represent, from `0` to `23` - `` is the minute-of-hour to represent, from `0` to `59` - `` 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 )`where `` 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 )`where `` 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 , String )`where:- `` is the date in a supported ISO 8601 format. - `` 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 , String )`where:- `` is the primary date-time in a supported ISO 8601 format to compare with - `` 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 , String , Number )`where:- *\* is the primary date-time in a supported ISO 8601 format to compare with - *\* is the other date-time in a supported ISO 8601 format to compare to - *\* is the default value to return if either of the input date-time are null, empty, blank or not a supported ISO 8601 format \ and \ 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 *\* is before *\*. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for *\* 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 , String , Number )`where:- *\* is the primary date-time in a supported ISO 8601 format to compare with - *\* is the other date-time in a supported ISO 8601 format to compare to - *\* is the default value to return if either of the input date-time are null, empty, blank, or not a supported ISO 8601 format \ and \ 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 *\* is before *\*. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for *\* 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 , String , Number )`where:- *\* is the primary date-time in a supported ISO 8601 format to compare with - *\* is the other date-time in a supported ISO 8601 format to compare to - *\* is the default value to return if either of the input date-time are null, empty, blank, or not a supported ISO 8601 format \ and \ 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 *\* is before *\*. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for *\* 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 , String , Number )`where:- *\* is the primary date-time in a supported ISO 8601 format to compare with - *\* is the other date-time in a supported ISO 8601 format to compare to - *\* is the default value to return if either of the input date-time are null, empty, blank, or not a supported ISO 8601 format \ and \ 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 *\* is before *\*. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for *\* 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 , String , String )`where:- *\* is the primary date-time in a supported ISO 8601 format to compare with. The value is inclusive. - *\* is the other date-time in a supported ISO 8601 format to compare to. The value is exclusive. - *\* is the default value to return if either of the input date-time are null, empty, blank, or not a supported ISO 8601 format. \ and \ 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 *\* is before *\*. If either of the input date-time is null, empty, blank or not a supported ISO 8601 format, the value provided for *\* 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 )`where *\* is the date-time in a supported ISO 8601 format. \ 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 *\* 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 )`where *\* 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 *\* is null. | `#datetime.fromUnixTimestamp(1609459199)` | `2020-12-31T23:59:59.000Z` | | `String parse(String , String , Object )`where:- *\* is the date with or without time to parse in a format other than ISO 8601 - *\* is the custom format supported by Java DateTimeFormatter used for the specified *\* - *\* is an optional JSON object with default values for allowed date-time fields which cannot be obtained from the *\* format. Supported fields are `zoneid` - if *\* 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. \ is treated as null if null, empty, blank, or not a supported ISO 8601 format. | Parses *\* in a format other than ISO 8601 as specified by *\*, and uses any default values specified in *\* if required to transform it to a date-time in ISO 8601 format.Will return null if *\*:- 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 , String , String )`where:- *\* is the date in a supported ISO 8601 format. - *\* 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 *\*/*\*, such as `Europe/Paris` or `America/New_York`. This is compatible with most IDs from Time Zone. \* *\* is a pattern supported by Java 8 DateTimeFormatter. For available formats, see the [References](p1_expressionlang_references.html) section. \ 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:- *\* is null, empty, or blank - *\* is not a supported ISO 8601 format, or has invalid dates or values - *\* or *\* 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 , )`where:- `` is the array to search through - `` 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 )`where `` 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 , Array )`where `` is the array of values to be searched for in the `` 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 , Array )`where `` is the array of values to be searched for in the `` 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 , Array )`where `` is the array of values to be removed from the `` 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 , Array )`where:- *\* is the array from which values are to be removed - `` is the array of values to be retained if they also exist in `` | 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 , Array )`where:- `` is the first array to which elements will be added to - `` 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 )`where `` 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 , Array )`where `` is the first array which is compared against ``. | 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 , String , String )`where:- `` is the string to search and replace in - `` is the regular expression to which this string is to be matched - `` 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 , String , String , …​, String , String )`where:- `` is the string to search and replace in - `` is the regular expression to which this string is to be matched - `` is the string to be substituted for each match - `` is an optional additional regular expression to which this string is to be matched - `` 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 , String )`where:- `` is the string to be matched with - `` 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 , String )`where:- `` is the string to search in - `` 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 , String , String )`where:- `` is the string value to be hashed and must not be null - `` is the string secret key to use and must not be null - `` 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 , Any , Boolean >, Any >, Any )`where:- `` 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. - `` is the value to use if the primary condition evaluates to true. - `>` 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. - *\>* is the value to use if the related elseIf condition evaluates to true. - *\>* 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 , Any , Any , Any >, Any >, Any )`where:- `` is the value against which all the choices are compared with to identify the match. - `` is the choice to match. - `` is the value to use or return if the valueToFind matches the corresponding valueToMatch. - *\>* are additonal and optional choices to match. - *\>* is the value to use or return if the valueToFind matches the corresponding choiceToMatch\. - *\* 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 *\* is compared against 1 or more choices to match (*\>*).If a match is found, the value corresponding to the matched choice (*\>*) is returned. If no match is found, *\* is returned if provided, or else null.*\>* and *\>* 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 , Any , Boolean >, Any >, Any )` | ```json { user: { type: "User" } } #core.ifelse(user.type == 'Administrator', 'Full Access', user.type == 'User', 'Restricted Access', 'No Access') ```returns `Restricted Access````json { 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 , Any , Any , Any >, Any >, Any )` | ```json { user: { type: "Administrator" } } #core.switchExpr(user.type, 'Administrator', 'Full Access') ```returns `Restricted Access````json { user: { type: "User" } } #core.switchExpr(user.type, 'Administrator', 'Full Access', 'User', 'Restricted Access', 'No Access') ```returns `Restricted Access` |