​
Templated Outputs

This guide assumes that you are already familiar with the basics of creating an agent and setting up extractions.

If you’d like to follow along, the files used in this guide may be downloaded here.

​
Setting up a Template

Kolena allows you to generate a well-formatted file using a docx template file for formatting and structure.

​
Creating a Template File

The template file allows you to insert values from an Agent Run. The template generator will look for placeholder fields in the docx file surrounded by curly braces and a space, such as {{ field_name }}. Note that template fields must be lowercased, with spaces and special characters replaced with an underscore character (_).

Kolena will preserve the font and format of the placeholder fields. For example, if your field is {{ company_name }} in bolded, size 24, Times New Roman and your Agent Run has Company Name extracted as Kolena Inc, the templated output field will be Kolena Inc, also in bolded, size 24, Times New Roman.

All values in the template files that are not in placeholder fields (such as text, images, and borders) will be preserved as is.

​
Uploading a Template File

Now that we’ve created a template file, we can upload it to our Agent:

  1. Navigate to the Agent for which the template applies
  2. Click on the Output card to fully expand it
  3. Click on the “Set Template” button
  4. Drag and drop the template docx file onto the file upload
  5. Hit Submit

With this, we’ve uploaded our first template!

​
Mapping Extractions to Template Fields

By default, Kolena will attempt to map extractions to placeholder fields by converting the extraction name to lowercase and replacing spaces and special characters with underscores. You can see this as the template_alias whenever you click into the details for the extractions.

You can change the template_alias by editing the extraction. This allows you to map an extraction field to one that might not necessarily match the name exactly.

​
Using the Template

Once you’ve uploaded and configured your template, you can use it for direct downloads and for automated connections to destinations.

​
Downloading the Output

You can directly download the templated output from the Reports page for a given Agent Run:

  1. Navigate to the desired Agent Run
  2. Click into the “Report” tab
  3. Click on the (Download) icon
  4. Select your desired template from the download menu

The templated report may be downloaded as either an editable docx file, or a generated pdf report.

​
Configuring a Destination

You can also specify a template for export with a Destination connection.

Simply go to the Connections page in Kolena, create or edit an existing Destination, and set your template as the “Fill Template” under the “Export Options” section.

​
Advanced

Kolena uses the Jinja templating syntax with the docxtpl engine. This tooling allows support for more advanced rendering, such as with tables and conditionally displaying values.

​
Tables

You can loop over the values of a Kolena table extraction using the %tr for syntax:

Date                          Payee                   Payment Value
{%tr for item in payments %}
{{ item["Payment Date"] }}    {{ item["Paid To"] }}   {{ item["Amount"] }}
{%tr endfor %]

In this case, if my Payments extraction gave me a table with details on individual payments, the above syntax would allow me to replicate that table (with formatting) into my templated output. Note that the field being retrieved from the item must match the extraction’s table columns but the header columns used in the template are free to differ.

​
Conditionally Displaying Sections

You can conditionally display a certain section from the template file based on extraction values using the if syntax:

{%p if tax_value > 0 %}
Due to local regulations, a tax amount of ${{ tax_value }} is owed.
{%p endif %}

The above blurb about tax value will only be displayed if the Tax Value extraction retrieves a number greater than zero, and will otherwise not be displayed in the templated output.