Note

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

Jinja

StackStorm uses Jinja extensively for templating. By now, you would have seen how to use jinja templates in YAML files for rules, actions, action chains and workflows. 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 Jinja docs for Jinja specific documentation.

For brevity, the jinja patterns are only documented. Usage of these patterns inside YAML is subject to understanding the YAML for each content type (sensors, triggers, rules, action and workflows) and their syntax.

Accessing datastore items with 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.

Applying filters with Jinja

Aside from standard filters available in Jinja, StackStorm supports custom filters as well, see Custom Jinja Filters. To use a filter my_filter on foo, simply do {{foo | my_filter}}. Please pay attention to 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 them. 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.

The current supported filters are grouped into following categories.

Note

For Developers: The filters are defined in st2/st2common/st2common/jinja/filters/.

Operator Description
to_json_string Convert data to JSON string.
to_yaml_string Convert data to YAML string.
to_human_time_from_seconds Given time elapsed in seconds, this filter converts it to human readable form like 3d5h6s.
decrypt_kv Decrypt a system scoped datastore item
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_more_than Returns if LHS version is greater than RHS version. Both input has to follow semantic version syntax. E.g. {{“1.6.0” | version_more_than(“1.7.0”)}}.
version_less_than Returns if LHS version is lesser than RHS version. Both input has to follow semantic version syntax. E.g. {{“1.6.0” | version_less_than(“1.7.0”)}}.
version_equal_than Returns if LHS version is equal to RHS version.
version_bump_major Bumps the major version and returns new version.
version_bump_minor Bumps the minor version and returns new version.

Examples of how to use filters are available in st2/contrib/examples/actions/chains/data_jinja_filter.yaml, st2/contrib/examples/actions/chains/time_jinja_filter.yaml, st2/contrib/examples/actions/chains/data_jinja_filter.yaml, and st2/contrib/examples/actions/chains/version_jinja_filter.yaml.

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

Custom Jinja Filters

Filters with regex support

Makes it possible to use regex to search, match and replace in expressions.

regex_match

match pattern at the beginning of expression.

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

regex_replace

replace a pattern matching regex with supplied 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")}}

Filters to work with version

Filters that work with semver formatted version string.

version_compare

compares expression with supplied value and return -1, 0 and 1 for less than, equal and more than respectively

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

version_more_than

True if version is more than supplied value

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

version_less_than

True if version is less than supplied value

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

version_equal

True if versions are of equal value

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

version_match

True if versions match. Supports operators >,<, ==, <=, >=.

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

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_strip_patch

Drops patch version of supplied version field

{{version | version_strip_patch}}