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


BWC uses Jinja extensively for templating. 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 the Jinja docs for Jinja-focused information.

Referencing Datastore Keys in 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, 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 BWC based on information you provide in YAML (for example, type field in action parameters). The casting is a best-effort casting.

BWC 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, BWC 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 BWC 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.


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.


Adds escape characters to JSON strings.

{{value_key | json_escape}}


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


Replaces substring that matches pattern with provided replacement 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")}}


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


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

{{value_key | to_complex}}


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

{{ value_key | to_human_time_from_seconds}}


Convert data to JSON string.

{{value_key | to_json_string}}


Convert data to YAML string.

{{value_key | to_yaml_string}}


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

{{value_key | use_none}}


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


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


Returns True if LHS version is equal to RHS version.

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


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


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


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


Drops patch version of supplied version field.

{{version | version_strip_patch}}