Jinja Template Language

What is Jinja?

We use Jinja2 for rendering data across the app in combination with JsonPath - so both are core concepts to understand. Jinja2, short Jinja, is a template language, based on the programming language Python. It can be used within HTML code and as a simpler alternative to Python in tools such as Locoia.

One of the primary use cases of Jinja is to use it to define and refer to variables. In the first step, a variable is defined in a JSON dictionary:

{
    "name": "John",
    "age": 35
}

In a text, you can now refer to those variables by using double curly bracket ( {{ … }} ), such as:

Hello {{ name }}!

This will output: Hello John!

Logic, such as if-else logic, can also be used in Jinja:

{% if age >= 30 %}
   {{ name }} is 30 years or older.
{% else %}
   {{ name }} is less than 30 years old.
{% endif %}

Based on the variables defined above, this would output: John is 30 years or older.

How Jinja is used in Locoia

Jinja has three main purposes in Locoia

1. Referencing to previous steps and connectors in a flow

2. Using functions and filters to format and change data

3. Adding advanced logic to flow steps which cannot be easily done with existing flow helpers

1. Referencing to previous steps and connectors in a flow

Similar to the variables example stated above, Jinja can be used within Locoia to reference to previous steps in a flow. For example, the flow could consist of a Dict Helper and Freshsales Connector:

Example Flow

The Dict Helper (dic1), in this example, contains the following dictionary:

{
    "firstName": "john",
    "lastName": "Doe",
    "email": "[email protected]"
}

In order to refer to those values in the Freshsales Connector, Jinja needs to be used. To do so, one needs to enter the entire path to the value which should be referred to. The path, in this example, consists of:

1. The reference to the connector (in this case dic1)

2. The key within the dictionary (e.g., firstName)

The elements of the path are separated by dots, and the entire path is wrapped in double curly brackets. By using that schema, the reference to the first name is:

{{ dic1.firstName }}

The references to the fields are written into the Freshsales connector, such as:

References in Freshsales Connector

When the flow is run, the Freshsales connector receives the following input data:

{
  "contact": {
    "first_name": "john",
    "last_name": "Doe",
    "email": "[email protected]"
  }
}

You can find out more about referencing using Jinja here.

2. Using functions and filters to format and change data

Functions and filters in Jinja are similar to Excel functions; they can, for example, change date formats, replace certain words and letters, or capitalize words.

In the previous example, the first name is given in lower case ("john") by the dict helper; in order to send "John" to Freshales, i.e., capitalizing the first letter of a word, one can make use of the Jinja capitalize filter. Using a filter is as simple as using a pipe (|) after the variable which should be changed:

{{ dic1.firstName | capitalize }}

When the flow is run, the Freshsales connector now receives the following input data:

{
  "contact": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  }
}

3. Adding advanced logic to flow steps which cannot be easily done with existing flow helpers

Sometimes one might want to use logic in a connector input to change the input depending on the inserted value.

For example, it could be checked if the email contains the @ symbol, and if that is the case, the email is inserted into the field; otherwise, a comment and the email is inserted into the email field. This can be done by using a Jinja if-else statement in combination with the Jinja in test:

{% if '@' in dic1.email %}
   {{ dic1.email }}
{% else %}
   Check for the correct E-Mail! {{ dic1.email }}
{% endif %}

If the email would not contain an @ symbol, e.g., john.doeexample.com, the Freshsales connector would receive the following input data for the email field:

Check for the correct E-Mail! john.doeexample.com

Filtering a list by a list

Based on the list below (L1), you want to filter another list (L2) and only get the domains back from L1 which are starting with L2.

L1:

[
  "[email protected]",
  "[email protected]",
  "[email protected]",
  "[email protected]"
]

L2:

[ "questions@", "legal@" ]

Solution:

{% set emails = L1 %}
{% set white_list = L2 %}
[
  {% for email_beginning in white_list %}
    {% for email in emails %}
        {% if email_beginning in email %}
             "{{ email }}",
        {% endif %}
    {% endfor %}
  {% endfor %}
]

Further Information

The official documentation, which includes most of the Jinja functions which you can use in Locoia as well as extensive explanations of the correct syntax, can be found here.

In order to test your Jinja code, you can use a third party Jinja playground. Please note that you should not enter any confidential information (such as company or customer data) in such tools, as they might store your input data.