Flowable applications

Flowable provides a web UI application to demonstrate and leverage the functionality provided by the Flowable project. This application contains four main app components:

• Flowable IDM: an Identity Management app that provides single sign-on authentication functionality for all the Flowable UI applications, and, for users with the IDM administrative privilege, it also provides functionality to manage users, groups and privileges.

• Flowable Modeler: an app that allows users with modeler privileges to model processes, forms, decision tables and application definitions.

• Flowable Task: a runtime task app that provides functionality to start process instances, edit task forms, complete tasks and query on tasks and process instances.

• Flowable Admin: an administrative app that allows users with admin privilege to query the BPMN, DMN, form and content engines and provides several options to change process instances, tasks, jobs and so on. The admin app connects to the engines through the REST API that is deployed together with the Flowable UI application and the Flowable REST application.

This UI application is provided as a single WAR file that can be dropped in any web server or started with its embedded server. Spring Boot starters are available for each separate component app.

The application and components are Spring Boot 2.0 based, which means that that the WAR file is actually executable and can be run as a normal standalone application. See The Executable Jar Format in the Spring Boot reference documentation.

Flowable also provides the flowable-rest.war which contains the Flowable REST API. More about this can be read in the REST API chapter.

Flowable UI application installation

As mentioned before, the UI application can be deployed on a Tomcat server, and to get started this is probably the easiest approach when additional configuration settings are used. For this installation guide we’ll describe the installation of the application in a Tomcat server.

1. Download a recent stable version of Apache Tomcat.

2. Download the latest stable Flowable 6 version.

3. Copy the flowable-ui.war file from the Flowable distribution wars folder to the Tomcat webapps folder.

4. Startup the Tomcat server by running the bin/startup.sh (Mac OS and Linux) or bin/startup.bat (Windows) script.

5. Open a web browser and go to http://localhost:8080/flowable-ui.

The Flowable UI application should now be running with an H2 in-memory database and the following login screen should be shown in your web browser:

By default, the Flowable IDM component will create an admin user that has privileges to all the Flowable UI apps. You can login with admin/test and the browser should go to the Flowable landing page:

Usually, you will want to change the default H2 in-memory database configuration to a MySQL or Postgres (or other persistent database) configuration. You can do this by changing the application.properties file in the WEB-INF/classes/ directory of the application. However, it is easier to use the Spring Boot Externalized Configuration. An example configuration can be found on Github To change the default configuration to MySQL the following changes are needed to the properties file:

spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/flowable?characterEncoding=UTF-8
spring.datasource.username=flowable
spring.datasource.password=flowable

This configuration will expect a flowable database to be present in the MySQL server and the UI apps will automatically generate the necessary database tables. For Postgres the following changes are necessary:

spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.url=jdbc:postgresql://localhost:5432/flowable
spring.datasource.username=flowable
spring.datasource.password=flowable

In addition to changing the configuration, make sure the database driver is available on the classpath. Again, you could do this for the web application by adding the driver JAR file to the WEB-INF/lib folder, but you can also copy the JAR file to the Tomcat lib folder. For MySQL and Postgres the database drivers can be downloaded from:

• MySQL: https://dev.mysql.com/downloads/connector/j

• Postgres: https://jdbc.postgresql.org/

When running the UI as a standalone application the database driver can be added by using the loader.path property.

java -Dloader.path=/location/to/your/driverfolder -jar flowable-ui.war

See the PropertiesLauncher Features in the Spring Boot reference documentation for more information.

Flowable UI Application Configuration

As the Flowable UI app is a Spring Boot application, you can use all the properties Spring Boot provides. In order to provide custom configuration for the application have a look at the Externalized Configuration section of the Spring Boot documentation.

You can also use YAML based properties.

Common UI App Properties

