Manage workflows via our Business Process Management (BPM) Engine based on Flowable.

Table of Contents

Characteristics

Service Name	`bpm-engine`
Port Range	`8080`
Profiles	`-`
Helm Chart	`bpm`
Public API	BPM Engine Endpoints

Function

In order to establish a standardized approach when working with such a large amount of documents, companies that use DMS systems need to establish and enforce business rules for their processing. For instance, an employee must know which steps are to be performed with an invoice document in order to pay an invoice to a third party, while still complying with bookkeeping rules of the company. The business rules also include multiple technical steps that should be performed by the employee in order to comply with these business rules as well as with the legal norms. For instance, a payed invoice must be marked as such in order to avoid double payment of it, and the retention time of it should be set, to prevent deletion within the time period defined by the law. All this puts a considerable cognitive load onto employees working with documents, since they have to execute their primary task of processing the invoice, while keeping the status of the document up to date (how far has the payment process progressed and what has been done so far) and setting such purely technical fields on the document.

yuuvis® Momentum is a powerful DMS system that can handle hundreds of millions of documents with ease—whether they are of numerous types, spread over multiple tenants or used by hundreds or thousands of users. In order to efficiently adopt and enforce the business rules, a considerable automation is necessary to be able to support the employees who work on the documents. And that is why we integrate the yuuvis® Momentum DMS with a workflow functionality in form of a BPM Engine. The DMS stores and manages the documents, and BPM Engine implements the business rules that define how documents are processed in a company. Implementing the business rules as workflows is not only an automation capability, but also a great opportunity for companies to document their business rules.

>> Business Process Management (BPM) Engine

Requirements

>> yuuvis® Momentum Requirements - BPM Engine

Setting up Identity Management for BPM-ENGINE

The BPM-ENGINE service is based on the workflow functionality of the open source software Flowable. The service is connected to Keycloak in order to obtain information on users and their roles present in the tenant. The Business Process Management can be used only if yuuvis® Momentum uses Keycloak as identity provider and role management system.

Flowable and Keycloak

If Keycloak is used as identity provider and role management system, users are registered as members of realms (corresponding to yuuvis® Momentum tenants) with defined roles assigned to them. Furthermore, users can be assigned to groups which can build a hierarchical structure.

The Keycloak realms and users are directly mapped to tenants and users in Flowable and thus in the BPM-ENGINE. The Keycloak groups are not mapped to Flowable. Keycloak supports the hierarchical group structure that is unique for every tenant. Hierarchical group structures are not supported in Flowable and in addition, since the group structure is unique for every tenant, it would not be possible to develop a model that is valid in multiple tenants and that assigns a user task to a specific group (such as "bookkeepers"). To resolve both of these integration issues, we map the users' Keycloak roles to Flowable groups. Since roles form a flat structure and can be assigned to users from different tenants, they correspond to the groups of users as defined in Flowable.

Once correctly configured, the Groups and Users interface in Flowable REST will provide information on users and groups within the BPM-ENGINE. However, it is not possible to edit users or groups via the BPM-ENGINE service. This has to be done in Keycloak.

BPM-ENGINE Service Configuration

Following service configuration parameters are available.

Parameter						Description	Default Value
`bpm`						Section of parameters defining BPM-internal settings.	-
	`engine`					Section of parameters related to the BPM-ENGINE service.	-
		`app`				Section of parameters.	-
			`global-tenant`			Specifies the master Flowable tenant which has access to all other tenants. As of version 2021 Autumn: If access to all tenants should be enabled also via BPM-ADMIN-UI, the same tenant has to be set for the parameter `bpm.admin.app.default-user-authentication.user.tenant`.	`'master'`
			`admin-access-role`			Specifies the role granting the permission to access all tenants. Users with the specified role furthermore have admin rights for processes and are thus able to manage all processes (not only their own ones, as it is the case for "normal" users). As of version 2021 Autumn: If access to all tenants should be enabled also via BPM-ADMIN-UI, the same role has to be included in the list defined for the parameter `bpm.admin.app.default-user-authentication.user.privileges`.	`'YUUVIS_TENANT_ADMIN'`
		`idm`				Section of parameters for the connection of an identity provider.
			`keycloak`			Section of parameters only required if Keycloak is used as identity provider.
				`enabled`		Boolean value that specifies if BPM Engine connects to Keycloak/KEYCLOAK-PROXY Service (`true`) or to a different identity provider (`false`). If `true`, the parameter `bpm.engine.idm.custom.enabled` must be `false`.	`true`
				`server`		URL of the Keycloak server that should be used for authentication.
				`admin`		Section of parameters specifying the access credentials for the technical user account used by the BPM-ENGINE service in order to authenticate in Keycloak.	n/a
					`username`	Username for technical user account.
					`password`	Password for technical user account.
			`custom`			Section of parameters only required if Keycloak is not used as identity provider.
				`enabled`		Boolean value that specifies if BPM Engine connects to Keycloak/KEYCLOAK-PROXY Service (`false`) or to a different identity provider (`true`). If `true`, the parameter `bpm.engine.idm.keycloak.enabled` must be `false`.	`false`
				`base-url`		URL to the identity provider or to the idm-controller of the TENANT-MANAGEMENT Service.	`'http://tenant-management/api/idm'`

As of product version 2022 Autumn: If you use Microsoft SQL Server as database for the BPM-ENGINE service, the corresponding JDBC driver requires an SSL connection. For a connection without SSL, append encrypt=false to the connection string in your configuration:

Option 1: Set environment variable

You can change the BPM-ENGINE service configuration via environment variable in the deployment, e.g.:

- name: SPRING_DATASOURCE_URL
  value: jdbc:sqlserver://sqlserver2019-mssql-latest.sqlserver2019:1433;databaseName=erebus;encrypt=false

Option 2: Use YML configuration file and profile

Create an application-bpmdb.yml configuration file with following parameter:

spring.datasource.url: 'jdbc:sqlserver://${db.host:localhost}:${db.port:1433};databaseName=${db.name:yuuvis};encrypt=false'

Start the BPM-ENGINE service with the additional bpmdb profile:
```
- name: SPRING_PROFILES_ACTIVE
  value: bpmdb,swagger
```

Up to version 2022 Summer, BPM Engine has to be configured as follows. Especially, the conversion of the Keycloak roles into Flowable groups can be customized via the keycloak.idm.groups.role-filter parameter.

Parameter				Description	Default Value
`keycloak`				Section of parameters defining the connection of the BPM-ENGINE service to Keycloak.	-
	`server`			URL of the Keycloak server that should be used for authentication.	`"http://localhost:8000/auth"`
	`admin`			Section of parameters specifying the access credentials for the technical user account used by the BPM-ENGINE service in order to authenticate in Keycloak.	n/a
		`username`		username for technical user account
		`password`		password for technical user account
	`idm`			Section of parameters defining conversion configurations for the connection between Keycloak and the BPM-ENGINE service.	-
		`groups`		Section of parameters dealing with the conversion of Keycloak roles into BPM-ENGINE groups.	-
			`role-filter`	Contains a regular expression that filters the roles from Keycloak such that only those Keycloak roles that match the condition are visible to the BPM-ENGINE service. Example: With the filter `^(YUUVIS)(.*)` only roles with names starting with `YUUVIS` will be visible to the BPM-ENGINE service.	`"^(.+)"`

Browser not supported