PingGateway 2024.11

Functions

A set of built-in functions to call in Expressions.

array

array(strings...)

Returns an array of the strings given as argument.

Parameters
strings

Strings to put in the array.

Returns
array

Resulting array containing the given strings.

boolean

bool(string)

Returns a Boolean with a value represented by the specified string.

The returned Boolean represents a true value if the string argument isn’t null and is equal to the string "true", ignoring case.

Parameters
string

String containing the boolean representation.

Returns
Boolean

Boolean value represented by the string.

contains

contains(object, value)

Returns true if the object contains the specified value. If the object is a string, a substring is searched for the value. If the object is a collection or array, its elements are searched for the value.

Parameters
object

Object to search for.

value

Value to search for.

Returns
true

If the object contains the specified value.

decodeBase64

decodeBase64(string)

Returns the base64-decoded string, or null if the string isn’t valid base64.

Parameters
string

Base64-encoded string to decode.

Returns
string

Base64-decoded string.

decodeBase64url

decodeBase64url(string)

Returns the decoded value of the provided base64url-encoded string, or null if the string was not valid base64url.

Parameters
string

Base64url-encoded string to decode.

Returns
string

Base64url-decoded string.

derCertificate

derCertificate(string)

Convert the incoming character sequence into a certificate.

Parameters
string

Character sequence representing a base64-encoded DER-format (binary) certificate.

The string begins and ends with :. Learn more in RFC 9440 Appendix A.

Returns
string

A Certificate instance or null if the function failed to load a certificate from the incoming object.

digestSha256

digestSha256(byte array or string)

Calculates the SHA-256 hash of an incoming object.

Parameters
byte array or string

The bytes to be hashed. If a string is provided, this function uses the UTF-8 charset to get the bytes from the string.

Returns
byte array

SHA-256 hash as a byte array, or null if the hash could not be calculated.

encodeBase64

encodeBase64(string)

Returns the base64-encoded string, or null if the string is null.

Parameters
string

String to encode into base64.

Returns
string

Base64-encoded string.

encodeBase64url

encodeBase64url(string)

Returns the base64url-encoded string, or null if the string is null.

Parameters
string

String to encode into base64url.

Returns
string

Base64url-encoded string.

fileToUrl

fileToUrl(file)

Converts a java.io.File into a string representation for the URL of the file or directory.

Parameters
file

File or directory for which to build the URL.

For example, ${fileToUrl(openig.configDirectory)}/myProperties.json.

Returns
file

String representation for the URL of the file or directory, or null if the file or directory is null.

For example, file:///home/gcostanza/.openig/config/myProperties.json.

find

find(string, pattern)

Attempts to find the next subsequence of the input string that matches the pattern.

Parameters
string

The input string.

pattern

A regular expression pattern.

Returns
boolean

  • true if a subsequence of the input string matches the regular expression pattern.

  • false if the input string is null, or a subsequence of it doesn’t match the regular expression pattern.

findGroups

findGroups(string, pattern)

Attempts to find a string that matches the regular expression or groups specified in the regular expression.

Parameters
string

The input on which the regular expression is applied.

pattern

A regular expression pattern.

Returns
array

An array containing the result of a find on the regular expression against the input string, or null if no result is found.

The first element of the array is the entire match, and each subsequent element correlates to a capture group specified in the regular expression.

formDecodeParameterNameOrValue

formDecodeParameterNameOrValue(string)

Returns the string that results from decoding the provided form encoded parameter name or value as per application/x-www-form-urlencoded, which can be null if the input is null.

Parameters
string

Parameter name or value.

Returns
string

String resulting from decoding the provided form encoded parameter name or value as per application/x-www-form-urlencoded.

formEncodeParameterNameOrValue

formEncodeParameterNameOrValue(string)

Returns the string that results from form encoding the provided parameter name or value as per application/x-www-form-urlencoded, which can be null if the input is null.

Parameters
string

Parameter name or value.

Returns
string

String resulting from form encoding the provided parameter name or value as per application/x-www-form-urlencoded.

indexOf

indexOf(string, substring)

Returns the index of the first instance of a specified substring inside a string.

Characters in the provided string are UTF-16, based on 16-bit code units. Each character is encoded as at least two bytes, and some extended characters are encoded as four bytes.

When this function processes a 2-byte character, it counts it as one 16-bit character. When it processes a 4-byte character, it counts it as two 16-bit characters.

Examples:

  • The unicode character a (U+0061) has the UTF-16 value 0x0061. The function {{indexOf('afooBar', 'Bar')}} evaluates to 4.

  • The unicode character 𐁗 (U+10057) has the UTF-16 value 0xD800 0xDC57. The function {{indexOf('𐁗fooBar', 'Bar')}} evaluates to 5.

Parameters
string

String in which to search for the specified substring.

substring

Value to search for within the string.

Returns
number

Index of the first instance of the substring, or -1 if not found.