Property name	Old Property	Default value	Description
flowable.common.app.idm-url	idm.app.url	-	The URL to the IDM application, used for the user info and token info REST GET calls. It’s also used as a fallback for the redirect url to the login page in the UI apps. Required for standalone applications.
flowable.common.app.idm-redirect-url	idm.app.redirect.url	-	The redirect URL to the IDM application, used for the login redirect when the cookie isn’t set or is invalid.Required for standalone applications.
flowable.common.app.redirect-on-auth-success	app.redirect.url.on.authsuccess	-	The URL to which the redirect should occur after a successful authentication. Required for standalone applications.
flowable.common.app.role-prefix	-	ROLE_	The default role prefix that needs to be used by Spring Security.
flowable.common.app.tenant-id	-	-	The static tenant id used for the DefaultTenantProvider. The modeler app uses this to determine under which tenant id to store and publish models. When not provided, empty or only contains whitespace it defaults to the user’s tenant id if available otherwise it uses no tenant id.
flowable.common.app.cache-login-tokens.max-age	cache.login-tokens.max.age	30	The max age in seconds after which the entry should be invalidated.
flowable.common.app.cache-login-tokens.max-size	cache.login-tokens.max.size	2048	The maximum number of entries that the cache should contain.
flowable.common.app.cache-login-users.max-age	cache.login-users.max.age	30	The max age in seconds after which the entry should be invalidated.
flowable.common.app.cache-login-users.max-size	cache.login-users.max.size	2048	The maximum number of entries that the cache should contain.
flowable.common.app.cache-users.max-age	cache.users.max.age	30	The max age in seconds after which the entry should be invalidated.
flowable.common.app.cache-users.max-size	cache.users.max.size	2048	The maximum number of entries that the cache should contain.
flowable.common.app.idm-admin.password	idm.admin.password	-	The password used for executing the REST calls (with basic auth) to the IDM REST services. Default is test.
flowable.common.app.idm-admin.user	idm.admin.user	admin	The username used for executing the REST calls (with basic auth) to the IDM REST services. Default is admin
flowable.rest.app.authentication-mode	rest.authentication.mode	verify-privilege	Configures the way user credentials are verified when doing a REST API call: 'any-user' : the user needs to exist and the password need to match. Any user is allowed to do the call (this is the pre 6.3.0 behavior) 'verify-privilege' : the user needs to exist, the password needs to match and the user needs to have the 'rest-api' privilege If nothing set, defaults to 'verify-privilege'

Some of the old properties have been moved to be managed by the Flowable Spring Boot starter (or Spring Boot itself)

Old properties managed by the Flowable Spring Boot Starter

Property name	Old Property	Default value	Description
flowable.async-executor-activate	engine.process.asyncexecutor.activate	true	Whether the async executor should be activated.
flowable.database-schema-update	engine.process.schema.update	true	The strategy that should be used for the database schema.
flowable.history-level	engine.process.history.level	-	The history level that needs to be used.
flowable.process.servlet.name	flowable.rest-api-servlet-name	Flowable BPMN Rest API	The name of the Process servlet.
flowable.process.servlet.path	flowable.rest-api-mapping	/process-api	The context path for the Process rest servlet.
flowable.content.storage.create-root	contentstorage.fs.create-root	true	If the root folder doesn’t exist, should it be created?
flowable.content.storage.root-folder	contentstorage.fs.root-folder	-	Root folder location where content files will be stored, for example, task attachments or form file uploads.
flowable.idm.enabled	flowable.db-identity-used	true	Whether the idm engine needs to be started.
flowable.idm.password-encoder	security.passwordencoder	-	The type of the password encoder that needs to be used.
flowable.idm.ldap.base-dn	ldap.basedn	-	The base 'distinguished name' (DN) from which the searches for users and groups are started. Use 'user-base-dn' or 'group-base-dn' when needing to differentiate between user and group base DN.
flowable.idm.ldap.enabled	ldap.enabled	false	Whether to enable LDAP IDM Service.
flowable.idm.ldap.password	ldap.password	-	The password that is used to connect to the LDAP system.
flowable.idm.ldap.port	ldap.port	-1	The port on which the LDAP system is running.
flowable.idm.ldap.server	ldap.server	-	The server host on which the LDAP system can be reached. For example 'ldap://localhost'.
flowable.idm.ldap.user	ldap.user	-	The user id that is used to connect to the LDAP system.
flowable.idm.ldap.attribute.email	ldap.attribute.email	-	Name of the attribute that matches the user email. This property is used when looking for an 'org.flowable.idm.api.User' object and the mapping between the LDAP object and the Flowable 'org.flowable.idm.api.User' object is done.
flowable.idm.ldap.attribute.first-name	ldap.attribute.firstname	-	Name of the attribute that matches the user first name. This property is used when looking for a 'org.flowable.idm.api.User' object and the mapping between the LDAP object and the Flowable 'org.flowable.idm.api.User' object is done.
flowable.idm.ldap.attribute.group-id	ldap.attribute.groupid	-	Name of the attribute that matches the group id. This property is used when looking for a 'org.flowable.idm.api.Group' object and the mapping between the LDAP object and the Flowable 'org.flowable.idm.api.Group' object is done.
flowable.idm.ldap.attribute.group-name	ldap.attribute.groupname	-	Name of the attribute that matches the group name. This property is used when looking for a 'org.flowable.idm.api.Group' object and the mapping between the LDAP object and the Flowable 'org.flowable.idm.api.Group' object is done.
flowable.idm.ldap.attribute.last-name	ldap.attribute.lastname	-	Name of the attribute that matches the user last name. This property is used when looking for a 'org.flowable.idm.api.User' object and the mapping between the LDAP object and the Flowable 'org.flowable.idm.api.User' object is done.
flowable.idm.ldap.attribute.user-id	ldap.attribute.userid	-	Name of the attribute that matches the user id. This property is used when looking for a 'org.flowable.idm.api.User' object and the mapping between the LDAP object and the Flowable 'org.flowable.idm.api.User' object is done. This property is optional and is only needed if searching for 'org.flowable.idm.api.User' objects using the Flowable API.
flowable.idm.ldap.cache.group-size	ldap.cache.groupsize	-1	Allows to set the size of the 'org.flowable.ldap.LDAPGroupCache'. This is an LRU cache that caches groups for users and thus avoids hitting the LDAP system each time the groups of a user needs to be known. The cache will not be instantiated if the value is less then zero. By default set to -1, so no caching is done. Note that the group cache is instantiated on the 'org.flowable.ldap.LDAPIdentityServiceImpl'. As such, if you have a custom implementation of the 'org.flowable.ldap.LDAPIdentityServiceImpl', do not forget to add the group cache functionality.
flowable.idm.ldap.query.all-groups	ldap.query.groupall	-	The query that is executed when searching for all groups.
flowable.idm.ldap.query.all-users	ldap.query.userall	-	The query that is executed when searching for all users.
flowable.idm.ldap.query.groups-for-user	ldap.query.groupsforuser	-	The query that is executed when searching for the groups of a specific user. For example: (&(objectClass=groupOfUniqueNames)(uniqueMember={0})) Here, all the objects in LDAP with the class 'groupOfUniqueNames' and where the provided DN is a 'uniqueMember' are returned. As shown in the example, the user id is injected by the typical {@link java.text.MessageFormat}, ie by using {0} If setting the query alone is insufficient for your specific LDAP setup, you can alternatively plug in a different org.flowable.ldap.LDAPQueryBuilder, which allows for more customization than only the query.
flowable.idm.ldap.query.user-by-full-name-like	ldap.query.userbyname	-	The query that is executed when searching for a user by full name. For example: (&(objectClass=inetOrgPerson)(|({0}={1})({2}={3}))) Here, all the objects in LDAP with the class 'inetOrgPerson' and who have the matching first name or last name will be returned Several things will be injected in the expression: {0} : the first name attribute {1} : the search text {2} : the last name attribute {3} : the search text If setting the query alone is insufficient for your specific LDAP setup, you can alternatively plug in a different 'org.flowable.ldap.LDAPQueryBuilder', which allows for more customization than only the query.
flowable.idm.ldap.query.user-by-id	ldap.query.userbyid	-	The query that is executed when searching for a user by userId. For example: (&(objectClass=inetOrgPerson)(uid={0})) Here, all the objects in LDAP with the class 'inetOrgPerson' and who have the matching 'uid' attribute value will be returned. As shown in the example, the user id is injected by the typical {@link java.text.MessageFormat}, ie by using {0} If setting the query alone is insufficient for your specific LDAP setup, you can alternatively plug in a different 'org.flowable.ldap.LDAPQueryBuilder', which allows for more customization than only the query.
flowable.mail.server.host	email.host	localhost	The host of the mail server.
flowable.mail.server.password	email.password	-	The password for the mail server authentication.
flowable.mail.server.port	email.port	1025	The port of the mail server.
flowable.mail.server.ssl-port	email.ssl-port	1465	The SSL port of the mail server.
flowable.mail.server.use-ssl	email.use-ssl	false	Sets whether SSL/TLS encryption should be enabled for the SMTP transport upon connection (SMTPS/POPS).
flowable.mail.server.use-tls	email.use-tls	false	Set or disable the STARTTLS encryption.
flowable.mail.server.username	email.username	-	The username that needs to be used for the mail server authentication. If empty no authentication would be used.
flowable.process.definition-cache-limit	flowable.process-definitions.cache.max	-1	The maximum amount of process definitions available in the process definition cache. Per default it is -1 (all process definitions).

