SAS provides predefined Liquid filters that you can use to further process the event data it receives. It runs the filters used in an event when it displays the event.

Important To display the data from your application, SAS assigns relevant values to the static_data or var_data variables, and then renders the Liquid template for the relevant event. For that reason, this section uses the Liquid terminology, instead of the Java terminology, for the description of the filters.

This section lists the filters that you may need when you develop applications with Rhino SAS API.

To use the predefined filters, separate the input value and the filter with a | symbol. Some filters can have additional parameters. To specify them, use a colon (:) followed by a comma-separated list of parameters.

For example, the following template calls the foo filter with three parameters, static_data[0], static_data[1], and static_data[2]:

{{ static_data[0] | foo: static_data[1], static_data[2] }}

You can combine multiple filters. In that case, they are applied from left to right.

Filters for formatting static_data

Data that your application attached to an event using the staticParam() method is available to the Liquid templates in the mini-bundle in the static_data array variable. Without any filters, SAS renders this variable as an unsigned decimal string, or as an empty string if the value is absent.

To format static_data in other forms, use the following filters:

Filter name Description Parameters

boolean

Treats an integer as a Boolean value and then converts the value to a string.

If the integer is 0, it returns "False". Otherwise, it returns "True".

For example, the expression {{ 0 | boolean: "yes", "no" }} returns "no".

  • <input>: The integer to process.

  • [true_string]: A string to specify the value of true. The default value is "True".

  • [false_string]: A string to specify the value of false. The default value is "False".

enum

Gets a value stored in an enumeration variable defined for an event in the mini-bundle.

  • <input>: The key to look up.

  • <enum_name>: The name of the enumeration variable.

float

Formats the input integer as a 32-bit float value.

<input>: The integer to format.

http_status_code_text

Returns the text description for an integer HTTP status code.

For example, the expression {{ 404 | http_status_code_text }} returns "Not Found".

<input>: The integer HTTP status code.

int32

Formats the input integer as a signed integer with optional radix (for example, 10 for decimal) parameter.

  • <input>: The integer to format.

  • [radix]: The parameter that specifies the radix to display the number in. The default value is 10 (decimal).

uint32

Formats the input integer as an unsigned one with optional radix (for example, 10 for decimal) parameter.

  • <input>: The integer to be formatted.

  • [radix]: The parameter that specifies the radix to display the number in. The default value is 10 (decimal).

Filters for formatting var_data

Data that your application attaches to an event using the varParam() method is available to the Liquid templates in the mini-bundle in the var_data array variable. Without any filters, SAS casts the value as UTF-8 encoded text and displays it as such. If the variable value is not valid UTF-8 encoded text, SAS renders it as Invalid UTF-8 String. If the value is absent, SAS renders it as an empty string.

Tip When a Java String is passed to the varParam() method, the corresponding var_data is UTF-8 encoded.

Filters for formatting UTF-8 var_data

To format var_data that is UTF-8 encoded in other forms, use the following filters:

Filter name Description Parameters

append_if_present

Appends an object to another and returns a concatenated string if the first object is present. Otherwise returns an empty string.

  • <input>: The object to check.

  • <append_obj>: The object to append.

append_port

Appends the specified port number to the input IPv4 address/hostname or IPv6 address. For an IPv6 address, the filter adds brackets.

Consider the following example:

{{ var_data[2] | append_port: var_data[3] }}

If the value of var_data[2] is 0000:0000:0000:0000:0000:0000:0000:0001, and the value of var_data[3] is 3000, the result is "[0000:0000:0000:0000:0000:0000:0000:0001]:3000".

  • <input>: The IP address or hostname in any format.

  • <port>: The port number to append to the address.

format_json

Converts the given JSON object to a well-formatted string.

You can use this filter in combination with the read_json filter. For example, with the following code, you read the value of the var_data[3] variable as a JSON object and then convert the object to a well-formatted string:

{{ var_data[3] | read_json | format_json }}

<input>: The JSON object to convert.

if_absent

Returns the specified string if the input value is absent. Otherwise returns the input value.

  • <input>: The input that might be absent.

  • <ret_string>: The string to return if the input is absent.

if_blank

Returns the specified string if the input value is blank. Otherwise returns the input value.

Consider the following example:

body: {{ var_data[2] | if_blank: "No body" }}

In this example, if the value of the var_data[2] variable is abcd, the result is "body: abcd". If the variable is blank, the result is "body: No body".

  • <input>: The input that might be blank.

  • <ret_string>: The string to return if the input is blank.

prepend_if_present

Prepends an object to another and returns a concatenated string if the first object is present. Otherwise returns an empty string.

Consider the following example:

The call was ended{{ var_data[1] | prepend_if_present: " by subscriber " }}.

If the variable var_data[1] is present and its value is 012-345-6789, the result is "The call was ended by subscriber 012-345-6789." If the variable isn’t present, the result is "The call was ended."

  • <input>: The object to check.

  • <prepend_obj>: The object to prepend.

read_json

Converts a string into a JSON object.

For example, after getting the p object with the following code:

{% assign p = var_data[3] | read_json %}

You can print the entire JSON structure with this code:

{{ p }}

Or print a field with this code:

{{ p.field_name }}

<input>: The string to convert.

Filters for formatting other var_data

To format var_data that is not UTF-8 encoded, use the following filters. For example, you may need one of these filters when you pass the contents of a binary encoded message in a byte array to the varParam() method.

Note These filters need to access the raw data form of the input. Don’t use them after other filters because all filters output UTF-8 strings that don’t have a raw data form.
Filter name Description Parameters

as_hex

Converts the input, which may include binary data, into a hexadecimal string.

<input>: The data to convert. It must not be nil.

binary

Interprets the input non UTF-8 data as valid UTF-8 data so that the data can be further processed.

Use this filter when SAS needs to process the results of a template render as binary.

For example, the variable for the data subfield of the call_flow field needs to be passed through this filter, unless the whole message is always valid UTF-8 text. Without the filter, the protocol message is invalid because SAS will cast its value and render it as Invalid UTF-8 String.

Tip Some nominally text-based protocols like SIP and HTTP may have body elements that are not valid UTF-8.

<input>: The raw data to process.

decode_diameter_details

Formats a string as Diameter details.

<input>: The string to format.

decode_diameter_summary

Formats a string as a Diameter summary

<input>: The string to format.

decode_sip_details

Formats a string as SIP details.

<input>: The string to format.

decode_sip_summary

Formats a string as a SIP summary.

  • <input>: The string to format.

  • [protocol_variant]: The protocol variant.

dn

Formats the input string as a directory number.

<input>: The string to format.

dump_as_hex

Dump a byte string as a hexadecimal string. Returns "" if the data is nil.

<input>: The byte string to process.

hex_and_ascii

Formats the input data by displaying it as a hex dump, with corresponding printable ASCII characters alongside.

Use this filter to display blobs of binary data for which a decoder isn’t available.

<input>: The data to format.

ip_addr

Formats the input string’s byte sequence as an IP address.

The filter interprets four bytes as an IPv4 address and 16 bytes as an IPv6 address.

<input>: The string to format.
Previous page