Documentation
What's NewUKG.comMarketplaceUKG Pro status

How to Write a Document Template

This section provides a guide on writing a document template.

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>>

Note
We discourage the use of hyphen - in field names. If you choose to use one, you will need to surround the field name with brackets ([ ]) when using it in an expression, such as in Conditions, Date format, or Number format. For example, <<[my-field-with-hyphens]>>

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 markup, 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.

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 address2 is empty, the output might have an undesirable blank line. Using optional fields:

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

produces:

53 Avenue Mirabeau
Paris, France

Optional fields are also helpful in numbered or bullet lists. For instance:

  • I have one ITEM1
  • I have one ITEM2
  • I have one ITEM3

With only item2 = orange and item3 = banana, the output would include a blank line for the first equation. Switching to optional:

  • I have one OP:ITEM1
  • I have one OP:ITEM2
  • I have one OP:ITEM3

results in:

  • I have one orange
  • I have one banana

Note: Optional fields strip the entire line or paragraph. Any additional content on that line is also removed.

Known fields

When using Smart Document Generation through the User Interface, you can add predefined fields in your template. These are divided into standard fields (supported out of the box) and custom fields (configured by your UKG instance). If a field in your template matches one of these names, it is automatically detected and replaced — if the corresponding data exists in the employee’s record.

Standard fields

Some built-in standard fields include firstname, lastname, address, etc.

Custom fields

To include a custom field, use:

<<custom_fields_<attribute_code>>>

For instance, if you have a custom field salary_amount, you insert:

<<custom_fields_salary_amount>>

Or for a custom field named assignment-category, you use:

<<custom_fields_assignment-category>>

Content blocks

Content blocks are reusable pieces of template text (e.g., header, footer, legal notes). You include them in templates using:

<<refLookup:my_block>>

Here my_block is the reference name. Upon upload in the UI, you link this reference to a defined content block.

Warnings:

  • Nesting content blocks inside other content blocks (i.e. recursive inclusion) is not supported.
  • Avoid having digits immediately after refLookup; for example:
    • <<refLookup:myfield007>> is allowed
    • <<refLookup:007myfield>> is not allowed

Conditions

Conditional sections allow parts of the template to show only when data meets criteria. Syntax involves:

<<cs_myCondition>>
  … content …
<<es_>>

You can also define else branches:

<<cs_myCondition>>
  … content A …
<<else>>
  … content B …
<<es_>>

Or with expression:

<<cs_myCondition>>
  … content …
<<else_myOtherCondition>>
  … alternative content …
<<es_>>

Note: The condition tags themselves are removed in final output (if they are on their own lines).

Comments

Comments allow authors to include notes or disable sections. They do not appear in the final document.

<</* Section disabled for now */>>
<<cs_displayPersonDetails>>
  … content …
<<es_>>
##>>

Dates

Date fields must be typed as Date in the template editor. You insert dates using:

<<{dateFormat(myDate)}>>

Date formats

By default the format is dd MMM yyyy (e.g. 25 Nov 2021).
You may override:

<<{dateFormat(myDate, 'output-format')}>>  
<<{dateFormat(myDate, 'EEEE MMMM yyyy', null, templateLocale)}>>

Example:

  • <<myDate>> → 2021-11-25
  • <<{dateFormat(myDate)}>> → 25 Nov 2021
  • <<{dateFormat(myDate, 'dd/MM/yyyy')}>> → 25/11/2021
  • <<{dateFormat(myDate, 'MMMM dd, yyyy')}>> → November 25, 2021
  • <<{dateFormat(myDate, 'yyyy')}>> → 2021

Operations on dates

<<{dateAdd(starting_date, 3, 'months')}>>  
<<{dateDiff('10 Jul 2020', '18 Jul 2020', 'days')}>> → 8

Number format

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

Source: UKG HR Service Delivery documentation — How to write a document template.

Updated 3 months ago