Old properties managed by Spring Boot

Property name	Old Property	Default value	Description
spring.datasource.driver-class-name	datasource.driver	-	Fully qualified name of the JDBC driver. Auto-detected based on the URL by default.
spring.datasource.jndi-name	datasource.jndi.name	-	JNDI location of the datasource. Class, url, username & password are ignored when set.
spring.datasource.password	datasource.password	-	Login password of the database.
spring.datasource.url	datasource.url	-	JDBC URL of the database.
spring.datasource.username	datasource.username	-	Login username of the database.
spring.datasource.hikari.connection-test-query	datasource.preferred-test-query	-	The SQL query to be executed to test the validity of connections.
spring.datasource.hikari.connection-timeout	datasource.connection.timeout	-	The maximum number of milliseconds that a client will wait for a connection from the pool. If this time is exceeded without a connection becoming available, a SQLException will be thrown when getting a connection.
spring.datasource.hikari.idle-timeout	datasource.connection.idletimeout	-	The maximum amount of time (in milliseconds) that a connection is allowed to sit idle in the pool. Whether a connection is retired as idle or not is subject to a maximum variation of +30 seconds, and average variation of +15 seconds. A connection will never be retired as idle before this timeout. A value of 0 means that idle connections are never removed from the pool.
spring.datasource.hikari.max-lifetime	datasource.connection.maxlifetime	-	This property controls the maximum lifetime of a connection in the pool. When a connection reaches this timeout, even if recently used, it will be retired from the pool. An in-use connection will never be retired, only when it is idle will it be removed.
spring.datasource.hikari.maximum-pool-size	datasource.connection.maxpoolsize	-	The property controls the maximum size that the pool is allowed to reach, including both idle and in-use connections. Basically this value will determine the maximum number of actual connections to the database backend. When the pool reaches this size, and no idle connections are available, calls to getConnection() will block for up to connectionTimeout milliseconds before timing out.
spring.datasource.hikari.minimum-idle	datasource.connection.minidle	-	The property controls the minimum number of idle connections that HikariCP tries to maintain in the pool, including both idle and in-use connections. If the idle connections dip below this value, HikariCP will make a best effort to restore them quickly and efficiently.
spring.servlet.multipart.max-file-size	file.upload.max.size	10MB	Max file size. Values can use the suffixes "MB" or "KB" to indicate megabytes or kilobytes, respectively.

