Skip to content

How it Works

Document Templates includes two different workflows: Firstly it provides the possibility to create a file by picking a template and providing some context. Secondly a template manager can upload templates and maintain related metadata. Both processes are described in detail further down.

Additionally, it's important to understand the compatibility with templates in the desktop client. To evolve from the limited syntax used in the desktop client templates, the new templates are based on a template library called Jinja. This has the following consequences:

  • Templates uploaded to the web client can't be picked in the desktop client.
  • Desktop client templates can be used for generating a document in the web client when configured to do so. This is only recommended after extensive testing to ensure the rendered result fits your expectation. You can find a list with unsupported merge codes on the troubleshooting page.
  • A template with the old template syntax can be uploaded to the webclient and thereby migrated. It's highly recommended to downloaded the template after it has been migrated to verify its correctness and adjust syntax that could not be migrated correctly. By uploading and migrating the desktop client to a web client template, you are making a copy of the template file which means double maintenance efforts if the template should still be used in the desktop client.

Prepare templates

Currently, there's no assistance yet when writing new templates in Word. Therefore, the correctness of the merge code variables and the syntax has to be manually ensured. You can find a Docx template file with the examples mentioned below here.

Jinja syntax

As mentioned earlier the template has to follow the syntax rules of Jinja to be rendered correctly. Please checkout their documentation for a complete feature overview. This section will go through some common use cases for document templates and show examples for how to solve those with Jinja.

Database structure

In order to render the correct values in a template, the merge codes have to be in sync with the database. For all the examples below we assume the following database structure: 

document:
    _label: document
    document:
        type: file
    comment:
        type: string
    deal:
        type: belongsto
        related: deal

deal:
    _label: project
    name:
        type: string
    value:
        type: decimal
    totalvalue:
        type: decimal
    company:
        type: belongsto
        related: company
    orderitems:
        type: hasmany
        related: orderitem
    probability:
        type: decimal
    person:
        type: belongsto
        related: person

company:
    _label: company
    name:
        type: string
    buyingstatus:
        type: option
        options:
            - notinterested
            - prospect
            - active
            - excustomer
        defaultvalue: prospect

orderitem:
    name:
        type: string
    price: 
        type: decimal
    currency:
        type: string
    picture:
        type: file

person:
    name:
        type: string
    allergies:
        type: set

Merge code variables

Starting from the configured document limetype you can use all its properties as well as nested properties on related limetypes. Here are a few valid examples:

  • {{ comment }}
  • {{ deal.value }}
  • {{ deal.company.name }}
  • {{ deal.company }}

Merge codes that end on a relation field (like {{ deal.company }}) will render the limetype's descriptive.

The limeobjects id and descriptive fields are also accessible. Note that there is one limitation though. Since the document template is run before the document limeobject is created in the database {{ id }} will not return the document's ID, since it's not yet been generated.

Pre-defined merge codes

A set of pre-defined merge codes are available when generating documents. These merge codes are available from the merge code variable context.

Available pre-defined merge codes
  • context.today - returns a date object with the current date, excluding time (2021-10-27 00:00:00).
  • context.now - returns a date object with the current timestamp, including timezone (2021-10-27 15:42:50 + 02:00).
  • context.active_user - returns the coworker object of the user generating the document.

Formatting

Variables can be rendered in a specific format by adding a filter. Filters are used within a variable, separated by a pipe (|) character like this: {{ <merge>.<code> | <filter> }}. Check out this list of built-in Jinja filters.

One very handy example of this is the sum filter. {{ deal.orderitems | sum(attribute='price') }} will sum up the price of all order items in a deal.

Date and time

Filters for formatting and manipulating dates and time are included. Further information and examples can be found here.

Numbers

Filters for formatting numbers are included. Further information and examples can be found here.

Lists

Whether you want to show all order items in an offering or list achievements in a certificate, there are a lot of use case where the possibility to loop through a list is needed. An example would be:

{% for orderitem in deal.orderitems %}
{{ orderitem.name }}: {{ orderitem.price }} {{ orderitem.currency }}
{% endfor %}

Rendering lists into a table is slightly different. You will need to add an extra tr in the opening and closing for loop tags. For example:

