Filters
Oftentimes data may be tokenized in one format, but you wish to use this data in a different format within a request. Several pieces of data may be stored together in a single token (e.g. a user record containing first and last names and contact information), but you wish to only use a single piece of that data within a Proxy or Reactor request, or you may wish to reformat the data before indexing it for search (e.g. use only the last name, but normalize by uppercasing it).
To allow you complete flexibility, transformation functions called filters can be applied within any expression.
Generally, a variable's value can be transformed by specifying a filter after the | symbol:
{{ <variable> | <filter> }}
You can effectively think of this as "piping" a variable into the filter in the same way you may be familiar with the "pipe" operator from Unix-like systems.
Multiple filters can be chained together by "piping" the result of each filter into the next, applying in order from left to right:
{{ <variable> | <filter1> | <filter2> | ... }}
All standard Liquid filters are supported within expressions.
For example, given a token containing a name object containing both first and last name properties:
{
"data": {
"name": "John Doe"
},
...
}
We can create an expression to return the upper-cased last name by splitting on the space character, grabbing the last element, and upper-casing:
{{ data.name | split: ' ' | last | upcase }}
This expression would evaluate to the value "DOE".
In addition to the standard Liquid filters, several custom filters are also available:
alias_preserve_format
Randomly generates a unique alias that preserves the format of the input string, optionally revealing a specified number of characters from the beginning and end of the value.
Alpha characters are replaced with randomized alpha characters, numeric characters are replaced with randomized numeric characters, and special characters and whitespace are preserved.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | reveal_first_length | int | false | 0 | The number of characters to reveal from the beginning of the value |
| 1 | reveal_last_length | int | false | 0 | The number of characters to reveal from the end of the value |
Examples
Given a token with the data:
{
"id": "<expression>",
"type": "token",
"data": "ABC12345DEF67890"
}
| Expression | Example Result |
|---|---|
{{ data | alias_preserve_format }} | "xir83203hqn73599" |
{{ data | alias_preserve_format: 3 }} | "ABC83203hqn73599" |
{{ data | alias_preserve_format: 0, 5 }} | "xir83203hqn67890" |
{{ data | alias_preserve_format: 3, 5 }} | "ABC83203hqn67890" |
alias_preserve_length
Randomly generates a unique alias that preserves the length of the input string, optionally revealing a specified number of characters from the beginning and end of the value.
All characters are replaced with randomized alphanumeric characters. The type of the character in each position is not preserved, e.g. alpha characters may be replaced with numeric characters and vice versa. Special characters and whitespace are not preserved and will be replaced with alphanumeric characters.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | reveal_first_length | int | false | 0 | The number of characters to reveal from the beginning of the value |
| 1 | reveal_last_length | int | false | 0 | The number of characters to reveal from the end of the value |
Examples
Given a token with the data:
{
"id": "<expression>",
"type": "token",
"data": "ABC12345DEF67890"
}
| Expression | Example Result |
|---|---|
{{ data | alias_preserve_length }} | "v38anr9m2cx0giw7" |
{{ data | alias_preserve_length: 3 }} | "ABCanr9m2cx0giw7" |
{{ data | alias_preserve_length: 0, 5 }} | "v38anr9m2cx67890" |
{{ data | alias_preserve_length: 3, 5 }} | "ABCanr9m2cx67890" |
json
Evaluates a JSON Path expression (proposed spec) on the input object.
All standard JSON Path syntax is supported, provided that the expression resolves to a single value. If the expression resolves to multiple values, the request will result in a 400 error.
While Liquid supports a very similar syntax to JSON path when selecting properties within a JSON object (e.g. {{ data.bicycle.color }}),
it does not support more complex JSON Path expressions (e.g. array filter expressions like $.books[?(@.price < 10)].title).
The json filter provides further flexibility for evaluating complex JSON Path expressions.
Parameters
| Position | Name | Type | Required | Description |
|---|---|---|---|---|
| 0 | json_path_expression | string | true | A JSON Path expression |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"books": [
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fantasy",
"author": "J. R. R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
],
"bicycle": {
"color": "red",
"price": 19.95
}
}
}
| Expression | Result |
|---|---|
{{ data.bicycle.color }} | "red" |
{{ data | json: '$.bicycle.color' }} | "red" |
{{ data.bicycle }} | { "color": "red", "price": 19.95 } |
{{ data | json: '$.books[0].author' }} | "Herman Melville" |
{{ data | json: '$.books[?(@.price < 10)].title' }} | "Moby Dick" |
{{ data.nonexistent }} | null |
{{ data | json: '$.book..author' }} | <400 Error> |
last4
Returns the last 4 characters of a string. If the string's length is less than 4, the whole value is returned.
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "36227206271667"
}
| Expression | Result |
|---|---|
{{ data | last4 }} | "1667" |
{{ data | slice: 12, 2 | last4 }} | "67" |
reveal
Returns a masked version of the string revealing characters at the start and end whilst preserving others. If the string's
length is less than or equal to reveal_first + reveal_last, or the resulting masked string equals the original unmasked value,
the whole value is masked.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | reveal_first | int | false | 0 | The number of characters to reveal at the start |
| 1 | reveal_last | int | false | 0 | The number of characters to reveal at the end |
| 2 | mask_char | char | false | X | A masking character |
| 3 | preserve_chars | string | false | `` | The characters to preserve |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "3622-7206-2716-5567"
}
| Expression | Result |
|---|---|
{{ data | reveal: 6 }} | "3622-7XXXXXXXXXXXXX" |
{{ data | reveal: 7, 5 }} | "3622-72XXXXXXX-5567" |
{{ data | reveal: 7, 5, '#' }} | "3622-72#######-5567" |
{{ data | reveal: 7, 4, '#', "-" }} | "3622-72##-####-5567" |
{{ data | reveal: 10, 9 }} | "XXXXXXXXXXXXXXXXXXX" |
pad_left
Returns a new string of the desired length by padding the input string on the left with the specified padChar.
Returns null when provided a null input value.
Parameters
| Position | Name | Type | Required | Description |
|---|---|---|---|---|
| 0 | length | int | true | The number of characters in the resulting string |
| 1 | pad_char | char | true | A padding character |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "1234"
}
| Expression | Result |
|---|---|
{{ data | pad_left: 6, '0' }} | "001234" |
{{ data | pad_left: 6, 'X' }} | "XX1234" |
{{ data | pad_left: 4, '0' }} | "1234" |
{{ data | pad_left: 2, '0' }} | "1234" |
pad_right
Returns a new string of the desired length by padding the input string on the right with the specified padChar.
Returns null when provided a null input value.
Parameters
| Position | Name | Type | Required | Description |
|---|---|---|---|---|
| 0 | length | int | true | The number of characters in the resulting string |
| 1 | pad_char | char | true | A padding character |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "1234"
}
| Expression | Result |
|---|---|
{{ data | pad_right: 6, '0' }} | "123400" |
{{ data | pad_right: 6, 'X' }} | "1234XX" |
{{ data | pad_right: 4, '0' }} | "1234" |
{{ data | pad_right: 2, '0' }} | "1234" |
reveal_last
Returns the last length characters of a string. If the string's length is less than or equal to length, the whole value is returned.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | length | int | true | null | The number of characters to reveal |
| 1 | mask_char | char | false | X | A masking character |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "36227206271667"
}
| Expression | Result |
|---|---|
{{ data | reveal_last: 6 }} | "XXXXXXXX271667" |
{{ data | reveal_last: 3, '#' }} | "###########667" |
stringify
Returns a JSON serialized string of the input object.
Returns null when provided a null input value.
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"books": [
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fantasy",
"author": "J. R. R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
],
"bicycles": [
{
"color": "red",
"price": 19.95
},
{
"color": "blue",
"price": 24.95
}
]
}
}
| Expression | Result |
|---|---|
{{ data.books[0].price | stringify }} | "8.99" |
{{ data.books[1].title | stringify }} | "The Lord of the Rings" |
{{ data.bicycles[1] | stringify }} | "{\"color\":\"red\",\"price\":19.95}" |
{{ data.bicycles | stringify }} | "[{\"color\":\"red\",\"price\":19.95},{\"color\":\"blue\",\"price\":24.95}]" |
to_boolean
Casts the input value to a boolean value.
Returns null when provided a null input value. Returns an error when the input cannot be cast to a boolean.
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"true_string": "true",
"false_string": "false"
}
}
| Expression | Result |
|---|---|
{{ data.true_string | to_boolean }} | true |
{{ data.false_string | to_boolean }} | false |
to_number
Casts the input value to a numeric value.
Returns null when provided a null input value. Returns an error when the input cannot be cast to a number.
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"int_string": "42",
"decimal_string": "3.14159"
}
}
| Expression | Result |
|---|---|
{{ data.int_string | to_number }} | 42 |
{{ data.decimal_string | to_number }} | 3.14159 |
to_string
Casts the input value to a string value.
Returns null when provided a null input value. Returns an error when the input cannot be cast to a string (e.g. for complex object values).
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"numeric_value": 3.14159,
"boolean_value": true,
"string_value": "foo"
}
}
| Expression | Result |
|---|---|
{{ data.numeric_value | to_string }} | "3.14159" |
{{ data.boolean_value | to_string }} | "true" |
{{ data.string_value | to_string }} | "foo" |