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

Docx List Examples

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

For example, we define a project data type having the following structure:


Figure: Project structured Type with list of developers


Figure: Project Name and List of Developers sample

Bullet and Numbering list

If you want to generate a list of first name and last name of developers, you have to loop over fields using Velocity syntax similar to the example shown below:


Figure: Developers List Bullet and Numbering 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 content. Find below 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

Docx Tables

In this example, two tables will be generated:

To generate the two tables, you have to write this document template:


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 content. Find below the Velocity scripts used in this sample.

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 is the following:


Figure: Tables of Developers

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

Template Creation

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.

MS Word DOCX template can be easily 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. Repeat the previous steps for the other fields.
  5. Save your template and upload it to the Repository or copy it under your classpath.

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

Enabling Cross-Origin Resource Sharing for Tomcat

If you use Tomcat, you need to enable cross-origin resource sharing (CORS). This is required for cross domain requests and for using the templating functionality. To enable CORS, enter the following CORS filter to your web.xml file:

<filter>
   <filter-name>CorsFilter</filter-name>
   <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
   <init-param>
      <param-name>cors.allowed.origins</param-name>
      <param-value>http://ap-pun-lp1859:9091</param-value>
   </init-param>
   <init-param>
      <param-name>cors.allowed.headers</param-name>
      <param-value>Content-Type,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,Accept-Language</param-value>
   </init-param>
   <init-param>
      <param-name>cors.allowed.methods</param-name>
      <param-value>GET,POST,HEAD,OPTIONS,PUT</param-value>
   </init-param>
</filter>
<filter-mapping>
   <filter-name>CorsFilter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>

Example

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