Not used old properties

Old property	Description
datasource.jndi.resource-ref	Spring Boot does not support configuring JNDI resourceRef. Use entire resource reference in the name.
email.use-credentials	In case you don’t want to use credentials, set the password and user to empty.

Flowable IDM app

The Flowable IDM app is used for authentication and authorization. The Flowable IDM is a simple identity management component that provides a central place to define users, groups and privileges.

The IDM component boots the IDM engine at startup and will create the identity tables as defined in the IDM engine in the datasource defined in the properties configuration.

When the Flowable application is deployed and started, it will check if there’s a user available in the ACT_ID_USER table, and if not it will use the flowable.common.app.idm-admin.user property to create a new default admin user in this table. It will also add all available privileges in the Flowable project to the newly created admin user:

• access-idm: provides the privilege to manage users, groups and privileges

• access-admin: allows the user to login to the Flowable Admin app, manage the Flowable engines and access the Actuator endpoints of the application

• access-modeler: enables access to the Flowable Modeler app

• access-task: provides the privilege to login to the Flowable Task app

• access-rest-api: allows the user to do call the REST API. Otherwise a 403 (forbidden) http status will be returned. Note that flowable.rest.app.authentication-mode needs to be set to verify-privilege, which is the default.

When opening the IDM app for the first time the following user overview screen is shown:

In this screen users can be added, removed and updated. The groups section can be used to create, delete and update groups. In the group details view you can also add and remove users to and from the group. The privilege screen allows you to add and remove privileges from users and groups:

There’s no option to define new privileges yet, but you can add and remove users and groups for the existing four privileges.

Following are the IDM UI app specific properties.

IDM UI App Properties

Property name	Old Property	Default value	Description
flowable.idm.app.bootstrap	idm.bootstrap.enabled	true	Whether the IDM App needs to be bootstrapped.
flowable.idm.app.rest-enabled	rest.idm-app.enabled	true	Enables the REST API (this is not the REST api used by the UI, but an api that’s available over basic auth authentication).
flowable.idm.app.admin.email	admin.email	-	The email of the admin user.
flowable.idm.app.admin.first-name	admin.firstname	-	The first name of the admin user.
flowable.idm.app.admin.last-name	admin.lastname	-	The last name of the admin user.
flowable.idm.app.admin.password	admin.password	-	The password for the admin user.
flowable.idm.app.admin.user-id	admin.userid	-	The id of the admin user.
flowable.idm.app.security.remember-me-key	security.rememberme.key	testKey	The hash key that is used by Spring Security to hash the password values in the applications. Make sure that you change the value of this property.
flowable.idm.app.security.user-validity-period	cache.users.recheck.period	30000	How long should a user be cached before invalidating it in the cache for the cacheable CustomUserDetailsService.
flowable.idm.app.security.cookie.domain	security.cookie.domain	-	The domain for the cookie.
flowable.idm.app.security.cookie.max-age	security.cookie.max-age	2678400	The max age of the security cookie in seconds. Default is 31 days.
flowable.idm.app.security.cookie.refresh-age	security.cookie.refresh-age	86400	The refresh age of the cookie in seconds. Default is 1 day.

In addition to the default identity tables, the IDM component can also be configured to use an LDAP server. To connect to a LDAP server, additional properties in the application.properties file (or any other way of configuring the application) are needed:

#
# LDAP
#
flowable.idm.ldap.enabled=true
flowable.idm.ldap.server=ldap://localhost
flowable.idm.ldap.port=10389
flowable.idm.ldap.user=uid=admin, ou=system
flowable.idm.ldap.password=secret
flowable.idm.ldap.base-dn=o=flowable
flowable.idm.ldap.query.user-by-id=(&(objectClass=inetOrgPerson)(uid={0}))
flowable.idm.ldap.query.user-by-full-name-like=(&(objectClass=inetOrgPerson)(|({0}=*{1}*)({2}=*{3}*)))
flowable.idm.ldap.query.all-users=(objectClass=inetOrgPerson)
flowable.idm.ldap.query.groups-for-user=(&(objectClass=groupOfUniqueNames)(uniqueMember={0}))
flowable.idm.ldap.query.all-groups=(objectClass=groupOfUniqueNames)
flowable.idm.ldap.query.group-by-id=(&(objectClass=groupOfUniqueNames)(uniqueId={0}))
flowable.idm.ldap.attribute.user-id=uid
flowable.idm.ldap.attribute.first-name=cn
flowable.idm.ldap.attribute.last-name=sn
flowable.idm.ldap.attribute.group-id=cn
flowable.idm.ldap.attribute.group-name=cn
flowable.idm.ldap.cache.group-size=10000
flowable.idm.ldap.cache.group-expiration=180000

