Validating empty business process mandatory fields on the template level

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. General description

When modeling business processes, Element Templates are used for the typical BPMN elements (service tasks, user tasks, etc.) together with a description of the corresponding contract. For the input parameters of this type of templates, validation is configured, which works on the client side in Regulation Modeling Web Interface. However, as part of the implementation, the validation rules were not applied to all required parameters of Element Templates. Because of this, a modeler sees the absence of a required field only when executing the business process, and not when simulating it. It is necessary to apply validation rules within the current solution for all Element Templates and additionally develop a server validation mechanism.

2. Concepts

Element Templates: Camunda element templates that simplify the process of business process modeling. See details at the link.
Regulations validation pipeline: Jenkins Code Review pipeline that is launched when changes are made to the candidate version, or directly to the RM in Gerrit.
Regulation publication pipeline: Jenkins Build pipeline that is launched when changes are made to the master version of the registry regulations.

3. Functional scenarios

Using Element Templates when modeling business processes of the registry regulations in the Regulations Modeling Web Interface.
Validation of the task template input parameters in the Regulations validation pipeline when modeling the regulations.
Validation of the task template input parameters in the Regulations publishing pipeline when modeling the regulations.
Validation of the task template input parameters in the Regulations modeling pipeline when modeling the regulations.
Validation the task template input parameters in the Regulations publication pipeline when deploying the regulations to the production environment

4. User roles

Registry developer
Registry administrator

5. General principles and provisions

5.1. Server Validation

Server validation of Element Templates takes place according to the general principles of the registry regulations validation in the Regulations publication pipeline and the Regulations verification pipeline.
The registry regulations validation step adds to the Regulations verification pipeline.
Validation of the Element Templates input parameters must be performed using the registry-regulations-validator-cli utility.
In case of input parameter validation errors in Element Templates, the Regulations validation pipeline must display an error with a clear message to understand the error.
Validation rules use the same version of Element Templates as for Regulations Modeling Web Interface.
The version of Element Templates must correspond to the version of the registry. That is, Element Templates can be modified only when the registry version is updated.
ConfigMap is used for saving Element Templates, which is updated when the registry version is updated.
The standard element templates (constraints) mechanism is used to describe the validation rules.
As part of the current solution, only notEmpty constraint validation is supported (100% of use cases in platform version 1.9.5).

5.2. Validation in the Regulations Modeling Web Interface (current state)

When developing a task template, you can specify the field type of the input parameter.
The client-side validation is supported only when the input parameter type is specified.
In Camunda version 7.x, it is possible not to specify the type of the input parameter.
The following types of input parameters are currently supported: String, Text, Boolean, Dropdown and Hidden.
For listing the task templates in the platform, the Map type must be used, which is not supported in Camunda version 7.x/8.x.
If you do not specify the input parameter type, the modeler will have to independently choose the Map type from the list.
Typed input parameters are shown in the Custom Properties section, while untyped ones are shown in the Input Parameters section.

Camunda 8.x does not support untyped input parameters. Read details here.

Figure 1. Modeling panel. Typed parameters

Figure 2. Modeling panel. Untyped parameters

Figure 3. Modeling panel. Mixed parameters

6. High-level solution design

Figure 4. Component diagram

Figure 5. Deployment diagram (current)

Figure 6. Deployment diagram (target)

Figure 7. Validation of the element template parameters in the regulations validator

7. Decision log

Approach to validation:
- 2 approaches to the validation of Element Templates were compared at the level of the Regulations publication pipeline and the Regulations validation pipeline:
  - Parameter validation rules are stored directly in the BPMN file.
  - Validation rules are stored separately together with the specifications of input parameters in Element Templates.
- The main principles behind choosing the 2nd approach:
  - Centralized approach to storing validation rules.
  - Maintaining the standard BPMN/camunda schema for the bpmn files for compatibility reasons.
  - Making it impossible for a modeler to exclude validation rules when using Element Template.
Client-side validation:
- A POC was conducted, as a result of which it was found that customization of the simulator panel is possible only in case of a fork of the bpmn-js-properties-panel library.
- It was decided not to fork the library for updating to new versions and to leave the client-side validation unchanged.
- Further extension of the simulator panel for autotips is possible without a fork of the library.
Approach to the ConfigMap deployment with a list of Element Templates has to be redone, and the files and templates has to be made a part of the registry-configuration component.

8. Scope of work

8.1. Preliminary decomposition

[DEVOPS] Move files from element templates to the registry-configuration repository and create OpenShift ConfigMap.
[DEVOPS] [FE] Rename ConfigMap from element templates to business-process-modeler-element-templates.
[FE] Rework the logic for reading the value from ConfigMap (common json instead of js file).
[DEVOPS] Add the regulations validation step to the regulations validation pipeline.
[DEVOPS] Remove the post-upgrade script from common-web-app for filling ConfigMap with element templates.
[BE] Add the element template validation parameters to the regulations validator (in the scope only the notEmpty constraint type with possible further extension).
[BE] Add typing of input parameters in Element Templates with required validation (switching to a mixed approach of input parameters).
[FE] Add blocking for saving changes in the Regulation Modeling Web Interface if Element Template has not been validated.

8.2. Out of scope

Customization of the simulator panel that requires a fork of the library:
- Adding the new Map input parameter type.
- Blocking for saving changes in the Regulations Modeling Web Interface if Element Template has not been validated.
- Combining two sections — Inputs (untyped input parameters) and Custom Properties (typed input parameters) — into one.
Support of the server-side validation for types not supported by the standard element templates mechanism.
Support of the server validation using the pattern (regexp), minLength and maxLength.

9. Limitations of the solution

The client-side validation remains incomplete due to the lack of support of the Map parameter type.
The backend-side Validation is asynchronous in the publication pipeline (there is no quick feedback to a user).
Existing business processes with element templates that do not meet the validation rules may cause a pipeline deployment error when upgrading to a new version.