As part of business processes often a document needs to be generated. In this article a word template is explained which can be integrated to a business process and used together with placeholders. The different steps to create a document and add it to a process are explained.
If you rather watch the how-to video, skip to the end of the article or watch it on YouTube.
This guide describes the 'Generate Document' activity that is available both for BPMN and CMMN models. With this activity, it is possible to generate PDF or Word documents based on data gathered during instance execution or from external sources.
The features and capabilities of this activity are described below by working through a real example.
Note: This activity is available in the Design palette for Flowable Work and Engage
The
Flowable Work Activities > Generate Document
activity uses a Word document as a template that at runtime is used to generate a final PDF or Word document. This template is referenced by a Template Model.Open Flowable Design and create a new app model. Click the
+ Add model
button, select create a new model for the app
, Other
and then Template
.Give the template a name and a key. For demo purposes, we'll use
My template
and myTemplate
.This will open up the template model editor. We'll use a Word document here, so the
Template type
can be kept on Document
, which is the default. The alternative there, Text
is for textual templates like for email bodies.Click the
Upload a file
icon and upload or drop a Word template there.The Word document template looks like this:
"Dear <<if [context.booleanValue("${gender == 'm' }")]>>Mr.<<else>>Mme.<</if>><<[context.value("${firstName}")]>> <<[context.value("${lastName}")]>>, We're very happy to inform you that your order is ready for shipping: <<foreach [item in context.foreach("${items}")]>> - <<[context.mapValue(item,"name")]>>, with a business value of <<[context.mapValue(item, "value")]>> <</foreach>> A preview: <<image [context.image("${anImage}")] -fitWidth>"
More information about the language and syntax used here can be found at https://docs.aspose.com/display/wordsnet/LINQ+Reporting+Engine+API.
Finally, save the model and go back to the app model.
We can now use this template in a process or case model. Using Flowable Design, let us create the following simple process model:
This process also has a start form that looks as follows:
Note that the start form has fields called firstName, lastName, gender, anImage. When executing an instance of this process definition, the form values are stored as process variables.
Such variables can be used in templates. Note that transient variables also work in case you do not want to store variables that are only useful for document generation.
Data for documents can also come from automatic service tasks. In this example, we are using a Groovy script task to emulate this:
"def items = new java.util.ArrayList(); HashMap map1 = new java.util.HashMap(); map1.put("name", "laptop"); map1.put("value", 1234); items.add(map1); HashMap map2 = new java.util.HashMap(); map2.put("name", "desk"); map2.put("value", 987654321); items.add(map2); execution.setTransientVariable("items", items);"
Now on to the configuration of the Generate Document step:
The template model is the model we've created above. It's also possible to create a new model directly from this property.
The Document name is used to determine the filename of the generated document and this can be an expression (e.g., based on a customer name variable, a timestamp, etc.).
The Document type is either
pdf
or word
and this determines the output format.The Output variable is filled in when the generated document needs to be referenced later (this is shown in the next step).
Finally, in the task at the end, we want to display the document. To do this, we attach a task form to the user task and use the document gallery form widget with a value set to {{generatedDocument}} (i.e., the name of the Output variable above).
Deploy the process model by creating an app and publishing it in Flowable Design. Go to Flowable Work or Engage, click the
Create new
button in the Work menu, and select the deployed process.The start form is now shown:
After clicking
Submit
, the process instance is started, and the document is generated. The process instance now waits at the user task before the end event. When clicking on the task, we see the generated document:When clicking the document thumbnail, the document is seen full screen and downloaded.
In the previous example, we used one variation definition for the template. Let us now look at adding variations.
Variations allow a different template, depending on the context (more specifically based on instance variables), for the same template definition.
A prime example is the multi-language support for the same document. That is the reason why the start form above had a language field.
Let us build such a multi-language document generation now.
Open the template model create before.
Click the
Enable variations
checkbox. This now shows a UI that allows filling in variation parameters. Add one parameter with name language
and Default value
en
.Upload two documents: one English template and one other language template:
The en version is the same as above and the nl version is a version that is translated into Dutch.
What we're configuring here: when the language parameter is 'en', pick the first template and when the parameter value is 'nl', pick the other. The parameter will be a process variable at runtime in this case. The default is set to 'en' when the parameter is not matching.
Note: Multiple variation parameters can be used and they are logically AND-ed together
The process definition is the same as the above. However, when now another language is selected, the translated version will now be used.
In the Word template a context variable exists with which to generate advanced output. This variable can be used in the template (as shown above).
Note: The name of the context object can be changed by the Context object property in Flowable Design. The default value is context.
The following methods are exposed via this context object:
valueOrDefault(expressiontext, defaultValue): allows resolution of an arbitrary expression (this includes Spring Beans). If no value is returned (null), the specified default value is used.
value: the same as the previous method, but without a fallback to a default value.
booleanValue: outputs a Boolean value.
mapValue: to retrieve an element from a Map variable (in the example above this was used:
<<[context.mapValue(item,"name")]>>)
.forEach(expression): allows iteration over a collection which is referenced by an expression (in the example above:
<<foreach [item in context.foreach("${items}")]>>
).image: allows rendering an image (in the example above:
<<image [context.image("${anImage}")] -fitWidth>>
).This guide describes the 'Generate Document' activity to generate pre-filled PDF documents from PDF forms. PDF document generation is similar to Using the 'Generate Document' Activity.
With this activity, it is possible to generate a pre-filled PDF form, based on data gathered during process/case instance execution or from external sources.
Creating a template model is done the same way as above. Th difference is that now a PDF template is uploaded. Such a PDF needs to be created using a specialized PDF tool that allows to created editable PDF's.
An example PDF document template looks like this:
To pre-fill a form field value with data, the form field name must be an expression. In the example above, the First name text field name is a
${firstName}
expression. When the text field name is an expression, the Generate document
activity sets the text field value to the value of the evaluated expression. Supported form fields are:text field.
check box: when the name expression value is of a
Boolean
type, the check box is set or unset if the value is true
or false
.radio button: the radio button option with the same name as the name expression value is set.
list box: the choice with the same name as the name expression value is set.
The Combo box form field is not supported.
Process Model Example
We can now use this template in a process or case model. Using Flowable Design, let us create the following simple process model:
We can now use this template in a process or case model. Using Flowable Design, let us create the following simple process model:
This process also has a start form that looks as follows:
Note that the start form has fields called salutation, firstName, lastName, flowableUser, bpmnExperience. When executing an instance of this process definition, the form values are stored as process variables. Such variables can be used in templates. Note that transient variables also work if you do not want to store variables that are only useful for document generation.
The only supported document type is
pdf
.Finally, in the task at the end, we want to display the document. To do this, we attach a task form to the user task and use the document gallery form widget with a value set to {{generatedDocument}} (i.e., the name of the Output variable above).
Deploy the process model by creating an app and publishing it in Flowable Design. Next, go to Flowable Work or Engage, click the
Create new
button in the Work menu, and select the deployed process.The start form is now shown:
After clicking
Submit
, the process instance is started, and the document is generated. The process instance now waits at the user task before the end event. When clicking on the task, we see the generated document:By clicking the document thumbnail, the document is seen in full screen and downloaded.
These settings are available from Flowable Work 3.9.0
There are a few advanced settings possible to tweak the Aspose templating engine. These need to be set in your Flowable Work installation:
flowable.template.aspose.allow-missing-members
(default true): By default, missing members in expressions (e.g. <<[name.something]>>) will throw an exception. When this property is set to true, no exception is thrown, but the expression will resolve to null (i.e. no value is written).
flowable.template.aspose.inline-errors
(default false): By default, syntax errors in the template will lead to an exception being thrown. When this property is set to true, no exception is thrown, and the place where the error is happening is shown in the generated template. Note that will show syntax errors only, not expression evaluations problems.
flowable.template.aspose.remove-empty-paragraphs
(default false): By default, expressions resolving to empty paragraphs are not removed. When this property is set to true, empty paragraphs will be removed from the final document.
Example of enabling the inline errors property:
Video:
Once you have downloaded the Flowable Work trial, you want to get started with creating your first application. In this video, Valentin…
The trial download is a full version of Flowable Work, with all its functionality enabled, including real-time chat. If you haven’t already…
What are CMMN sentries and how can you use them in Flowable? In this how-to video, Valentin Zickner, explains CMMN sentries by creating…