WordTemplateHandler

Description

This actionhandler allows you to create and use Word document templates with values from process variables that usually come from a form. The parameter "overwriteExisting" specifies whether existing templates may be overwritten (true) or whether a new template should be created. Variables from https://tim-doc.atlassian.net/wiki/spaces/eng/pages/227969642 can also be used with this actionhandler.

In order to create document names based on variables, you can include desired variables in the document name in addition to the document content.

It is possible to insert pictures from the process instance into the Word document. Therefore, special variables are needed in the template. An individual picture can also be inserted with the exact name of the picture, for example: $img{bild.jpg}. It is also possible to insert all images attached to the instance: $img{addAllimages}.

The WordTemplateHandler can also be installed in the https://tim-doc.atlassian.net/wiki/spaces/eng/pages/228002614 as a button to generate a template if required. More information is here.

Class

com.dooris.bpm.actionhandler.WordTemplateHandler

Parameter

Parameter	Default value	Description	Valid examples

Parameter	Default value	Description	Valid examples
`template` mandatory		This parameter is used to set the path to the template, so the ActionHandler can search for it in the resources folder. It can be specified absolute or relative to the external file path in the loom.properties. In order to rename the generated PDF, the name of the template itself may contain process variables. Special case: Resolving process variables in the template name Given the template, parameter has the following value: `template`=`${SYS.PROCESSINSTANCE_NAME}_report.docx`. In the target folder, the file will be searched accordingly. The WordTemplateHandler literally searches for the template `${SYS.PROCESSINSTANCE_NAME}_report.docx`. If it is unable to find the respective document, the process variables `SYS.PROCESSINSTANCE_NAME` will be resolved in the document name. Only now, the WordTemplateHandler is looking for the template `8D-ProblemSolving_report.docx` (8D-ProblemSolving is the resolved value of `${SYS.PROCESSINSTANCE_NAME}`). In order to access ‘Resources’ section under the 'Administration' please see: `Roles`	`${processInstanceId}_8D-report.docx`
`overwriteExisting`	`false`	This parameter is used to decide if the documents should be overwritten if the process run by a loop. If the original template is needed, it should be `false`.	`true`
`documentPrefix`		The documentPrefix can be used so that created documents always have the specified value before the template name.	`mydocumentprefix`
`pdf`	`false`	If this parameter is set to `false` or is not given, the system replaces the variables in the template and creates a Word document, which is attached to the process. In order to create a PDF document instead of a Word document, this should be `true`.	`true`
`removeEmptyTableRows`	`false`	When the value is set to `true`, all table rows in the docx-template are cleared, if the variable in the first column is missing or empty. This can avoid unsightly blank rows in dynamic content (DOMRepeater).	`true`
`interpretNummbersAsBoolean`	`false`	It can be either true or false. If this value is set to true, process variables (which start with "bool") are changed like below: baa1 → true (In the document: true) boolbaa1 → true (In the document: yes) boolbaa1 → 1 (In the document: yes) bobbb1 → false (In the document: false) boolbbb1 → false (In the document: no) boolbbb1 → 0 (In the document: no)	`true`
`interpretBooleanAsHuman`	`false`	This parameter is used to decide if the boolean variables (true and false) should be replaced with ‘yes and no'. Setting this variable to `true` will change boolean variables as 'yes and no'.	`true`
`target`		This parameter is used to determine the document name in the destination folder. This procedure is useful if the name of the created Word document should be different from the template name. The target parameter can contain process variables. Suppose the user wanted to generate two reports in English and German. The Word template in the resource folder has the following name `${SYS.PROCESSINSTANCE_NAME}_report_${language}`. With the target parameter, the name of the Word document can now be changed to e.g. `target=XY-Report_DE`. Therefore the user can create Word files with different names from the same Word template. File extension is not needed within the target parameter.	`target=${processInstanceId}_${processInstanceName}_report`
`locale`	`"de"`	With this parameter all system supported languages can be given in short form(e.g. `en`, `de`). This leads to, that all system-generated words (e.g. boolean Yes/No) are translated.

Example:

We have a brief use case to explain this ActionHandler.

Firstly, a Word document is used as a template. The template includes two variables (${employee_name}, ${employee_id}). These variables are used in the Form later. To ensure that the variables are replaced with the content from the Form by the WordTemplateHandler, the variables must be placed inside a ‘Text Form Field’ in Word.

The variable ${employee_name} is entered into the field ‘Default text’ in the ‘Text Form Field’ options. This option can be accessed by double-clicking on the gray highlighted text field in Word.

After both variables have been inserted as text form fields, the Word document looks as follows:

The Word document is saved with the name ${employee_name}.docx. The ActionHandler replaces the variable in the document name with the employee's name provided in the Form.

This template should be uploaded to the ‘Resources’ in the Administration:

The document is uploaded into the Resources using the "Upload File(s)" button.

Now the ActionHandler can be set up in the process flow. For each employee, a Word document containing the employee’s name and ID should be generated after process start. To achieve this, the WordTemplateHandler is implemented on the first task in the process model.

Parameter	Description	Example

Parameter	Description	Example
`template`	Here, you provide the name of the Word template which was uploaded to the resources folder. When the process is started, the ActionHandler will find the template with this parameter and will create a new document with the information from the form. The document is stored in the “Documents” tab of the process instance.	${employee_name}.docx

Finally, a Form is required, which contains two input fields with the variables employee_name and employee_id.

Once the process with its form is published, start a process instance and enter the employee’s name and ID, when starting it.

After a successful instance start, a document will be generated from the template and variables employee_name and employee_id will be filled as John Doe and 000123. You can access the generated document under the documents section:

You can access the document by clicking on it, and you can also download and open the document by clicking on the action button:

The variables in the document as well as in the document name were replaced with the values from the form.

Integrating the WordTemplateHandler into a HTML-Form

The WordTemplateHandler can be integrated into a HTML-Form as a link, a button, or an image so that the participants can create a template at any time. For this, the following code must be integrated into the form:

<button type="button" onbuttonclick="generateFileFromTemplate([{handler:'WordTemplateHandler',template:'pfad/zumTemplate.docx',pdf:false,attach:false,open:true,documentPrefix:'Prefix'}])">button name</button>

The "onbuttonclick" attribute defines which functions/parameters the handler should execute. See Parameters sections above.

Document History

The document-history of a process instance can be reviewed via the system variable ${SYS:DOC_HISTORY}. The document history displays which documents of the instance have been attached, edited or deleted. With the WordTemplateHandler the user can save the document history to a Word or PDF document (s. screenshot).

Important when using HTML-Forms

Normally written text will be inherited, whereas variables will be overwritten if marked as ${Variable-ID}. To overwrite variables with content from the HTML form, you must use the variable's ID, such as ${Variable-ID}, within the text form fields. An exception to this rule applies to radio buttons, where you should use the variable name, like ${Variable-Name}, instead of the variable ID.