Using filters in local policy scripts

Local policy manipulates service configuration and media location data by running a jinja2 script against that data.

To assist you in manipulating this data Pexip Infinity supports a subset of filters from the jinja2 templating language and also provides some custom Pexip filters as described below.

Supported jinja2 filters

Pexip Infinity supports a subset of filters from the jinja2 templating language. Any jinja filters that are not listed below have been disabled in Pexip Infinity. See List of Builtin Filters for more information about these filters.

abs float last replace truncate
capitalize format length round upper
default int lower striptags  
first join range trim  

To use a filter you would typically follow the syntax {{<source_value>|<filter_name>}}.

In most cases the <source_value> is likely to be a variable, for example {{ call_info.local_alias|replace("@example.com", "") }}.

Custom Pexip filters

In addition to the jinja filters, Pexip also provides the following custom filters, which are typically used to manipulate data:

Filter Description and example usage
pex_base64

Performs Base64 encoding on the input field.
pex_clean_phone_number

This extracts only +0123456789 characters (and removes ()&%#@|"':;, A-Z,a-z etc).
pex_debug_log(message)

The pex_debug_log filter can be used to help debug your script. It writes debug messages to the Pexip Infinity support log. You can include literal text and variables.

To avoid filling the support log and causing it to rotate, remove all pex_debug_log filters from your scripts as soon as they are working correctly.

Example usage: {{pex_debug_log("Media location policy ", call_info.location, " protocol", call_info.protocol) }}

This will generate a support log entry in the style of: Name="support.jinja2" pex_debug_log Detail="Media location policy ,Oslo, protocol,sip"
pex_find_first_match(string_list, 'find_regex')

This extracts from the list the first value that matches the specified regex.
pex_hash

Performs a hash of a field.
pex_head(maxlength)

Returns, at most, the first maxlength characters from the input field.
pex_in_subnet

Tests whether a given address is within one or more subnets. It takes as input the address you want to test, and one or more subnet ranges, and returns either True or False.

This filter could be useful if, for example, you want to place media in a particular location based upon the network location of the participant. For example:

  • {{pex_in_subnet("10.47.0.1", ["10.47.0.0/16", "10.147.0.0/16"])}} returns True
  • {{pex_in_subnet("10.44.0.1", ["10.47.0.0/16", "10.147.0.0/16"])}} returns False
  • {{pex_in_subnet("2001:658:22a:cafe:ffff:ffff:ffff:ffff", ["2001::/16", "2002::/16"])}} returns True
  • {{pex_in_subnet("2000:758:23a:beef:ffff:ffff:ffff:ffff", ["2001::/16", "2002::/16"])}} returns False

For practical usage you will most likely want to refer to the calling participant's address (call_info.remote_address) instead of literally specifying the address to be tested, for example: {{pex_in_subnet(call_info.remote_address, ["10.44.0.0/16"])}}

See Test whether a participant's address is within a particular subnet for a more advanced example that shows how you can make multiple tests against multiple locations with multiple subnets.
pex_md5

Applies an MD5 hash to the input field.
pex_now(timezone)

The pex_now filter takes an optional parameter of a timezone description e.g. 'UTC', 'Asia/Tokyo', or 'US/Eastern' and returns the current date and time for that timezone. UTC is assumed if a timezone is not provided.

The resulting available attributes are year, month, day, hour, minute, second and microsecond.

Example usage:
{% set now = pex_now("Europe/London") %}
{% if now.month == 2 and now.day == 29 %}

See Use a different theme based on time of day for a full example that shows how to make decisions based on the time of day.
pex_random_pin(length)

Generates a random PIN of the given length. Note that this filter does not take any input.
pex_regex_replace('find_regex', 'replace_string')

This performs a regex find and replace.

Example usage: {{mail|pex_regex_replace('@.+','@otherdomain.com')}}

This example takes as input an email address contained in the mail variable and changes the domain portion of the address to @otherdomain.com. For example, it will transform user1@domainA.com to user1@otherdomain.com, and user2@domainB.com to user2@otherdomain.com etc.

See Regular expression (regex) reference for information about writing regular expressions.
pex_regex_search('regex pattern', 'string_to_search')

This performs a regex search for the first location that matches the pattern and returns the regex groups.

Example usage:

{% set groups = pex_regex_search("([a-z0-9.-]+)@([a-z0-9.-]+.com)", "example string with someone@example.com") %}
{% if groups %}
{{ groups[0] }}@{{ groups[1] }}
{% endif %}

This example takes as input a string containing an email address and extracts the email using two regex groups.

See Regular expression (regex) reference for information about writing regular expressions.
pex_require_min_length(length)

This validates that the input string field has the specified minimum length.

Syntax: {{ some_string|pex_require_min_length(2) }}

When used in local policy, if the input string fails the minimum length requirement, the policy is not applied and the original configuration data is retained unchanged.
pex_reverse

This reverses the characters in the input field.
pex_strlen

Returns the length of string. The basic usage syntax is:

{% set some_length = "Example"|pex_strlen %}
{# sets a variable named some_length to the value 7 #}
pex_tail(maxlength)

Returns, at most, the last maxlength characters from the input field.
pex_to_json

Converts a Python dictionary variable into JSON format.

It can be used to convert the data in the service_config and suggested_media_overflow_locations variables (which are Python dictionaries) into JSON format (which is the required data structure for the configuration data returned to Pexip Infinity) when you want to use those variables in a response result object.

Example usage: {{suggested_media_overflow_locations|pex_to_json}}

The example above converts the suggested_media_overflow_locations variable into JSON format.

Example usage: {{service_config|pex_update({"participant_​limit":10, "ivr_theme_name":"funky"})|pex_to_json}}

This second example combines the pex_update filter with the pex_to_json filter. It makes updates to the service_config variable and then converts it to JSON.

Note that you do not need to use the pex_to_json filter if you are constructing the response result object directly in JSON format (e.g. as shown in the Example service configuration data response).
pex_to_uuid

Converts a base64 string to a UUID.
pex_update

Updates Python dictionary variables.

It can be used to update the service_config (service configuration data) and suggested_media_overflow_locations (media location data) variables.

Example usage: {{service_config|pex_update({"pin":"1234", "guest_pin":"", "allow_guests" : false}) }}

This updates 3 of the data elements in the service_config variable. It sets the pin to 1234, the guest_pin to null and the allow_guests flag to false. (See Service configuration data responses for a list of all of the elements in the service_config variable, and Media location data responses for a list of all of the elements in the suggested_media_overflow_locations variable.)
pex_url_decode

This filter decodes a previously URL-encoded string. For example, it can be used with OTJ custom rules to simplify the regular expressions required.
pex_url_encode

This filter creates URL parameters that are safely URL-encoded.
pex_urldefense_decode

This filter converts a string that has been rewritten by Proofpoint's URL Defense into the original URL.

pex_uuid4()

This generates a uuid (universally unique identifier). Note that this filter does not take any input.