Workflows (BPMN)
SINCE VERSION 1.0 DRAFT
What is a BPMN Workflow?
BPMN (Business Process Model and Notation) is an internationally recognized ISO standard for formally describing business processes in a graphical format. It facilitates discussion, ensures compatibility between business and technical teams, and enables seamless collaboration across departments and organizations.
BPMN represents a stateful business process, often involving one or more interactions with humans. In PIPEFORCE, BPMN workflows can be modeled and initiated through a graphical web interface, with the optional capability to directly start the execution of automation pipelines.
Note: If there are no interactions with humans required in your workflow, consider to use an automation pipeline instead. In this case probably no BPMN is required. But it depends on your use case.
If you’re not familiar with the BPMN concept so far, we highly recommend you to learn the basics before you dive deeper into this chapter. Here you can find a first introduction on Wikipedia: Business Process Model and Notation .
Modelling a BPMN Workflow
Below is a very simple example of a BPMN diagram, which shows a vacation approval process where the employee must fill-out a request form, and the supervisor can then approve or decline the vacation request:
As you can see, it is quite easy to understand what is going on in this workflow.
A BPMN workflow typically has a single start event, one or more user or service tasks and a single end event. There are more elements possible, just to name a few for now.
Such BPMN workflows are typically designed using a BPMN modeller tool. You can use your own local software to design such a diagram and then upload it to PIPEFORCE, or you can use the built-in online BPMN modeller from PIPEFORCE, which supports these additional features:
Discuss a BPMN diagram with your team.
Create or link service tasks with data pipelines.
Create or link user tasks with input forms.
Deploy and start the diagram with one click so it becomes a workflow instance executing a real process.
Monitor running workflow instances.
In order to draw a BPMN diagram, the most important elements are these:
Lets shortly explain those basic items below.
Start Item
This is the starting point of a BPMN workflow and defines how the workflow will be started. This can be done manually or triggered by an event for example. If nothing is defined, it is always considered to be started manually.
User Task
The user task is the part of a workflow in case manual input from a user is required. For example to review some data and approve it. This input is typically requested using a form showing one or more form fields to the user he then can fill out.
Form
The workflow waits at this user task until the user has filled-out the form and finished this task by clicking the COMPLETE button of the form. In PIPEFORCE such a form can be defined in the online modeller using the FORM tab.
There are two form types available you can select from:
Simple = The form fields can be directly defined in the tab and will be displayed vertically one after another. This is the simplest approach but is limited. So for example you can not change the orientation of the fields, no special fields are supported, fields are limited to max. 4000 chars and validation is also quite limited.
Custom = These are advanced forms where you have full flexibility of the PIPEFORCE form framework to design your user task form. With this flexibility also a bit more complexity comes. See here for documentation about the form framework: Forms.
Assignment
User tasks can be assigned in the workflow to specific users and user groups, by using the GENERAL tab. This can be done in the Assignment section:
Assignee is a single username. If defined, the user task will be automatically assigned to the user with this username when created.
The Candidate Users field define the users allowed to pick and claim this task. They will see the task instance of example in the TODO filter which can be seen as a “task pool”. Same is true if user is member in one of the groups mentioned in the Candidate Groups field. Multiple entries in these fields must be separated by comma.
Service Task
If a task in the BPMN workflow must be executed by an automated service (“machine”), it must be marked as a service task. Such automated steps could be for example sending an email, doing a data conversion, connecting to external systems or much more complex steps. Here full automation is possible.
By default, such a service task is linked to a data pipeline which defines all these “instructions” to the “machines” (services) to be executed in an automated way as soon as the workflow arrives at this service task.
You can link a service task to a data pipeline by clicking the service task and then in the PIPELINE tab select an already existing data pipeline you would like to execute when this service task starts. Or you create a new pipeline and link it there.
Decision Gateway
In case the flow direction inside a BPMN workflow must change depending on a condition, a decision gateway or just gateway in short can be used. For example if the user has approved a request in the form, this approval information can be used to decide to follow the approval path.
End Item
The end item (also known as end state) defines when the process must be finished. Typically a BPMN workflow must always have exactly one such end state. There are some rarely cases which could differ from that.
How to start a workflow in PIPEFORCE?
The design and execution of a workflow in PIPEFORCE is always a 3-steps task:
Design the workflow in the BPMN modeler, and save the result. When you work locally with the pi tool, save it at:
app/myApp/workflow/myWorkflow.bpmn
.Deploy by pushing the DEPLOY button in the online designer, or upload the BPMN file using the pi tool by calling the command:
pi publish
.Execute the workflow using the command
workflow.start
in a pipeline, and set the Id of your process as the parameter key (see BPMN file). You can use, for example, the pi tool to start a workflow:pi uri ”workflow.start?key=<ID>”
Then, you can login to your portal at https://<NAMESPACE>.pipeforce.net
, and complete the workflow.
How to create a trigger pipeline
A pipeline, executed when an app is started, is called a trigger pipeline. Each pipeline is written in YAML format.
This pipeline listens to the new form entry.
Sets the variables
Maps the form data to workflow model (workflow data).
Perform different operations on file / directories if needed.
Save the data in variables, which we can use later in our next steps / pipelines.
Let's create a simple trigger pipeline:
1. Headers
The headers section is optional in our trigger pipeline. It is used to configure any global variable which is used to execute the pipeline e.g. description of the pipeline, auto execute pipelines, manage versions, user authorization, etc. Headers can be used in pipeline like following:
headers:
description: "A010 listens for a new form entry, maps form data to workflow model + starts the workflow"
Note: To get more details regarding this feature, please see: Headers
2. Vars
This section is also optional in our trigger pipeline. This helps to initialize the variables and set those variables later in the other steps in the same pipeline.
vars:
workflowModelInstanceKey: null # To be set by the workflow when calling this pipeline
workflowModel: "#{@property.lazy(vars.workflowModelInstanceKey)}"
3. Pipeline
Pipeline section is mandatory for execution of any application. It includes all the commands which are executed in the sequential order. We use the Pipeline Expression Language (PEL) to write the expressions in pipeline. Scope of pipeline is defined as follows:
Listen to events:
Every time an event is fired after matching the given criteria, all commands after the event.listen, will be executed. It executes commands like creation of property, copy property, delete property, error handling on login, etc. For example, creation of a new property store every time the pipeline is executed.
pipeline: - event.listen: key: "property.created" filter: "#{body.payload.target.key.contains('global/app/travelexpense/object.travelexpense/v1/instance')}"
Note: To get more details regarding this feature, please see: Events
Capture the data:
Data, which is entered in start form entry, is captured and converted into the required format e.g. converting the form values (object) into a map.
Note: To get more details regarding this feature, please see: Convert
Initialize the variables: Set the values of variables and update / save them e.g.
Manage attachments: It helps to manage files / attachments uploaded from the entry-form and save them to a particular path / directory. Here is the bifurcated example to do this task:
Create Directory / Folder
Note: To get more details regarding this feature, please see: drive.archive.save
Here, to create a directory, we need to run the pipeline as the system user, because only that user has the folder creation rights.
Get Attachment and Get Content
Get file from entry-form and save into a variable
Get content of file
Note: To get more details regarding this feature, please see: property.attachment.chunk.get
Save the file into drive
Create roles or groups : You can also create your own role or group of roles. e.g.
Roles / Groups are created only by running the pipeline with system user only.
Note: To get more details regarding this feature, please see: property.attachment.chunk.get
Give permissions for accessing files to a role or a group.
Evaluate any expressions.
4. Workflow Model
Workflow model enables you to map your data from entry-form to your application workflow. It allows us to use the inputted data throughout the application. The workflow model can be defined as follows:
Here, we define all the variables in key:value pair and store it in our workflow model.
Note: To get more details regarding this feature please see: Workflow Model
5. Save Workflow Model Into Schema
It enables you to save the entry-form data into a schema. Schema is a file where we define all the fields that are there in entry-form with their data types. The file is in JSON format. e.g.
Note: To get more details regarding this feature, please see: property.schema.put
6. Start Workflow
In this section, we define those variables which we process and use them in the subsequent steps. We use workflow.start to start processing the fields from the entry-form and map them in key:value pair and then use later in different pipelines e.g.
Note: To get more details regarding this feature, please see: workflow.start
You can access these process variables in the next pipeline as following:
vars.fname, vars.email, vars.account, vars.comment
BPMN Gateway
A gateway in BPMN is a branch of the workflow. Depending on a condition, the flow of the process can branch into different directions.
Where to define gateways conditions?
In this example, depending on whether the supervisor has approved or declined the vacation request, the workflow should execute the “Send declined email” or the “Send approved email” task. For this, we need to define rules on the gateway edges:
To define the rule for the decline gateway, select the declined edge of the gateway and fill-in this condition:
${vacationApproved == false}
:This makes sure that this branch is executed in case the supervisor set
vacationApproved
to false in the task form.Repeat these steps for the task “Send approved email”, and set the condition to
${vacationApproved == true}
.Click
SAVE
to save the current state of the BPMN workflow.
How to design gateways
The gateway design is defined by a specific expression language named JUEL. Below, you will find that the most important operators are:
Arithmetic:
+
,-
(binary),*
,/
anddiv
,%
andmod
,-
(unary)Logical:
and
,&&
,or
,||
,not
,!
Relational:
==
,eq
,!=
,ne
,<
,lt
,>
,gt
,<=
,ge
,>=
,le
. Comparisons can be made against other values, or against boolean, string, integer, or floating point literals.Empty: The
empty
operator is a prefix operation, that can be used to determine whether a value isnull
or empty.Conditional:
A ? B : C
. EvaluateB
orC
, depending on the result of the evaluation ofA
.
For more details see Unified Expression Language - The Java EE 5 Tutorial
Examples of gateway conditions
Condition for dropdown
Condition refers to a field named “decision”
Field provides a dropdown list for the user (Approve, Decline, or Delegate)
Gateway should represent the “Approve” selection
Condition looks like this:
Condition for checkbox
Condition refers to a field named “checked”
Field provides a checkbox
Gateway should represent the situation that the checkbox is ticked
Condition looks like this:
${ checked } works as well. Similarly, ${ !checked } can be used in place of ${ checked == false }
Condition for value
Condition refers to a field named “Kosten”
Field provides the option to type in numbers
Gateway should represent the situation that the value is > 100, but < 1000
Condition looks like this:
Multiple conditions
Condition refers to the fields: “decision” and “checked”
Field “decision” provides a dropdown list for the user (Approve, Decline, or Delegate)
Field “checked” provides a checkbox
Gateway should represent the situation that:
“Approved” is selected from dropdown
Tick is set for “checked”
Condition looks like this:
Workflow Variables
All values entered in a form are stored in variables and can be displayed & edited with subsequent task forms. In this section, you will learn how to display those variables.
Define form fields as workflow variables
In case, you are defining form fields via the Online Workflow Modeler, like in the example below, all field IDs are directly stored as workflow variables. If you use those IDs in multiple steps in the workflow model, the content entered in previous steps are displayed automatically.
In case, you would like to use workflow variables from a trigger form, there are a few additional steps to do. These steps are described in this tutorial Tutorial: Create a new BPMN workflow, section 9 & 10.
Display workflow variables
To display values entered during the workflow in subsequent (task) forms, you can just create a field with an identical ID in the Online Workflow Modeler (e.g. taxRate).
Make a variable read-only
As default, the values are editable. That means a user, who is assigned to this task, is able to see the entered value and overwrite it. To change it to “read-only”, you have to follow these steps:
Go to your BPMN model (for example, in the online editor)
Open the XML view of your model
Add this section below the field you would like to define as “read-only” and save it:
Example:
In this example, the field named f1
is set to read only.
Expression helper methods
There are pi
helper methods which can be used in any Camunda expression. These methods simplify the integration with PIPEFORCE. The can be called this way:
Method | Description | Example |
---|---|---|
| Loads the property by given path from the property store an returns it as JSON. |
|
| Returns the path of the workflow model as configured by workflow.start parameter |
|
| Loads the workflow model JSON from the property store as configured by |
|
| Returns the name of the assignee of the current task regardless in which task context it is used. |
|
| Returns the instance id (last part) of the workflow model path as given by For example if model path is |
|
| Returns the id (type) of the workflow model as given by For example if model path is |
|
| The name of the app, this workflow belongs to. |
|
| The path of the app, this workflow belongs to. |
|
| Loads the JSON from the data folder of the app with given name and id. |
|