When the flowable.idm.ldap.enabled property is set to true, the IDM app will expect the other LDAP properties to have been filled-in. In this example configuration the server configuration + LDAP queries for the Apache Directory Server are provided. For other LDAP servers, like Active Directory, other configuration values are needed.

When LDAP is configured, authentication and group retrieval for a user will be done through the LDAP server. Only privileges will still be retrieved from the Flowable identity tables. So make sure each LDAP user has the correct privileges defined in the IDM app.

If the IDM component is booted with LDAP configuration the bootstrap logic will check if there are already privileges present in the Flowable identity tables. If there are no privileges (only when booting the first time), the 4 default privileges will be created and the flowable.idm.app.admin.user-id property value (from application.properties or configured in the environment) will be used as the user id to get all 4 privileges. So make sure that the flowable.idm.app.admin.user-id property value is set to a valid LDAP user, otherwise nobody will be able to login to any of the Flowable UI apps.

Flowable Modeler app

The Flowable Modeler app can be used to model BPMN processes, DMN decision table, Form definitions and create app definitions. When you open the Modeler app, you will see the process overview screen. From here you can start creating new BPMN process models by clicking on the Create Process or Import Process button.

When creating a process model (but also any other model), it’s important to think carefully about the model key value. The model key is a unique identifier for the model across the full model repository. If you choose a model key that already exists in the model repository, an error message is shown and the model is not saved.

After creating the model with the popup, the BPMN modeling canvas is shown. All BPMN elements supported by the Flowable engine are available to be used in the design of a process model.

The BPMN editor is divided into 4 parts:

• Palette: the palette of BPMN elements available to design a process model

• Toolbar: actions to change the model canvas, such as zooming, layout and saving a model

• Model canvas: the modeling canvas on which to drag and drop BPMN elements and design the process model

• Properties panel: the properties for the main process model if no element is select and otherwise the properties of the selected BPMN element

For a User task element there’s a Referenced form property in the properties panel. If you select this property, a popup is opened where you can select a form definition from the repository or create a new form. When creating a new form, a similar create dialog to the process model create dialog is presented. After filling in the name and form model key, the form editor is opened.

Form fields can be dragged from the form palette on to the form canvas. In this example, a name textfield, two date fields and a remarks multiline textfield are added to the form canvas. When editing a form field, the label, id, required status and placeholder can be filled in.

The id field is an important value, because a process variable will be created with the form field value using the id property value. When filling in the label property, the id property is automatically filled. If needed, you can also provide the id property value yourself by checking the override id checkbox.

After saving the form model and closing the form editor, you are automatically navigated back to the process model (when the form editor was opened via the BPMN editor). When selecting the User task element again and clicking on the Referenced form property you will see that the newly created form definition is now attached to the User task. When clicking on the Form tab in the header of the Modeler app, all form definitions available in the model repository are shown.

You can preview every form definition by opening the details view of a form definition. In the details view, the form name, key and description can be edited and the history of form models is available. You can also duplicate the form definition to create a new form definition with the same form fields.

Now let’s open the vacation request process model in the BPMN editor again and add a Script task to the process model, that will calculate the number of days between the vacation start and end dates. Click on the Script format property and fill in a value of groovy to instruct the Flowable engine to use the Groovy scripting engine. Now click on the Script property and fill in the script that calculates the number of days.

Now we have a amountOfVacationDays process variable we can add a Decision task to the process model. A decision task can be used to execute a DMN decision table in the Flowable DMN engine. Through the Decision table reference property, a new decision table model can be created and the DMN editor is opened.

The DMN editor provides a table editor with input columns, where input conditions can be defined with the process variables available in the process context, and output columns, where output variable values can be defined. In this very simple example there’s one input column using the amountOfVacationDays variable that checks if it’s less than 10 or higher or equal to 10. When the amount of days is less than 10, an output variable managerApprovalNeeded is returned with value false, and otherwise a value of true is returned. You can define multiple input columns and have multiple input conditions per rule. It’s also possible to leave an input column empty, which means that it’s evaluated to true for that part of the rule. You can define one or multiple output variables.

Another important part of the DMN decision table definition is the hit policy. Currently, Flowable supports the First and Any hit policy. With the First hit policy, when the first rule is found that evaluates to true the DMN execution will stop and its output variables are returned. For the Any hit policy, all rules will be executed and the output variables for the last rule that evaluates to true are returned.

