PingGateway 2024.9

Transformations

A set of built-in transformations are available to coerce strings to other data types. The transformations can be applied to any string, including strings resulting from the resolution of configurations tokens.

After transformation, the JSON node representing the transformation is replaced by the result value.

The following sections describe how to use transformations, and describe the transformations available:

Usage

{
   "$transformation": string or transformation
}

A transformation is a JSON object with a required main attribute, starting with a $. The following example transforms a string to an integer:

{"$int": string}

The value of a transformation value can be a JSON string or another transformation that results in a string. The following example shows a nested transformation:

{
  "$array": {
    "$base64:decode": string
  }
}

The input string must match the format expected by the transformation. In the previous example, because the final transformation is to an array, the input string must be a string that represents an array, such as "[ \"one\", \"two\" ]".

In the first transformation, the encoded string is transformed to a base64-decoded string. In the second, the string is transformed into a JSON array, for example, [ "one", "two" ].

array

{"$array": string}

Returns a JSON array of the argument.

Argument Returns
string

String representing a JSON array.
array

JSON array of the argument.

The following example transformation results in the JSON array [ "one", "two" ]:

{"$array": "[ \"one\", \"two\" ]"}

bool

{"$bool": string}

Returns true if the input value equals "true" (ignoring case). Otherwise, returns false.

Argument Returns
string

String containing the boolean representation.
boolean

Boolean value represented by the argument.

If the configuration token &{capture.entity}" resolves to "true", the following example transformation results in the value true:

{"$bool": "&{capture.entity}"}

decodeBase64

{
  "$base64:decode": string,
  "$charset": "charset"
}

Transforms a base64-encoded string into a decoded string. If $charset is specified, the decoded value is interpreted with the character set.

Argument Parameters Returns
string

Base64-encoded string.
$charset

The name of a Java character set, as described in Class Charset.
string

Base64-decoded string in the given character set.

The following example transformation returns the Hello string:

{
 "$base64:decode": "SGVsbG8=",
 "$charset": "UTF-8"
}

encodeBase64

{
  "$base64:encode": string,
  "$charset": "charset"
}

Transforms a string into a base64-encoded string. Transforms to null if the string is null.

If $charset is specified, the string is encoded with the character set.

Argument Parameters Returns
string

String to encode with the given character set.
$charset

The name of a Java character set, as described in Class Charset.
string

Base64-encoded string.

int

{"$int": string}

Transforms a string into an integer.

If the parameter is not a valid number in radix 10, returns null.

Argument Returns
string

String containing the integer representation.
int

Integer value represented by the argument.

The following example transformation results in the integer 1234:

{"$int": "1234"}

list

{"$list": string}

Transforms a comma-separated list of strings into a JSON array of strings

Argument Returns
string

A string representing a comma-separated list of strings.
array

The JSON array of the provided argument. Values are not trimmed of leading spaces.

The following example transformation results in the array of strings ["Apple","Banana","Orange","Strawberry"]:

{"$list": "Apple,Banana,Orange,Strawberry"}

The following example transformation results in the array of strings ["Apple"," Banana"," Orange"," Strawberry"], including the untrimmed spaces:

{"$list": "Apple, Banana, Orange, Strawberry"}

The following example transformation results in the array of strings ["1","2","3","4"], and not an array of JSON numbers [1,2,3,4]:

{"$list": "1,2,3,4"}

number

{"$number": string}

Transform a string into a Java number, as defined in Class Number.

Argument Returns
strings

A string containing the number representation.
number

The number value represented by the argument.

The following example transformation results in the number 0.999:

{"$number": ".999"}

object

{"$object": string}

Transforms a string representation of a JSON object into a JSON object.

Argument Returns
string

String representation of a JSON object.
object

JSON object of the argument.

The following example transformation

{"$object": "{\"ParamOne\":{\"InnerParamOne\":\"InnerParamOneValue\",\"InnerParamTwo\": false}}"}

results in the following JSON object:

{
  "ParamOne": {
    "InnerParamOne": "myValue",
    "InnerParamTwo": false
  }
}

string

{"$string": placeholder string}

Transforms a string representation of a JSON object into a placeholder string. Placeholder strings are not encrypted.

Use this transformation for placeholder strings that that must not be encrypted.

Argument Returns
string

String representation of a JSON object.
placeholder string

Placeholder string.

This example transformation:

{
  "someAttributeExpectingString": { "$string": "&{ig.instance.dir}" }
}

results in this JSON object:

{
  "someAttributeExpectingString": "/path/to/ig"
}