--- title: PingGateway functions description: A set of built-in functions to call in PingGateway expressions. component: pinggateway version: 2026 page_id: pinggateway:reference:Functions canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/Functions.html revdate: 2026-01-20T12:00:00Z section_ids: functions-array: array functions-boolean: boolean functions-contains: contains functions-decodeBase64: decodeBase64 functions-decodeBase64url: decodeBase64url functions-derCertificate: derCertificate functions-digestSha256: digestSha256 functions-encodeBase64: encodeBase64 functions-encodeBase64url: encodeBase64url functions-fileToUrl: fileToUrl functions-find: find functions-findGroups: findGroups functions-formDecodeParameterNameOrValue: formDecodeParameterNameOrValue functions-formEncodeParameterNameOrValue: formEncodeParameterNameOrValue functions-indexOf: indexOf functions-integer: integer functions-integer-radix: integerWithRadix functions-ipMatch: ipMatch functions-join: join functions-keyMatch: keyMatch functions-lastElement: lastElement functions-length: length functions-matchesWithRegex: matchesWithRegex functions-pathToUrl: pathToUrl functions-pemCertificate: pemCertificate functions-read: read functions-readProperties: readProperties functions-readWithCharset: readWithCharset functions-split: split functions-toJson: toJson functions-toLowerCase: toLowerCase functions-toString: toString functions-toUpperCase: toUpperCase functions-trim: trim functions-urlDecode: urlDecode functions-urlEncode: urlEncode functions-urlDecodeFragment: urlDecodeFragment functions-urlDecodePathElement: urlDecodePathElement functions-urlDecodeQueryParameterNameOrValue: urlDecodeQueryParameterNameOrValue functions-urlDecodeUserInfo: urlDecodeUserInfo functions-urlEncodeFragment: urlEncodeFragment functions-urlEncodePathElement: urlEncodePathElement functions-urlEncodeQueryParameterNameOrValue: urlEncodeQueryParameterNameOrValue functions-urlEncodeUserInfo: urlEncodeUserInfo functions-javadoc: More information --- # PingGateway functions A set of built-in functions to call in [PingGateway expressions](Expressions.html). ## 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](https://www.rfc-editor.org/rfc/rfc9440.html#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](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/regex/Pattern.html). 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](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/regex/Pattern.html). 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`) 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](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/regex/Pattern.html), 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. ## lastElement ``` lastElement(object) ``` Returns the last element of the collection or array in `object` or `null` if `object` is empty. Returns * object The last element or `null` if empty. ## 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. ## 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](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/regex/Pattern.html). 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. ## 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). By default, Java properties files use UTF-8 encoding. To use deprecated ISO-8859-1 encoding, set the deprecated system property `org.forgerock.config.resolvers.properties.encoding` to `ISO-8859-1`. Include characters you can't directly represent in ISO-8859-1 with [Unicode Escapes](https://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-3.3), as described 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](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/charset/Charset.html). 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](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/regex/Pattern.html). 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](#functions-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](#functions-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](../_attachments/apidocs/org/forgerock/openig/el/Functions.html). Other functions are provided by [org.forgerock.http.util.Uris](../_attachments/apidocs/org/forgerock/http/util/Uris.html).