When the DMN editor is saved and closed, the Modeler app navigates back to the BPMN editor and the newly created DMN decision table is now attached to the Decision task. The decision task will be generated in the BPMN XML like;

<serviceTask id="decisionTask" name="Is manager approval needed?" flowable:type="dmn">
    <extensionElements>
        <flowable:field name="decisionTableReferenceKey">
            <flowable:string><![CDATA[managerApprovalNeeded]]></flowable:string>
        </flowable:field>
    </extensionElements>
</serviceTask>

With the managerApprovalNeeded variable available in the process instance context, we can now create an exclusive gateway with a sequence flow condition that evaluates the calculated value of the DMN Engine.

The full BPMN process model now looks like this:

With the process model completed, we can now create an app definition that combines one or more process models with all their associated models (for example, decision tables and form definitions) into a single artifact. An app definition can be exported as a BAR file (zip format) that can be deployed on the Flowable engine. When creating a vacation request app definition, the app editor will look something like the screen below.

In the app editor, an icon and a theme color can be selected that will be used in the Flowable Task app to show the process app in the dashboard. The important step is to add the vacation request process model, and by selecting the process model, automatically include any form definitions and DMN decision tables.

A process model can be selected by clicking on the model thumbnail. When one or more models are selected, you can close the popup, save the app definition and close it. When navigating to the details view of the newly created vacation request app definition, the following details screen is shown:

From this view, you can download the app definition in two different formats. The first download button (with the arrow pointing downwards) can be used to download the app definition with the JSON model files for each included model. This makes it easy to share app definitions between different Flowable UI applications. The second download button (with the arrow point to upper right) will provide a BAR file of the app definition models, which can be deployed on the Flowable engine. In the BAR file, only the deployable artifacts are included, such as the BPMN 2.0 XML file and the DMN XML file, and not the JSON model files. All files in a BAR file deployed on a Flowable engine are stored in the database, so therefore only the deployable files are included.

From the app definition details view, you can also Publish the app definition directly to the Flowable engine. The Flowable Modeler can only deploy if it is part of the single UI app (i.e. the engines are present during the runtime). Once you click on the Publish button, the app definition is now deployed as a BAR file to the Flowable UI runtime engines.

This are the Modeler UI App specific properties.

Modeler UI App Properties

Property name	Old Property	Default value	Description
flowable.modeler.app.data-source-prefix	datasource.prefix	-	The prefix for the database tables.
flowable.modeler.app.rest-enabled	rest.modeler-app.enabled	true	Enables the REST API (this is not the REST api used by the UI, but an api that’s available over basic auth authentication).

Flowable Task app

The Flowable Task app is the UI to the runtime engines of the Flowable project and includes the Flowable BPMN, DMN, Form and Content engines by default. With the Flowable Task app, new process instances can be started, tasks can be completed, task forms can be rendered and so on. In the previous section, the vacation request app definition was deployed on the Flowable Task app REST API, and through that deployed on the Flowable engine. If you look in the Flowable database, you can see a new deployment entry has been added to the ACT_RE_DEPLOYMENT table for the BPMN Engine. Also, new entries haven been created in the ACT_DMN_DEPLOYMENT and ACT_FO_FORM_DEPLOYMENT tables for the DMN and Form engines.

On the dashboard in the Task app, you can see a vacation request app in addition to the default Task app, and any other apps that have been deployed to the Flowable engine already.

When clicking on the vacation request app, the task list for the logged-in user is shown (which is probably empty for now).

When clicking on the Processes tab you can choose to start a new process instance by clicking on the Start a process button. The list of available process definitions within the context of this app definition is now displayed. In the general Task app this works in a similar way, but in the Task app, all process definitions deployed on the Flowable engine are shown. After selecting the vacation request process definition, the Start process button can be clicked to start a new vacation request process instance.

The Flowable Task app automatically navigates to the process instance details view. You can see the Provide vacation information task is active and, for example, comments can be added and the process instance state can be shown diagrammatically using the Show diagram button.

When navigating to the task list, you can also see the Provide vacation information task listed there as well. The task details are shown in this view, with the vacation info form being rendered. You can also switch to the details view by clicking on the Show details button. In the details view, comments can be added, users can involved in the task and attachments can be added to the task. You can also change the due date and the assignee of a task.

Let’s fill in the form and complete the task. First, select a start date and end date that have more than 10 days in between, so we can validate that a Manager approval task is being generated. After filling in the vacation info form and clicking the Complete button, the Flowable task app navigates directly to the Manager approval task view. When you also complete this task (without a task form), the process instance is completed.

When navigating to the Processes tab and clicking on the Showing running processes section, you can select an option to show completed process instances. The list of completed process instances is now shown and when clicking on the just completed vacation request process you can see the two completed tasks.

