Jinja2 templates and filters

Pexip Infinity uses a subset of the jinja2 templating language (http://jinja.pocoo.org/docs/dev/) to assist in creating content or deciding on processing logic when:

Template content

Jinja2 templates are made up of the following elements:

  • literal text that you want to add to the output or result, such as prefixing every generated VMR name with meet.
  • variables that are either locally defined within the script or template, or that are provided automatically according to the context in which the template is being used, for example there is a call_info variable when configuring local policy), or a givenName variable when syncing VMRs via LDAP.
  • filters that can manipulate text or modify the content of variables or text strings, such as join, pex_update or pex_to_json
  • delimiters such as {{...}} and pipes | which are used to enclose variables and define filter expressions
  • jinja statements and control structures (see http://jinja.pocoo.org/docs/dev/templates/#list-of-control-structures)

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 http://jinja.pocoo.org/docs/dev/templates/#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 {{givenName|upper}}, although it could be one or more literal values, for example {{ [1, 2, 3, 4]|join }}.

Some filters take parameters, for example {{sn|truncate(5)}}. You can also use multiple filters in the same expression, for example {{sn|truncate(5)|upper}}.

The trim filter is often used. This trims leading and trailing whitespace from the string held in the <source_value>.

Example usage: {{title|trim}}

If the title field contained "   Project Manager   ", this would be converted to "Project Manager".

The replace filter is also often used. This replaces one string with another string. The first argument of the filter is the substring that should be replaced, the second is the replacement string. If the optional third argument count is given, only the first count occurrences are replaced.

Example usage: {{ department|replace("Personnel", "HR") }}

If the department field contained "Personnel Department Personnel", this would be converted to "HR Department HR".

Example usage: {{ department|replace("Personnel", "HR", 1) }}

In this case a count of 1 is specified, thus if the department field contained "Personnel Department Personnel", it would be converted to "HR Department Personnel".

For more complicated search and replace patterns, use the custom Pexip pex_regex_replace filter described below.

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.

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.

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 %}

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) }}

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.

pex_to_uuid

Converts a base64 string to a UUID.

pex_update

Updates Python dictionary variables.

pex_url_encode

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

pex_uuid4()

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

Further contextual examples of how to use these filters can be found in Using filters in local policy scripts, Example local policy scripts and Using templates, variables and filters when provisioning VMRs, devices and users.