Templating Application

The Templating Application allows to invoke Velocity or MS Word DOCX templates with Process Data and if required converts the output into PDF format.

A template is a document, such as a personalized form letter/email/report that is sent to many customers. Templates allow business people to have more control regarding document content and format. Find more details in the following sections:

Setting Templating Application Properties

Apart from the common properties, the following property tabs are provided for a Templating application:


Figure: Properties - Templating Application

Parameters

You can define parameters to access the data associated with the application. The Templating Application only allows for one Output Parameter of type Text, which is representing the response content of the Velocity Template invocation. It allows for multiple Input Parameters. Input Parameters can be document or primitive/structured data,. Click the Add icon to add the parameters.

To delete the parameters, select the added parameter and click the Delete icon.


Figure: Properties - Parameters

Configuration

In the Configuration tab, you specify the template source, format, content and output. It is also possible to indicate whether the template output should be converted into PDF format.

Text format

In the following example, an embedded template content is converted to PDF and attached to the process instance using the specified output file name.


Figure: Properties - Embedded Configuration

At runtime, the PDF attachment looks similar to the sample in the screenshot below:


Figure: PDF Template output sample

The template could be located in the class path as shown below:


Figure: Properties - Class Path Configuration

XML format

The following example uses embedded XML template content. The result is attached to the process instance using the specified output file name.


Figure: Configuration - Embedded XML template


Figure: XML document output

HTML format

The following example uses embedded HTML template content. The result is converted into PDF format and attached to the process instance using the specified output file name.


Figure: Configuration - Embedded HTML template


Figure: HTML converted to PDF output

In case option Convert to PDF is not selected, the output document will be in HTML format.


Figure: HTML converted to PDF output

DOCX format

The following example uses a DOCX template. The result is converted into PDF format and attached to the process instance using the specified output file name.


Figure: Configuration - DOCX template configuration

The DOCX template file is located in the repository under the Root/artifacts/templates folder.


Figure: Template repository location

It is created using MS Word. Find a sample file below:


Figure: DOCX Sample template

A sample DOCX output converted to PDF format is shown below:


Figure: DOCX output converted to PDF format

Dynamic template configuration

In many situations, the end user would like to specify the Template and/or the Output Name dynamically (i.e. at runtime). This also allows the same templating application to be used with multiple template files at runtime.

Here are the main steps to follow:


Figure: Dynamic Template Configuration

If you want to provide a template file name and/or the output name dynamically through a structured data type, then use expressions such as: $simple{header.Person[template]} and/or $simple{header.Person[outputName]}.


Figure: Dynamic Template Configuration with SDT

Creating Templates

To create Velocity templates in text, XML or HTML format, you can use your preferred text editor.


Figure: HTML Template

More details about the Velocity Template Language (VTL) could be found here.

Creating MS Word DOCX Templates

MS Word DOCX templates can easily be created using MS Word by following these steps:

  1. Start with creating a new document in MS Word
  2. Add static content including fonts, styles, images, etc.
  3. Add a dynamic field, for example $person.firstName:
  4. Click OK. The field is created. The field entry is displayed in « ». Note that in MS Word, the field content is not displayed in full length if it exceeds a certain length. In that case you have to edit the field to see its full content.
  5. Repeat the previous steps for the other fields.
  6. Save your template and upload it to the Repository or copy it under your classpath.

DOCX Templates Examples

The following examples show how to process a data that contains a list of elements.

We define a project data type with the following structure:


Figure: Project structured Type with list of developers


Figure: Project Name and List of Developers sample

Creating a Template containing Lists

If you want to generate a list with the first name and last name of all structured data instances of developers, you have to loop over fields using Velocity syntax.

Prepare the template in MS Word by adding the following text containing an unordered and an ordered list:

Lists
Figure: Unordered and ordered list

Now create the following fields of type MergeField as described in section Creating MS Word DOCX Templates with the following entries as their field names:

  1. After Project: $Project.name
  2. After both occurrences of term Developer List: #foreach($developer in $Project.developers)

    Lists

  3. After the unordered list bullet icon as well as after the ordered list item the following three fields:

