Working with Jinja2

Oomnitza uses the Jinja2 templating language allow for a diverse array of transformations in order to better facilitate data management and hygeine, as well as complex functions and data transformations.

Using Jinja2 in Oomnitza

API block

Update block

Notification and Approval block

Extended integration

Screen Builder

Jinja Examples

Check if a field is defined (exists)

Check if a field is not empty

Join or group fields

Manipulating data

Documentation

Using Jinja2 in Oomnitza

You can use custom Jinja2 in the following locations in Oomnitza:

• API block
• Update Block
• Notification and Approval block
• Extended integrations
• Screen Builder

You can use Jinja2 to modify any Data Type (such as DateTime, Text, and Decimal).

However, when you are using the Update block, the data type must be set to text. This is because it is only possible to enter a Jinja2 in a text field. For information on creating these fields, refer to Creating custom fields.

Tip
Sometimes you'll want to ensure that data being retrieved is accepted as-is from the external system, such as cases with dates and phone numbers that use the '-' symbol to separate numbers. In these cases, values may be interpreted as math equations instead of strings. To prevent this, "| as_is" can be added to the template to interpret the field as a raw input. For example: {{phone_number | as_is}}.

Using Jinja2 in an API block

You can use custom Jinja2 in Oomnitza workflows to manipulate data and configure mapping. To create an API block workflow:

1. Follow the steps in Creating workflows with the API block. 
2. In the Configure section of the API block window, select the Advanced Mode. 

While in the Advanced Mode of the API block, you can add custom Jinja2 to the following locations:

1. In the URL field in the Information tab.
2. In the URL query parameters in the Params tab.
3. In the HTTP headers in the Headers tab.
4. In the message body in the Body tab.
5. In the Response field in the Response tab. 

Figure 1: An example of a Jinja2 template used in the API Response field where the asset id in the API response is mapped to the Oomnitza ID field. Refer to Check if a field is defined (exists) for more information.

Figure 2: An example of Jinja2 template used in the API URL field to delete a user. The identifier of the user is used to form the URL path.

Figure 3: An example of Jinja2 template used in the Body tab to convert the weight of a package to pounds. 

Using Jinja2 in an Update block

When you select a Update block in a workflow, you can apply Jinja2 to a field you want to update. You can only enter Jinja2 template in a text field. 

Figure 4: An example of a Jinja2 template in an Update block. The block will prepend the value "OOM-" to the Serial Number text field according to the specified rules.

For additional information on Update blocks in Oomnitza, refer to Update block.

Using Jinja2 in a Notification or Approval block

When you select a Notification or an Approval block in a Workflow, you can add Jinja2 in the Message tab to customize the body of your message.

For additional information, refer to Notification block.

Figure 5: An example of a Jinja2 template in a Notification block. The block will convert the email recipient's first name to uppercase.

Using Jinja2 when creating an extended integration

You can use Jinja2 when specifying the mapping in an extended integration. For example, you could use Jinja2 to add a timestamp to a field every time an integration runs:

1. Go to Configuration>Integrations>Overview.
2. Select an existing integration or create a new one.
3. In Mappings, click the Add button in the Connector section.
4. Enter a Field name, for example Last Sync Time, and in the Field path enter the following Jinja2 statement:
   

           {% set datetime = import('datetime') %}
           {% set rightnow = datetime.datetime.utcnow()%}
           {{rightnow}}      

5. Map this to a DateTime field in Oomnitza. When your integration is created, open the DateTime field in the Customization menu and in the Field information screen deselect the Add updates to History checkbox. Otherwise the History tab will update every time the integration runs, which may serve to increase the integration run-time.

Using Jinja2 when customizing the Screen Builder

You can use Jinja2 in the Screen Builder to construct a custom URL that directs you to an external website. For example, you can use the Serial Number of an asset to construct a URL path.

1. Click a record, such as an asset record, and then click Configure the view .
2. Select + Add Link to add a custom link to the top of the field grouping.
3. Enter a Link label, for example: Open in AWS.
4. Enter your Link followed by the field name you want to use to construct the link:

   https://www.yourdomainhere.com/exampleaction?{{serial_number}}

Figure 6: An example of a Jinja2 template link created using the Screen Builder. The link is visible in every asset record and directs the user to an external website, with part of the URL query coming from the {{serial_number}} variable.

Jinja Examples

Check if a field is defined (exists)

The example below checks if an API response and an id exists. If the statement is true then the id is returned.  

{% if response and response.id %}
{{ response.id }}
{% else %}{% endif %}

If the response id is a nested in another JSON value, the above statement can be modified to:

{% if response and response.collection and response.collection.id%}
{{ response.collection.id }}
{% else %}{% endif %}

Check if a field is not empty

You can use a similar check to determine if a field is not empty:

{% if response and response.id|length %}
{{ response.id }}
{% else %}{% endif %}

Join or group fields

It may be necessary to join or group fields, for example, you might wish to group all assets belonging to a user. The below template can be used in a workflow block to group or join items in a list.

{% if response %}
{{ response|map(attribute='model') | list | join(', ') }}
{% else %}{% endif %} 

In the example below, the response will be: Macbook Pro, Dell.

[
  {
    "equipment_id": "123",
    "model": "Macbook Pro",
  }
    {
    "equipment_id": "456",
    "model": "Dell",
  }
]

Manipulating data

You can also add custom Jinja2 to your workflow block to clean or modify the data that is returned in an API response. For example, you could use upper() or capitalize() to convert a value to uppercase or capitalize the first letter in a value.

{% if response and response.name|length %}
{{ response.name.upper()}}
{% else %}{% endif %}

Or combine the Python syntax and Jinja filters to return the first letter of the full name in upper case:

{{full_name.split() | first | capitalize}}

You can find further information on how to customize and create Jinja2 templates by consulting the documentation below.

Documentation

Jinja: Template Designer Documentation

ShellHacks:Jinja2

Jinja2: Live parser

Python Documentation (for supported string methods)

Importing and Using Libraries with Jinja2