JUNE 7, 2022

Generate Document Task in Flowable

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.

Configuring and Using the 'Generate Document' Activity

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.

Flowable Platform Activities

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

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:

750-word-template-01-4ddc71417b8944a9250541dc1c24c4dc

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

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

750-process-example-c8c3d669d4de9df6d164a9a4d50c0d95

This process also has a start form that looks as follows:

750-start-form-d8c0e61d349cd9347f956071aeb0c231 (1)

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:

750-generate-document-configuration-3545d022cd48d984cdd2b66fcc73cf87
  • 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).

Running the Example

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:

750-start-form-02-3cc9d3c5f90ec07d057e0bd3bbd8431f (1)

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:

750-see-document-task-138ed06ec5901249577c731fd1769e0f

When clicking the document thumbnail, the document is seen full screen and downloaded.

Template Variations

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:

Template Variation 1:

755-template-variations-0186ccedad02094dc1e4ea4a7e1d54f8

Template Variation 2:

755-template-variations-0186ccedad02094dc1e4ea4a7e1d54f8 (1)

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.

Advanced

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

Configuring and Using the 'Generate Document' Activity with a PDF Template

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.

Flowable Platform Activities

The Template Model

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:

755-pdf-form-template-145309edd5bdbd8781d0a63eea2c401c

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:

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:

download

This process also has a start form that looks as follows:

755-start-form-1e1b510dbb4369051c87d240fb99eb35

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
.

755-generate-document-configuration-d94a6e08eb68a0c5942a76316eec028a

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

Running the Example

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:

755-start-form-02-9620c6a8fb74d3a92f4a6cbf2b1f972b

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:

755-see-document-task-9c96faf310f4ab9e4c5ef4f879a97aad

By clicking the document thumbnail, the document is seen in full screen and downloaded.

Advanced settings

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:

755-inline-errors-a2f0bbee1921a5c79ed974c487fe2488

Video:

flowable_blog_generic video_header
How-to | JUNE 26, 2022

Creating a Hello World Case

Based on the enterprise trial installation this video explains how you can create your first Flowable app with a simple "hello world" CMMN case model.Read more

flowable_blog_generic video_header
How-to | JUNE 25, 2022

Modeling by Example: Travel Request App Part 2

This is the second part in the series where we're build a travel request CMMN case model. In this part, we'll dive deeper into completing stages and forms.Read more

flowable_blog_generic video_header
How-to | JUNE 24, 2022

Modeling by Example: Travel Request Part 1

This is the first part in a series where we're building a CMMN case model to manage travel requests from scratch. This is an excellent movie…Read more