Templating V2

Templating allows to insert content from an action or trigger output in another action fields. For example:

{{ step0:Body.supplierId }}

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

Breaking changes

With the new templating we make some breaking changes with the previous system:

• Templating format changes: {{ step0:Body.supplierId }} => {{ step0.Body.supplierId }}
• Now you can use templating inside Filters and Conditions (left and right operands) but you must provide the curly braces.

Enabling Templating V2

The new templating system is enabled by default when creating a new flow. You can revert back to templating v1 in the "Preview Features" section of the flow Overview. Templating v1 will be considered deprecated, old flows will continue to use it unless they are migrated and new flows will use the new version by default.

⚠️ Be mindful that there are some breaking changes and your flow may stop working properly. Look at Breaking Changes section for more information.

• Old references (using {{ stepX:x.x }}) will be invalidated, you have to manually change them to the new format.

The Liquid templating language

The implemented templating language in Extension Kit tries to be compliant with the Liquid templating language, you can find more information about the language and features available in the Liquid official documentation.

Liquid filters support in Extension Kit

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

Some examples of different filters:

• {{ "TEST STRING" | downcase }} => "test string"
• {{ "Name Surname" | split: " " | first }} => Name

Here you will find a list of the supported filters, for more information, visit the Liquid documentation.

Supported: ✅ | Not supported: ❌ | Differs from Liquid documentation, check this documentation: ⚠️

Name	Supported
abs	✅
append	✅
at_least	❌
at_most	❌
capitalize	✅
ceil	✅
date	✅/⚠️
default	✅
divided_by	✅
downcase	✅
escape	✅
escape_once	❌
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	❌
where	❌

Default flow variables

A flow has variables setup by default, those are:

• Unique identifier of the current tenant TenantId {{ defaultVariables.tenantId }}
• Unique identifier of the flow currently running FlowId {{ defaultVariables.flowId }}
• Unique identifier of the current run of the flow RunId {{ defaultVariables.runId }}
• Unique identifier of the current distributed trace. It is created from the incoming traceparent when the flow is triggered, if it is not triggered with a traceparent a new one is generated. It is propagated to external systems on http calls and messages. {{ defaultVariables.operationId }}
• A parameters object that contains the Tenant parameters.

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 will have to include the data type they belong to, for example:

• {{ string.capitalizewords "example text" }}
• {{ [1, 2, 3] | array.add 4 }}
• {{ product | object.has_key "title" }}

Existing data types:

• array
• date
• html
• math
• object
• regex
• string
• timespan

Date

To use the date filter we 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:

• date.now
• date.add_days
• date.add_months
• date.add_years
• date.add_hours
• date.add_minutes
• date.add_seconds
• date.add_milliseconds
• date.parse
• date.to_string

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 and additional documentation, please visit the Date documentation.

Custom Liquid functions

The following custom Liquid functions are available:

• zip used to zip a file
• unzip used to unzip a file
• size_in_bytes used to return the size of a string or file in bytes

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:

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.

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 is shown below:

FAQ

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.

For example:

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

Using variables that contain special characters

As the Liquid documentation shares:

Variables: The most basic kind of expression is just the name of a variable. Liquid variables are named like Ruby variables. They should: - Consist of alphanumeric characters and underscores - Always start with a letter - Not having any kind of leading sigil (that is, they look like var_name, not $var_name)

In case that you need to access a variable that is not a valid Liquid variable name, you can use the step1.Response["1variable-with-unsupported$chars"] syntax.

For example:

❌ Incorrect

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

✅ Correct

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