The index count starts from 1, not 0.

integer

integer(string)

Transforms the string parameter into an integer. If the parameter isn’t a valid number in radix 10, returns null.

Parameters
string

String containing the integer representation.

Returns
integer

Integer value represented by the string.

integerWithRadix

integer(string, radix)

Uses the radix as the base for the string, and transforms the string into a base-10 integer. For example:

  • ("20", 8): Transforms 20 in base 8, and returns 16.

  • ("11", 16) Transforms 11 in base 16, and returns 17.

If either parameter isn’t a valid number, returns null.

Parameters
string

String containing the integer representation, and an integer containing the radix representation.

Returns
integer

Integer value in base-10.

ipMatch

ipMatch(string, string)

Returns true if the IP address matches the range provided by the Classless Inter-Domain Routing (CIDR), false otherwise.

Parameters
string

IP address of a request sender, in IPv4 or IPv6

string

CIDR defining an IP address range

Returns
Boolean

true or false

join

join(values, separator)

Returns a string joined with the given separator, using either of the following values:

  • Array of strings (String[])

  • Iterable value (Iterable<String>)

The function uses the toString result from each value.

Parameters
separator

Separator to place between joined values.

strings

Array of values to be joined.

Returns
string

String containing the joined values.

keyMatch

keyMatch(map, pattern)

Returns the first key found in a map that matches the specified regular expression pattern, or null if no such match is found.

Parameters
map

Map whose keys are to be searched.

pattern

String containing the regular expression pattern to match.

Returns
string

First matching key, or null if no match found.

length

length(object)

Returns the number of items in a collection, or the number of characters in a string.

Characters in the provided string are UTF-16, based on 16-bit code units. Each character is encoded as at least two bytes, and some extended characters are encoded as four bytes.

When this function processes a 2-byte character, it counts it as one 16-bit character. When it processes a 4-byte character, it counts it as two 16-bit characters.

Examples:

  • The unicode character a (U+0061) has the UTF-16 value 0x0061. The function {{length('a')}} evaluates to 1.

  • The unicode character 𐁗 (U+10057) has the UTF-16 value 0xD800 0xDC57. The function {{length('𐁗')}} evaluates to 2.

Parameters
object

A collection or string, whose length is to be determined.

Returns
number

Length of the collection or string, or 0 if length could not be determined.

matches (deprecated)

This function is deprecated. Use the matchesWithRegex or find function instead. For more information, refer to the Deprecated section of the Release Notes. 
matches(string, pattern)

Returns true if the string contains a match for the specified regular expression pattern.

Parameters
string

The input string.

pattern

A regular expression pattern.

Returns
true

String contains the specified regular expression pattern.

matchesWithRegex

matchesWithRegex(string, pattern)

Attempts to match the entire input string against the regular expression pattern.

Parameters
string

The input string.

pattern

A regular expression pattern.

Returns
boolean

  • true if the entire input string matches the regular expression pattern.

  • false if the input string is null, or the entire input string doesn’t match the regular expression pattern.

matchingGroups (deprecated)

This function is deprecated. Use the findGroups function instead. You can find more information in the Deprecated section of the Release Notes. 
matchingGroups(string, pattern)

Returns an array of matching groups for the specified regular expression pattern applied to the specified string or null if no such match is found. The first element of the array is the entire match. Each later element correlates to any capture group specified within the regular expression.

Parameters
string

String to be searched.

pattern

String containing the regular expression pattern to match.

Returns
array

Array of matching groups or null if no such match is found.

pathToUrl

pathToUrl(path)

Converts the given path into the string representation of its URL.

Parameters
path

Path of a file or directory as a string.

For example, ${pathToUrl(system['java.io.tmpdir'])}.

Returns
string

String representation for the URL of the path or null if the path is null.

For example, file:///var/tmp.

pemCertificate

pemCertificate(string)

Convert the incoming character sequence into a certificate.

Parameters
string

Character sequence representing a PEM-formatted certificate

Returns
string

A Certificate instance or null if the function failed to load a certificate from the incoming object.

read

read(string)

Takes a file name as a string, interprets the content of the file with the UTF-8 character set, and returns the content of the file as a plain string.

Provides the absolute path to the file or a path relative to the location of the Java system property user.dir.

Parameters
string

Name of the file to read.

Returns
string

Content of the file or null on error.

readProperties

readProperties(string)

Takes a Java Properties filename as a string, and returns the content of the file as a key/value map of properties or null on error (due to the file not being found, for example).

Java properties files are expected to be encoded with ISO-8859-1. Characters that cannot be directly represented in ISO-8859-1 can be written using Unicode escapes, as defined in Unicode Escapes, in The Java™ Language Specification.

Parameters
string

The absolute path to the Java properties file or a path relative to the location of the Java system property user.dir.

For example, to return the value of the key property in the Java properties file /path/to/my.properties, provide ${readProperties('/path/to/my.properties')['key']}.

