How to write a document template¶

What is a document template?¶

A document template is a typical document created with any text editor and saved as DOCX, DOC, PDF or ODT format. A template can contain fields and/or functions.

Our product uses those fields to insert data and generate documents that can be downloaded in DOCX or PDF format.

We recommend users to create templates using Microsoft Word, Office 365 or Google Docs and to save their templates as DOCX when using Word or Office 365 and as ODT when using Google Docs.

Simple fields¶

We support the inclusion of elements that simply match an element of data filled in by the user in the User Interface. Wherever an element occurs, our product substitutes the actual data value in the document. The inserted data inherits all the typesetting characteristics that are applied to the field, such as font and paragraph style.

The syntax for a simple field is:

<<element_name>>

By default, the start of a field is annotated by << and the end of a field by >>. So to create a field that will be replaced by the value of the field “firstname” for the employee, you would simply type <<firstname>> into the document.

To be as unobtrusive as possible to the text of a template, our tool is strict about identifying fields and ignores invalid mark-up, which is interpreted as plain text. For example, <<firstname> is ignored and left as plain text because a closing > character is missing. A single space between the << and the name or the name and >> is allowed, but more also result in the field not being recognized. The following table shows the typical types of error that result in a field not being recognized.

Optional fields¶

Optional fields operate like the fields described earlier, except if there is no data for the value the entire paragraph containing the field is removed. Optional fields are specified with the prefix op: , for example:

<<op:element_name>>

Optional fields are useful for condensing output (not leaving behind blank lines) when populating data. Consider a typical address block:

<<address1>>
<<address2>>
<<city>>, <<country>>

If you fill in no value for address2, the output using the above sequence looks as follows:

53 Avenue Mirabeau

Paris, France

The blank line in the middle of the output above is likely to be undesirable and so using an optional field:

<<address1>>
<<op:address2>>
<<city>>, <<country>>

Results in the required output:

53 Avenue Mirabeau
Paris, France

Optional fields are also useful for removing paragraphs from numbered or bullet lists. Consider:

I have one <<item1>>
I have one <<item2>>
I have one <<item3>>

With data item2 = orange and item3 = banana, this results in:

I have one
I have one orange
I have one banana

Clearly item #1 above is incomplete because there is no data for it. Changing to optional paragraph fields resolves this:

I have one <<op:item1>>
I have one <<op:item2>>
I have one <<op:item3>>

With data item2 = orange and item3 = banana, this results in:

I have one orange
I have one banana

Known fields¶

When using Smart Document Generation through our User Interface, you have the possibility to add predefined fields in your document template. These fields are divided into two types, standard fields which are known by our database without configuration on your side, and custom fields that you can create when configuring UKG HR Service Delivery platform.

If you insert a field in your template with the same name as one of these fields then, it is automatically detected.

Please note that the variable is replaced by the expected value only if the corresponding information is present in the employee folder.

Content blocks¶

Content blocks are parts of templates to be inserted into other templates. They are useful when you need to insert recurring content into several of your templates, such as logos and legal mentions.

To insert a content block in your template you need to add this field:

<<refLookup:my_block>>

Conditions¶

Conditional content is populated in the final document depending on the data filled in by the HR User in the User Interface. If, and only if, the specified condition is met, the content within the matching conditional section is rendered in the document.

Each conditional section is defined using a pair of fields: one to start the section and one to end it. The general syntax is:

To provide else and else if options in a conditional section you can use the following syntax:

The conditions can use expressions, variables and range specifiers, or any of the operators in this list:

The conditional start and end tags are removed from the resulting document. If each tag is on a line by itself, the entire line is removed and the result is cleaner.

We strongly recommend using those conditional tags on dedicated lines or paragraphs when possible. Not following this recommendation might produce unexpected behavior, like extra blank lines appearing in the generated document.

You can find an example template with conditions in the Example templates section.

Comments¶

Comments are sections of the templates that are ignored by document processing and never appear in the generated document. They are useful for:

• Creating permanent notes in the template that are helpful to template authors and maintainers.

• Disabling sections of templates temporarily to assist with development and maintenance.

Due to the two distinct requirements for comments above, there are times when you may need to comment out a section of a template which itself contains other comments. For example, you are temporarily disabling a section of the template which happens to contain comments that are permanent. To support this, we provide several distinct comment markup delimiters as shown by the following table. Different delimiters may be used to nest comments inside other comments.

As an example, a single comment may look as follows:

<</* The following section displays the person details if they exist */>>

<<cs_displayPersonDetails>>

And nested comments may looks as follows:

<<## This entire section is disabled
<</* This displays the salary of my employee */>>
<<salary>>
##>>

Dates¶

Dates can be inserted in the document template and formatted in the desired output format.

The syntax for inserting a date in the template is:

<<{dateFormat(myDate)}>>

Number format¶

If you want to format a number on a specific format/pattern, the syntax is:

<<{numFormat(number, '### ###,##', 'FR', 'false')}>>

where ### ###,## represents the pattern to display, and FR is the optional locale that specifies the input format of number.

Calculations¶

Calculations can be performed in the generated document according the data filled in by the user in the User Interface. The result of a calculation can either be simply displayed in the generated document or used in conditions.

The syntax to create a calculation to be displayed in the generated document is:

<<{number1 + number2}>>

where + can be replaced by any of the operators on this list:

Here is the syntax to store a calculation in a variable $myResult , to be used later on in a condition:

<<$myResult={number1 + number2}>>

[...]

<<cs_{$myResult>10}>>
The text and elements of the conditional section.
<<es_>>

Other functions¶

Several other functions can be used in a document template:

<<cs_{isBlank(address)}>>
There is no address
<<es_>>

<<cs_{endsWith(serialNum, 'ZZZ')}>>
<<serialNum>>
<<es_>>

<<cs_{length(refNo) > 0}>>
Ref Num : <<refNo>>
<<es_>>

Example templates¶

You can download these templates to avoid starting from scratch:

• template-with-conditions.docx

• employment-certificate-template.docx