Templating

Overview

Templating is the process of creating a reusable format or layout for presenting data in a consistent manner. Templating is currently used in Stroom for creating email templates for Analytic Rule detections and Reports.

Stroom's templating uses a sub-set of the template syntax called jinja and specifically the JinJava library. The templating syntax includes support for variables, filters, condition blocks, loops, etc.

When a template is rendered, Stroom will populate the template context with data that can be used by the template.

Basic templating syntax

Jinja templating is very powerful and has a rich language so this is a quick guide to the very basic features. Stroom uses the JinJava templating engine that is based on Jinja templating. Not all feature

See also:

HubSpot's Hubl language also uses the JinJava engine, its documentation may be helpful.

Another reference for jinja templating is here.

Data types

The following data types are available in the Jinja language.

Accessing collection items

A List/tuple item can be accessed by its index (zero based), e.g. fruits[0] returns Apple.

A value in a dictionary can be accessed using its key, e.g. myDict['fruit'] returns Apple. If the key does not contain special characters (with the exception of _, then you can also use this form myDict.fruit to get the same value.

Conditions

Valid conditions are:

• == Compares two objects for equality
• != Compares two objects for inequality
• > true if the left-hand side is greater than the right-hand side
• >= true if the left-hand side is greater or equal to the right-hand side
• < true if the left-hand side is lower than the right-hand side
• <= true if the left-hand side is lower or equal to the right-hand side

Logical operators

The logic operators for use with boolean values are:

• and Boolean and
• or Boolean or
• not Boolean negation

Expressions

Syntax: {{ ... }}

Expressions will render the value of a variable that has been defined in the template context or in a previous statement. An example of a simple value expression is

Template

The detection time is {{detectTime}}.

### Rendered

The detection time is 2024-05-03T09:15:13.454Z.

An expression can also contain variables that are passed through one or more Filters.

Statements

Syntax: {% ... %}

Statements are used to create conditional blocks, loops, define variables, etc.

Setting variables

Syntax: {% set <variable name> = <value or expression> %}

Template

{% set colour = '#F7761F' %}
Colour: {{colour}}
{% set fruits = ["Apple", "Orange"] %}
Top Fruit: {{ fruits | first }}
{% set fullName = "% %" | format(firstName, surname) %}
Name: {{fullName}}

### Rendered

Colour: #F7761F
Top Fruit: Apple
Name: Joe Bloggs

Conditional blocks

Syntax:

{% if <value, variable or expression> <condition> <value, variable or expression> %}
  < optional content, expressions or statements>
{% elif <value, variable or expression> <condition> <value, variable or expression>%}
  < optional content, expressions or statements>
{% else %}
  < optional content, expressions or statements>
{% endif %}

Conditional blocks can be used to optional render content depending on the value of a variable. See conditions for the list of valid conditions.

Template

{% if (values | length) > 0 -%}
This detection has {{ values | length }} values.
{%- else -%}
This detection has no values.
{%- endif -%}

### Rendered

This detection has 10 values.

Loops

Syntax:

{% for <item name> in <variable or expression> %}
  <content, expressions or statements to repeat for each item>
{% endif %}

For loops allow you to loop over items in a list/tuple or entries in a dictionary.

Template

{% for key, val in values | dictsort %}
{{ key }}: {{ val }}
{% endfor %}

### Rendered

fruit: Apple
weight: 320

Filters

Syntax: ... | <filter name>

Filters are essentially functions that take an input and return an output. Some functions have additional parameters to control the behaviour of the function.

Filters can be chained together with the output of one filter becoming the input to the next filter in the chain in the same way that Stroom pipeline elements work.

Some useful filters are:

For a full list of filters see here or here.

Comments

Syntax: {# <comment text> #}

Non-rendered Comments can be added to the template.

Template

{#- Show the time -#}
The detection time is {{detectTime}}.

### Rendered

The detection time is 2024-05-03T09:15:13.454Z.

White space

When JinJava renders the template, each expression or statement is evaluated and then removed or replaced by its output, but any white space around them, e.g. line breaks remain. This can result in unwanted line breaks in the output.

To avoid unwanted white space you can add the - character to the opening and/or closing tag to strip leading/trailing whitespace outside the block, e.g.

• {{ ... }} => {{- ... -}}

• {% ... %} => {%- ... -%}

  Template

{{ firstName -}}
{{ surname }}

### Rendered

JoeBloggs

For a detailed guide to how white space works see here.

Template context

The context is a data structure that contains the dynamic content to use when rendering the template. The variables and values in the context are set by Stroom depending on where the template is being used.

Rule detections context

When an email subject/body template is rendered for an Analytic Rule detection, field values from the detection are placed in the context which allows them to be used in the template.

For example {{ detectTime }} will render the date/time the detection happened. The fields available in the context are those taken from the detection:1 XMLSchema with some additional fields.

The template has access to the following fields from the detection:

A field that is not set on the detection is not in the context at all, rather than being empty, and a template that references a missing field will fail to render. Guard any field that may not be set, e.g. {% if level is defined %}{{ level }}{% endif %} or {{ level | default('') }}.

DetectionLinkedEvent fields:

Report context

When an email subject/body template is rendered for a Report , the context describes the report that was produced rather than a detection.

A Report delivers its data as an attached file, so the context carries facts about that file and about the run that produced it, not the data itself.

aiSummary is always present in the context, so that a template using it renders whether or not a summary was produced.