Templating V2

Templating allows you to insert content from an action or trigger output into another action field, for example:

{{ step0:Body.supplierId }}

Templating V2 extends this concept to allow advanced transformation of data using Liquid templating and removing the need for external services.

Breaking changes

The following breaking changes are introduced by moving to the new V2 templating:

Enabling Templating V2

The templating V2 version is enabled by default when you create a new flow. It is disabled for legacy flows created before templating was introduced, but you can enable it. Templating V1 is considered deprecated, and legacy flows will continue to use it unless they are migrated.

Note:

  • There are some breaking changes and your flow may stop working properly. See Breaking changes for more information.
  • Old references (using {{ stepX:x.x }}) will be invalidated and you must manually change them to the new format.

Enable TemplatingV2

The Liquid templating language in Extension Kit

The implemented templating language in Extension Kit aims to comply with the Liquid templating language, but it contains some custom functions to provide additional functionality and certain Liquid functions are adapted to better suit Extension Kit requirements. See the official Liquid documentation for information about the language and features available.

Liquid filters support in Extension Kit

Filters change the output of a Liquid object, and are used within an output and separated by a |.

Some examples of different filters:

Here you will find a list of the supported filters. For more information see the Liquid documentation.

Supported: ✅ | Not supported: ❌ | Differs from standard Liquid, see this documentation for details: ⚠️

Name Supported Comments
abs ✅
append ✅
at_least ✅
at_most ✅
capitalize ✅
ceil ✅
date ✅/⚠️ In Extension Kit, you must use the date.to_string <datetime> <pattern> <culture> filter. See Date for more details.
default ✅
divided_by ✅
downcase ✅
escape ✅
escape_once ✅ If the string already contains escaped characters, they are not modified further, for example:

{{ "1 &lt; 2 &amp; 3" | escape_once }} -> 1 &lt; 2 &amp; 3
first ✅
floor ✅
join ✅
last ✅
lstrip ✅
map ✅
minus ✅
modulo ✅
newline_to_br ✅
plus ✅
prepend ✅
remove ✅
remove_first ✅
replace ✅
replace_first ✅
reverse ✅
round ✅
rstrip ✅
size ✅
slice ✅
sort ✅
sort_natural ✅
split ✅
strip ✅
strip_html ✅
strip_newlines ✅
times ✅
truncate ✅
truncatewords ✅
uniq ✅
upcase ✅
url_decode ✅
url_encode ✅/⚠️ The function url_encode requires the word html in order to work. It converts any URL-unsafe character in a string into percent-encoded characters, for example:

{{ "Tetsuro Takara" | html.url_encode }} => "Tetsuro%20Takara"
where ✅

Default flow variables

A flow has the following variables set up as default:

Templating default variables

This can be extended with additional values provided by the team.

Additional functions

By default we include additional builtin functions attached to the different data types. To use them you must include the data type they belong to, for example:

Existing data types:

Date

To use the date filter you must take into consideration a difference with the date filter provided in the Liquid documentation.

In Liquid, you can use date in the following way: | {{ step1.Body.publishedDate | date: "%a, %b %d, %y" }}

Instead, in Extension Kit, you must use the date.to_string <datetime> <pattern> <culture> filter.

Example: {{ step1.Body.publishedDate | date.to_string '%d %b %Y' }} or {{ date.now | date.to_string '%d %b %Y' }}

Also, you can parse dates that come in a string format, for example: {{ date.parse '2016/01/05' }}. A full example of a parse plus a format could be:

{{ date.parse step0.Body.date | date.to_string '%a, %b %d, %y' }} where step0.Body.date equals '2020/10/10'. The result is Sat, Oct 10, 20.

There are a lot of additional functions you can use with the date object:

Also, it is possible to set dates from the past for all date.add functions, for example:

{% assign myDate = date.now | date.add_days (-1) %}

For more information, see the sriban built-in date functions documentation.

Custom Liquid functions and enhanced operations

The following custom Liquid functions and enhanced operations are available:

array.each

The array.each function iterates over each string in the array to perform a specified action. For example, to remove any leading and trailing whitespace directly in the original array:

array.each @string.strip

array_strip

The array_strip function removes all leading and trailing whitespaces from the given array and returns a new array. 

{% ["     ", "   too many spaces           "] | array_strip %}  => ["", "too many spaces"]

size_in_bytes

The size_in_bytes function returns the size in bytes of a file or string that is passed to it.

Examples of how the size_in_bytes function is used within a Liquid template are shown below:

{{step0.Body | size_in_bytes}}

{{size_in_bytes "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed rhoncus odio dui, eu feugiat enim lobortis vel." }}

zip / unzip

You can include zip and unzip functions within a Liquid templating script to zip and unzip large files before sending and receiving.

When a file is unzipped and it is a binary file, it is converted to Base64, otherwise it is not encoded and the plain text, XML or JSON is passed on etc.

Note that the zip and unzip functions use gzip compression and gunzip decompression.

Examples of how the zip and unzip functions are used within a Liquid template are shown below:

{{zip step1.FileContent}}

{{unzip step2.Output}}

You can set a limit on the size of the file to be zipped as shown in the example below, where only files larger than 5 Mbytes are zipped.

Zip file if size condition met

Technical points to note

Negative numbers

In Liquid operations, when a number is considered negative you must to wrap it in parantheses.

Example:

{{ 4.9901 | at_most: (-4.9901) }}

Splitting strings into individual characters

Using the default string.split or split filter does not allow to split strings to individual characters. For that, using the regex.split filter is recommended.

Example:

{% assign result = '12345' | regex.split "" }} => ['1', '2', '3', '4', '5']

Using variables that contain special characters

The Liquid documentation states the following about variables containing special characters:

Variables: The most basic kind of expression is just the name of a variable. Liquid variables are named like Ruby variables. They must:

In case that you need to access a variable that is not a valid Liquid variable name, you can use the following syntax:

step1.Response["1variable-with-unsupported$chars"]

Example:

❌ Incorrect

{{ step1.Response.value-with-hypens }}

✅ Correct

{{ step1.Response["value-with-hypens"] }}