Name Value (SEK)
{%tr for orderitem in deal.orderitems %}
{{ orderitem }} {{ orderitem.price }}
{%tr endfor %}

You can also find the example in the linked Word document example.

For more build-in list functionality read this section in the Jinja documentation.

Conditional expressions

Does your template have a paragraph that should only be included under certain circumstances? For instance some extra information that only prospects need?

{% if deal.company.buyingstatus == 'prospect' %}
This is a paragraph about how amazing your company is. 
Existing customers already know that.
{% endif %}

Option and Set Properties

Option and set properties work a little differently than other fields because their values have labels with translations. Option and set fields define keys and labels for each key. In the web and desktop client, when a specific key is selected for an option or set field, the correct label is shown to the user depending on their language.

The below examples assume:

  • A template with en_US locale
  • A company option field buyingstatus with the key notinterested and the labels Not interested for english and Ointressant for swedish,
  • A person set field allergies with the keys vegetarian and lactose with english labels Vegetarian and Lactose respectively.

By default in document templates, option and set fields will just render their key(s).

{{ deal.company.buyingstatus }}
notinterested

{{ deal.person.allergies }}
vegetarian, lactose

To render a label, you must use the localize filter. The below will render the label for the templates configured locale (for sv_SE it would render Ointressant). If there is no label for the template locale, it falls back to the default language of the application.

{{ deal.company.buyingstatus | localize }}
Not interested

{{ deal.person.allergies | localize }}
Vegetarian, Lactose

You can override the template locale on a case by case basis as well

{{ deal.company.buyingstatus | localize(locale="sv_SE") }}
Ointressant

Set properties have some additional use cases 

{% for allergy in deal.person.allergies %}
- {{ allergy | localize }}
{% endfor %}

{% if "lactose" in deal.person.allergies %}
Below is a list of lactose free alternatives you may request

- Soy milk
...
{% endif %}

Info

Although locale (which contains a language code such as sv and a country code such as SE) is used for getting the label for set and option fields, the CRM only stores a label for each language, so the country part of the locale will have no affect on the rendering of the field.

File properties

File properties are supported as long as they contain images.

{% for orderitem in deal.orderitems %}
{{ orderitem.picture }}
{% endfor %}

The list of supported image types is currently limited to:

  • Windows Bitmap (.bmp, .dib, .rle, .bmz)
  • Graphics Interchange Format (.gif, .gfa)
  • JPEG File Interchange Format (.jpg, .jpeg, .jfif, .jpe*)
  • Portable Network Graphics (.png)
  • Tag Image File Format (.tif, .tiff)

Filters for controlling images are included. Further information and examples can be found here.

Manage Templates

You can manage templates via Lime Admin. In Lime Admin under Settings > Document Templates you'll find a UI for enabling and disabling templates and where you can upload your templates so they can be used when creating Documents in the CRM Webclient.

For a breakdown of this UI take a look at the configuration page

Migrating Templates

Desktop templates can be migrated automatically by uploading them as a template in Lime Admin. The flow for migrating a template is as follow:

  • Upload a desktop template via Lime Admin
  • If the template contains desktop merge codes, you will be prompted to either upload and migrate or upload and skip migration.
  • Detection of desktop merge codes is not perfect, therefore you have the option to skip the migration if you know that your template does not contain desktop merge codes. Otherwise, you should choose to migrate the template and the desktop merge codes should be replaced with the equivalent Jinja merge code.
  • After migration, download the migrated file and verify that the document is migrated correctly. Not all desktop merge codes can be migrated correctly.
  • If the template was not migrated correctly, fix the issues in the migrated document and reupload it in Lime Admin.

Note: If you are having issues with migrating templates, check out the troubleshooting page.

Apply templates

As long as document templates are enabled, template support is built into the workflow whenever someone creates a document. A user can then either upload an existing file or pick a template. The list of templates shown in the picker can be configured to include the desktop client templates or not. Furthermore, metadata from either Lime Admin or the Desktop client template manager are displayed and searchable. Before saving the limeobject, the user should fill out the rest of the form with related information. This related information is used to populate merge codes in the template when rendering the final document.

Pick a template