The Word content now should look similar as in the below screenshot. Please note that in MS Word, the field content is not displayed in full length if it exceeds a certain length. You have to edit the field to see its full content.


Figure: Developers List Bullet and Numbering DOCX template

Find below the complete text including the Velocity scripts used in this sample:

Project: �$Project.name�

Developer List: �#foreach($developer in $Project.developers)�

. �$developer.Firstname� �$developer.Lastname��#end�

Developer List: �#foreach($developer in $Project.developers)�

1. �$developer.Firstname� �$developer.Lastname��#end�

The generated MS Word DOCX document looks similar to the example in the following screenshot:


Figure: Developers List Bullet and Numbering DOCX output

Creating a DOCX Table Template

In this example, two tables will be generated:

Prepare the template in MS Word by adding the following text and tables:

Plain text and tables
Figure: Plain text and tables

You can add colors to a row by selecting Borders and Shading from the Home menu. Select the Shading tab and choose a color.

Select a color for a row
Figure: Select a color for a row

Now add fields of type MergeField as described in section Creating MS Word DOCX Templates:

The document now looks similar as below:


Figure: Developers Table DOCX template

Please note that in MS Word, the field content is not displayed in full length if it exceeds a certain length. You have to edit the field to see its full content. Find below an overview on the Velocity scripts used in this example:

Project: �$Project.name�

Developer Table I
| First Name                                               | Last Name             | Email              | Salary                 |
----------------------------------------------------------------------------------------------------------------------------------
| �@before-row#foreach($developer in $Project.developers)� | �$developer.Lastname� | �$developer.Email� | �$developer.Salary�EUR |
| �$developer.Firstname�                                   |                       |                    |                        |
| �@after-row#end�                                         |                       |                    |                        |


Developer Table II
| First Name                                                                         | Last Name             | Email              | Salary                 |
------------------------------------------------------------------------------------------------------------------------------------------------------------
| �@before-row#foreach($developer in $Project.developers) #if(0 ==$velocityCount%2)� | �$developer.Lastname� | �$developer.Email� | �$developer.Salary�EUR |
| �$developer.Firstname�                                                             |                       |                    |                        |
| �@after-row#else�                                                                  |                       |                    |                        |
------------------------------------------------------------------------------------------------------------------------------------------------------------
| �$developer.Firstname�                                                             | �$developer.Lastname� | �$developer.Email� | �$developer.Salary�EUR |
| �@after-row#end #end�                                                              |                       |                    |                        |
------------------------------------------------------------------------------------------------------------------------------------------------------------

The generated document looks similar as displayed in the screenshot below:


Figure: Tables of Developers

Templating Functionality as REST Service

The core templating functionality is available via REST service.

Request description

The Templating REST service path is services/rest/templating as shown below.

http://localhost:8080/ipp-portal/services/rest/templating

It has a POST request with the following JSON payload:

Find below a request sample:

{
  "templateUri": "repository://letter.docx"  
  "format": "docx",
  "pdf": true,
  "parameters": {
      "customer": {
         "firstname": "Peter",
         "lastname": "Smith"
      },
      "contract": {
         "number": 1234560,
         "name": "Gold Contract"
      }
   }
   "output": {
      "activityInstance" : aiOid,
      "name" : letter.pdf,
   }
}

Example - Calling a Templating Service by using a UI Mashup Application

The following example describes how to call the templating Service by using a UI Mashup application.

The model has a UI Mashup application configured as follows:


Figure: Templating Rest service

The UI mashup allows to enter a template name, its format as well as output response and location. Those parameters are used to invoke the REST service.

You find more details about UI Mashup applications here.

Once the model is deployed, we can execute the process and provide below values in the Templating Configuration UI.


Figure: Templating Rest service invocation

The template used is located in folder Root/artifacts/templates as shown below.


Figure: Template repository location

The response.pdf file has been generated and attached to the process instance


Figure: Templating output file