Note

The documentation you're currently reading is for version 2.4.1. Click here to view documentation for the latest stable version.

Jinja

StackStorm uses Jinja extensively for templating. Jinja allows you to manipulate parameter values in StackStorm by allowing you to refer to other parameters, applying filters or refer to system specific constructs (like datastore access). This document is here to help you with Jinja in the context of StackStorm. Please refer to the Jinja docs for Jinja-focused information.

Referencing Datastore Keys in Jinja

You can use {{st2kv.system.foo}} to access key foo from datastore. Note that until v2.1, the expression to access key foo from datastore used to be {{system.foo}} but is now deprecated, and the leading st2kv. namespace is required.

Applying Filters with Jinja

To use a filter my_filter on foo, you use the pipe operator, e.g.: {{foo | my_filter}}. Please pay attention to the data type and available filters for each data type. Since Jinja is a text templating language, all your input is converted to text and then manipulations happen on that value. The necessary casting at the end is done by StackStorm based on information you provide in YAML (for example, type field in action parameters). The casting is a best-effort casting.

StackStorm supports Jinja variable templating in Rules, Action Chains, and Actions etc. Jinja templates support filters to allow some advanced capabilities in working with variables.

Custom Jinja Filters

In addition to the standard filters available in Jinja, StackStorm also comes with some custom filters.

For Developers: These filters are defined in st2/st2common/st2common/jinja/filters/. The equivalent Mistral filters are located in the st2mistral repo at st2mistral/st2mistral/filters/. To ensure filters maintain parity across StackStorm workflows, changes to one location must be replicated to the other in a separate PR.

For brevity, only simple Jinja patterns for each filter are documented below. “Real-world” usage will depend on the type of content where the filters are being applied (sensors, triggers, rules, action and workflows) and their syntax. More detailed examples can be found in the ActionChains in the examples pack: st2/contrib/examples/actions/chains/.

In StackStorm 2.4, all custom filters were made available to Mistral workflows as well, with one notable exception: the decrypt_kv filter. That filter is not necessary in Mistral, as the st2kv function in Mistral workflows natively supports decryption via the decrypt parameter.

Note

Because of a bug in Mistral, these filters do not currently support the “pipe” operator filter format (|) So, instead of '{{ _.input_str | regex_match(_.regex_pattern)}}' you would call the filter like a regular function, moving the previously input value into the first positional argument position: '{{ regex_match(_.input_str, _.regex_pattern)}}'. This will be addressed in a future release.

json_escape

Adds escape characters to JSON strings.

{{value_key | json_escape}}

regex_match

Search for the pattern at beginning of the string. Returns True if found, False if not.

{{value_key | regex_match('x')}}
{{value_key | regex_match("^v(\\d+\\.)?(\\d+\\.)?(\\*|\\d+)$")}}

regex_replace

Replaces substring that matches pattern with provided replacement value (backreferences possible).

Note

When using backreferences you need to escape two \’s in Jinja, hence the 4 \’s.

{{value_key | regex_replace("x", "y")}}
{{value_key | regex_replace("(blue|white|red)", "beautiful color \\\\1")}}

regex_substring

Searches for the provided pattern in a string, and returns the first matched regex group (alternatively, you can provide the desired index).

{{value_key | regex_substring("y")}}
{{value_key | regex_substring("^v(\\d+\\.)?(\\d+\\.)?(\\*|\\d+)$")}}

to_complex

Convert data to JSON string (see to_json_string for a more flexible option)

{{value_key | to_complex}}

to_human_time_from_seconds

Given time elapsed in seconds, this filter converts it to human readable form like 3d5h6s.

{{ value_key | to_human_time_from_seconds}}

to_json_string

Convert data to JSON string.

{{value_key | to_json_string}}

to_yaml_string

Convert data to YAML string.

{{value_key | to_yaml_string}}

use_none

If value being filtered is None, this filter will return the string %*****__%NONE%__*****%

{{value_key | use_none}}

version_bump_major

Bumps up the major version of supplied version field.

{{version | version_bump_major}}

version_bump_minor

Bumps up the minor version of supplied version field.

{{version | version_bump_minor}}

version_bump_patch

Bumps up the patch version of supplied version field.

{{version | version_bump_patch}}

version_compare

Compare a semantic version to another value. Returns 1 if LHS is greater or -1 if LHS is smaller or 0 if equal.

{{version | version_compare("0.10.1")}}

version_equal

Returns True if LHS version is equal to RHS version.

{{version | version_equal("0.10.0")}}

version_less_than

Returns True if LHS version is lesser than RHS version. Both inputs have to follow semantic version syntax.

E.g. {{“1.6.0” | version_less_than("1.7.0")}}.

{{version | version_less_than("0.9.2")}}

version_match

Returns True if the two provided versions are equivalent (i.e. “2.0.0” and “>=1.0.0” are equivalent and will return True).

Supports operators >, <, ==, <=, and >=.

{{version | version_match(">0.10.0")}}

version_more_than

Returns True if LHS version is greater than RHS version. Both inputs have to follow semantic version syntax.

E.g. {{"1.6.0” | version_more_than("1.7.0")}}.

{{version | version_more_than("0.10.1")}}

version_strip_patch

Drops patch version of supplied version field.

{{version | version_strip_patch}}