Returns
object

Key/value map of properties or null on error.

readWithCharset

readWithCharset(string, string)

Takes a file name as a string, interprets the content of the file with the specified Java character set, and returns the content of the file as a plain string.

Parameters
filename

Name of the file to read.

Provides the absolute path to the file or a path relative to the location of the Java system property user.dir.

charsetName

Name of a Java character set with which to interpret the file, as described in Class Charset.

Returns
string

Content of the file or null on error.

split

split(string, pattern)

Splits the specified string into an array of substrings around matches for the specified regular expression pattern.

Parameters
string

String to be split.

pattern

Regular expression to split substrings around.

Returns
array

Resulting array of split substrings.

toJson

toJson(JSON string)

Converts a JSON string to a JSON structure.

Parameters
JSON string

JSON string representing a JavaScript object.

For example, the string value contained in contexts.amSession.properties.userDetails contains the JSON object {"email":"test@example.com"}.

Returns
JSON structure

JSON structure or null on error.

In the expression "${toJson(contexts.amSession.properties.userDetails).email}", the string value is treated as JSON, and the expression evaluates to test@example.com.

toLowerCase

toLowerCase(string)

Converts all the characters in a string to lowercase.

Parameters
string

String whose characters are to be converted.

Returns
string

String with characters converted to lowercase.

toString

toString(object)

Returns the string value of an arbitrary object.

Parameters
object

Object whose string value is to be returned.

Returns
string

String value of the object.

toUpperCase

toUpperCase(string)

Converts all of the characters in a string to upper case.

Parameters
string

String whose characters are to be converted.

Returns
string

String with characters converted to upper case.

trim

trim(string)

Returns a copy of a string with leading and trailing whitespace omitted.

Parameters
string

String whose white space is to be omitted.

Returns
string

String with leading and trailing white space omitted.

urlDecode

urlDecode(string)

Returns the URL decoding of the provided string.

This is equivalent to formDecodeParameterNameOrValue.

Parameters
string

String to be URL decoded, which may be null.

Returns
string

URL decoding of the provided string, or null if string was null.

urlEncode

urlEncode(string)

Returns the URL encoding of the provided string.

This is equivalent to formEncodeParameterNameOrValue.

Parameters
string

String to be URL encoded, which can be null.

Returns
string

URL encoding of the provided string or null if string was null.

urlDecodeFragment

urlDecodeFragment(string)

Returns the string that results from decoding the provided URL encoded fragment as per RFC 3986, which can be null if the input is null.

Parameters
string

URL encoded fragment.

Returns
string

String resulting from decoding the provided URL encoded fragment as per RFC 3986.

urlDecodePathElement

urlDecodePathElement(string)

Returns the string that results from decoding the provided URL encoded path element as per RFC 3986, which can be null if the input is null.

Parameters
string

The path element.

Returns
string

String resulting from decoding the provided URL encoded path element as per RFC 3986.

urlDecodeQueryParameterNameOrValue

urlDecodeQueryParameterNameOrValue(string)

Returns the string that results from decoding the provided URL encoded query parameter name or value as per RFC 3986, which can be null if the input is null.

Parameters
string

Parameter name or value.

Returns
string

String resulting from decoding the provided URL encoded query parameter name or value as per RFC 3986.

urlDecodeUserInfo

urlDecodeUserInfo(string)

Returns the string that results from decoding the provided URL encoded userInfo as per RFC 3986, which can be null if the input is null.

Parameters
string

URL encoded userInfo.

Returns
string

String resulting from decoding the provided URL encoded userInfo as per RFC 3986.

urlEncodeFragment

urlEncodeFragment(string)

Returns the string that results from URL encoding the provided fragment as per RFC 3986, which can be null if the input is null.

Parameters
string

Fragment.

Returns
string

The string resulting from URL encoding the provided fragment as per RFC 3986.

urlEncodePathElement

urlEncodePathElement(string)

Returns the string that results from URL encoding the provided path element as per RFC 3986, which can be null if the input is null.

Parameters
string

Path element.

Returns
string

String resulting from URL encoding the provided path element as per RFC 3986.

urlEncodeQueryParameterNameOrValue

urlEncodeQueryParameterNameOrValue(string)

Returns the string that results from URL encoding the provided query parameter name or value as per RFC 3986, which can be null if the input is null.

Parameters
string

Parameter name or value.

Returns
string

String resulting from URL encoding the provided query parameter name or value as per RFC 3986.

urlEncodeUserInfo

urlEncodeUserInfo(string)

Returns the string that results from URL encoding the provided userInfo as per RFC 3986, which can be null if the input is null.

Parameters
string

userInfo.

Returns
string

String resulting from URL encoding the provided userInfo as per RFC 3986.

More information

Some functions are provided by org.forgerock.openig.el.Functions.

Other functions are provided by org.forgerock.http.util.Uris.