The completed form of each task is stored in the ACT_FO_FORM_INSTANCE table of the Flowable Form engine. So it’s possible to look at the values of each completed form when you navigate to the completed task.

Make sure to switch back to showing running processes instead of the completed ones, otherwise you won’t see newly started process instances. You can also filter tasks in the task list view. There are options to search on the name of a task, the task state, only tasks for a specific process definition and change the assignment filter.

By default, the assignment filter is set to Tasks where I am involved. This doesn’t show the tasks where you are a candidate, such as tasks that are available to a specific candidate group before they are assigned to a specific person. To show candidate tasks you can select the Tasks where I am one of the candidates assignment filter option.

This are the Task UI App specific properties.

Task UI App Properties

Property name	Old Property	Default value	Description
flowable.experimental.debugger.enabled	debugger.enabled	false	Whether the process debugger should be enabled.
flowable.task.app.rest-enabled	rest.task-app.enabled	true	Enables the REST API (this is not the REST api used by the UI, but an api that’s available over basic auth authentication).
flowable.form-field-validation-enabled		false	Enable form field validation after form submission on the engine side.

Flowable Admin app

The fourth UI component the Flowable project provides is the Flowable Admin app. This provides ways to, for example, query deployments in the BPMN, DMN and Form Engines, but also shows the active state of a process instance with its active tasks and process variables. It also provides actions to assign a task to a different assignee and to complete an active task. The Flowable Admin app uses the REST API to communicate with the Flowable engines. By default, it is configured to connect to the Flowable UI REST API, but you can easily change this to use the Flowable REST app REST API instead. When going to the Admin app, the configuration screen is shown (which is also available by clicking on the arrow at the top right near the Flowable logo).

For each engine, the REST endpoint can be configured with the basic authentication values. The configuration is done per engine, because it’s possible to, for example, deploy the DMN Engine on a separate server from the BPMN Engine.

When the configuration is defined with the correct values, the Process Engine can be selected to administer the Flowable BPMN engine. By default, the deployments of the Flowable BPMN engine are shown.

You can filter the deployments based on name and tenant identifier. In this view, it’s also possible to deploy a new BPMN XML file or BAR file to the Flowable engine. When clicking on one of the deployments, the deployment details view is shown.

More details of a deployment are shown here and also the process definitions that are part of this deployment on which you click to get more details. It’s also possible to delete a deployment here. When you want to delete a deployed app definition, this is also the way to delete the app definition from the Flowable Task app dashboard. When clicking on one of the process definitions, the process definition details view is shown.

In the process definition details view, the first page of process instances is shown, together with optional decision table definitions and form definitions that are used in the process definition. For the vacation request process definition, there’s one connected decision table and one connected form definition. Clicking on the decision table definition navigates the Flowable Admin app to the DMN engine. You can always navigate back to the Process engine by clicking on the Parent Deployment ID link.

In addition to the deployments and definitions, you can also query on process instances, tasks, jobs and event subscriptions in the Process engine. The views all work in a similar way to what’s already been described.

This are the Admin UI App specific properties

Admin UI App Properties

Property name	Old Property	Default value	Description
flowable.admin.app.data-source-prefix	datasource.prefix		The prefix for the database tables.
flowable.admin.app.security.encryption.credentials-i-v-spec	security.encryption.credentials-i-v-spec	-	The string that needs to be used to create an IvParameterSpec object using it’s the bytes.
flowable.admin.app.security.encryption.credentials-secret-spec	security.encryption.credentials-secret-spec	-	The string that needs to be used to create a SecretKeySpec using it’s bytes.
flowable.admin.app.security.preemptive-basic-authentication		false	Perform a preemptive basic authentication when issuing requests to the flowable REST API. NB: This is an experimental property and might be removed without notice.

In addition to these properties, the Flowable admin app has a few more properties. The full content of the properties file can be viewed on {sc-flowable-ui-admin}/flowable-ui-admin-app/src/main/resources/application.properties[Github]. The additional properties are mainly used for defining the initial values for the REST endpoints for the different engines. The Admin app uses the initial values to make a connection to the Flowable engines, but the values can be overridden in the Admin app configuration view and these values are stored in the ACT\_ADM\_SERVER\_CONFIG table. An example of the BPMN Engine REST properties is shown below:

flowable.admin.app.server-config.process.name=Flowable Process app
flowable.admin.app.server-config.process.description=Flowable Process REST config
flowable.admin.app.server-config.process.server-address=http://localhost
flowable.admin.app.server-config.process.port=8080
flowable.admin.app.server-config.process.context-root=flowable-ui
flowable.admin.app.server-config.process.rest-root=process-api
flowable.admin.app.server-config.process.user-name=admin
flowable.admin.app.server-config.process.password=test

These values can be used when multiple Flowable UI applications (with all the Flowable engines included) are managed by the Flowable Admin app.

Admin UI App Properties managed by Spring Boot

Old property	Description
message.reloading.enabled	Using Spring Boot MessageSourceAutoConfiguration. Set the duration with spring.messages.cache-duration.

