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


BWC 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 BWC 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 BWC. 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 {{}} to access key foo from datastore. Note that until v2.1, the expression to access key foo from datastore used to be {{}} but is now deprecated.

Applying filters with Jinja

Aside from standard filters available in Jinja, BWC 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 BWC 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.


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.

BWC supports Jinja2 variable templating in Rules, Action Chains and Actions etc. Jinja2 templates support filters to allow some advanced capabilities in working with variables. BWC 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.


match pattern at the beginning of expression.

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


replace a pattern matching regex with supplied value (backreferences possible)


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.


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


True if version is more than supplied value

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


True if version is less than supplied value

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


True if versions are of equal value

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


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

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


Bumps up the major version of supplied version field

{{version | version_bump_major}}


Bumps up the minor version of supplied version field

{{version | version_bump_minor}}


Bumps up the patch version of supplied version field

{{version | version_bump_patch}}


Drops patch version of supplied version field

{{version | version_strip_patch}}