Internationalization

The Flowable UI application supports internationalization (i18n). The project maintains the English translations. It is however possible to provide your own translation files in order to support other languages.

The Angular Translate library tries to load a specific translation file based on the browser’s locale located in the i18n folder (present in each UI module). When a matching translation file cannot be loaded the framework will fallback to the English translation.

Mapping multiple browser locale keys to specific translations additional configuration can be provided (located in the Angular app config);

// Initialize angular-translate
$translateProvider.useStaticFilesLoader({
    prefix: './i18n/',
    suffix: '.json'
})
/*
    This can be used to map multiple browser language keys to a
    angular translate language key.
*/
// .registerAvailableLanguageKeys(['en'], {
//     'en-*': 'en'
// })
.useCookieStorage()
.useSanitizeValueStrategy('sanitizeParameters')
.uniformLanguageTag('bcp47')
.determinePreferredLanguage();

For example; your browser is configured for English (United States) and provides the language key en-US. Without the mapping Angular Translate will try to fetch the corresponding translation file en-US.json. (If this is not available it will fallback to 'en' and load the en.json translation file)

By uncommenting the .registerAvailableLanguageKeys block you can map en-US (and all other en language keys) to the en.json language file.

Production-ready endpoints

The Production ready endpoints from Spring Boot are present for the application. To have an overview of all the available Endpoints have a look at the Actuator Web API Documentation.

This properties are set per default:

# Expose all actuator endpoints to the web
# They are exposed, but only authenticated users can see /info and /health abd users with access-admin can see the others
management.endpoints.web.exposure.include=*
# Full health details should only be displayed when a user is authorized
management.endpoint.health.show-details=when_authorized
# Only users with role access-admin can access full health details
management.endpoint.health.roles=access-admin

The security is configured in such way that the info and health endpoint are exposed to all authenticated users. Full details of the health endpoint can only be seen by users with the privilege access-admin. In case you want to change that you need to configure management.endpoint.health.show-details. All the rest of the endpoints are accessing only to users with the access-admin privilege.

Custom bean deployment

There are multiple ways of providing custom beans to the Flowable application.

Using Spring Boot auto configuration

The Flowable application is a Spring Boot 2 application. This means that normal Spring Boot auto configuration can be used to make the beans to Flowable. This can be done in the following manner

package com.your.own.package.configuration;

@Configuration
@AutoConfigureOrder(Ordered.LOWEST_PRECEDENCE) // Makes sure that this configuration will be processed last by Spring Boot
@ConditionalOnBean(type = "org.flowable.engine.ProcessEngine") // The configuration will only be used when the ProcessEngine bean is present
public class YourOwnConfiguration {

    @Configuration
    @ComponentScan ("com.your.own.package.beans")
    public static class ComponentScanConfiguration {
        // This class is needed in order to conditionally perform the component scan (i.e. when the ProcessEngine bean is present)
        // It is an optional class, in case you don't need component scanning then you don't need to do this
    }

    @Bean
    public CustomBean customBean() {
        // create your bean
    }

    @Bean
    public EngineConfigurationConfigurer<SpringProcessEngineConfiguration> customProcessEngineConfigurationConfigurer() {
        return engineConfiguration -> {
            // You can use this to add extra configuration to the process engine
        }
    }
}

Note that when using Spring Boot the configuration class can be under your own package and not under some Flowable package.

In order to make this class an auto configuration class a file named spring.factories should be created in the META-INF folder of your jar. In this file you should add

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  com.your.own.package.configuration.YourOwnCustomConfiguration

In order to use this approach you would need to include your jar in the WEB-INF/lib folder of the exploded war. Placing this jar in the lib folder of the servlet container (e.g. Tomcat) is not going to work due to the way Spring proxies the @Configuration classes.

Component scan

Another way to provide custom Spring beans to the Flowable engine is to put them under a certain package and have the Flowable application component scan that package. Based on the application used, this package is different:

• org.flowable.rest.app for the flowable-rest.war

• org.flowable.ui.application for the flowable-ui.war

The custom beans can be located in a single JAR and this jar should be present on the classpath when the application is starting up. Depending where there JAR is placed, the lib folder of the servlet container (e.g. Tomcat) or the WEB-INF/lib folder of the exploded war, there are different possibilities.

When using the lib folder of the servlet container then the created classes should be self contained, i.e. they should only use classes from within the jar. You can use any of the Spring @Component annotations (with the exception of @Configuration). The reason for not being able to use @Configuration classes is the fact that each configuration class is proxied by Spring with the help of the ConfigurationClassPostProcessor. However, the classloader loading the @Configuration class does not have access to the needed classes by Spring.

When including the jar in the WEB-INF/lib folder of the exploded war then @Configuration classes and dependencies to other jars is possible.

Creating your own Spring Boot application

This approach is the most flexible and most powerful approach of all. In order to follow this approach have a look at the Getting Started with Spring Boot section of this documentation.