SINCE VERSION 1.0

What is a BPMN Workflow?

BPMN (Business Process Model and Notation) is an internationally recognized ISO standard for formally representing business processes in a graphical format. It fosters clear communication, ensures alignment between business and technical teams, and enables smooth collaboration across departments and organizations.

BPMN models a dynamic business process, often involving one or more human interactions. In PIPEFORCE, BPMN workflows can be designed and initiated online via a graphical web interface, with the added option to directly trigger the execution of automation pipelines:

Business Process Model and Notation (BPMN) Basics​

If you’re not familiar with the BPMN concept so far, we highly recommend you to learn the basics of this standard before you dive deeper into this chapter. Here you can find a first introduction on Wikipedia: https://en.wikipedia.org/wiki/Business_Process_Model_and_Notation.

In this chapter, we will highlight and cover some of the most important concepts of BPMN.

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 business process.

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 of different types possible, just to name the most widely used setup.

Such BPMN workflows are typically designed using a BPMN modeller (designer) 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 Designer from PIPEFORCE, which supports additional features like:

• Link a user task to a custom task form.

• Link service tasks with automation pipelines in order to start an automation in case this task is executed.

• Discuss a BPMN diagram with your team.

• Deploy and start the diagram right from within the designer.

• Monitor running workflow instances.

In order to draw a BPMN diagram, the most important elements are these:

Lets shortly explain the most important basic elements below.

Start Event

This is typically 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.

Select the input form

In the PIPEFORCE Online BPMN Designer you have the possibility to link a user task to a form by first selecting the task and then clicking the FORM tab on the right. Here you have then two options of form types:

Form Type: Simple

In this form type mode, form fields can be directly defined in the tab and will be displayed vertically one after another. No additional configuration is required then. This is the simplest approach but is limited. So for example you can not change the orientation of the fields, no advanced fields are supported and fields are limited to max. 4000 chars.

Form Type: Custom

If you need more control about the layout of a form or would like to use advanced form fields, then you can select the Custom form type. In the dropdown you can then select the form configuration of the form to be used for this task or create a new one.

You have full flexibility to define the form by leveraging the power of the integration form framework. See here for documentation about the form framework: Forms.

Assign a user task to a user

Before a user task can be processed by a user, it needs to be assigned to this particular user. Once the task was assigned to this user, the input form switches from read-only to read-write mode and the user can start editing it.

There are three main concepts in this field which should be understood:

• Assigning a task means to put a particular user in the responsibilty to complete a certain task. As soon as a task was assigned to a user it will be shown up in his My Tasks filter and the user can start to edit the form. The assigned user of this task is called the assignee.

• Claiming a task means that a user assigns a task to himself (he picks a task to work on).

• Candidate users is a list of predefined users which are “allowed” to assign or claim the task.

• Candidate groups is similar to Candidate users with groups containing the candidate users.

By default a task can be claimed by any user who can see the task in the task list. Whether a user can see the task in the task list is defined by task filters which are typically pre-defined:

The default task filters are these:

• All Tasks
  Shows all open tasks.

• Assigned to Me
  Shows only those tasks assigned to the currently logged-in user.

• Assigned to my Group
  Shows only those tasks where Candidate group is a group the currently logged-in user is member of.

• I’m involved
  Shows only those tasks the currently logged-in user has participated as a commenter or is related in some other way.

• Started by Me
  Shows only those tasks initially started by the currently logged-in user.

• TODO
  Shows only those tasks which must be finished but not yet assigned to any user.

The assignment of a task is typically done a

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 (marked by a cog wheel). 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 an automation 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 automation pipeline by clicking the service task and then in the PIPELINE tab select an existing automation pipeline you would like to execute when this service task starts. Or you create a new pipeline and link it there.

Decision Gateway

A gateway in BPMN is a decision point that controls the flow of a process based on conditions or rules. It evaluates input data or process variables to determine which path to follow from multiple available paths.

Such a gateway ensures process flow logic is clear and dynamically adaptable to varying conditions.

There are different types of gateways in BPMN. In this section we will cover only the most widely used one: The exclusive gateway. It allows exactly one of the multiple outgoing paths to match. The flow will then follow this matching path. Here is an example how to use it with two outgoing paths (there could be more):

Gateway Conditions

In order to define the condition of a gateway to decide on which path to select, an expression language is set on a path which can operate on the existing workflow variables.

Lets assume we have a workflow variable called vacationApproved and we would like to use this variable to decide whether to send an approval email or a declined email, the condition expression for the No path of the example diagram above could look like this:

${vacationApproved == false}

And for the Yes path it could look like this:

${vacationApproved == true}

In order to configure this in the online BPMN designer of PIPEFORCE, click the path and set the condition inside the Condition field as this example shows:

Repeat the same step for the Yes path but with condition ${vacationApproved == true}.

Expression Language (JUEL)

The gateway condition is defined by a specific expression language named JUEL. Such an expression is always embedded between ${ and }.

Below, you will find the most important operators of this expression:

• Arithmetic: +, - (binary), *, / and div, % and mod, - (unary)

• Logical: and, &&, or, ||, not, ! (negation)

• 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 is null or empty.

• Conditional: A ? B : C. Evaluate B or C, depending on the result of the evaluation of A.

All of these operators can be applied on any workflow variable.

For more details see https://docs.oracle.com/javaee/5/tutorial/doc/bnahq.html

Example conditions

Here are some more examples of condition expressions.

Lets assume you would like to check that a workflow variable decision is contains exactly a given value:

${decision == 'approved'}

Lets assume you would like to check that a workflow variable budget is in a certain range:

${budget > 100 and budget < 1000}

End Event

The end event (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.

BPMN Management in PIPEFORCE

PIPEFORCE has a deep intgration with BPMN and simplifies its usage a lot. Here are the most important features, PIPEFORCE provides in order to manage BPMN workflows:

Design, deploy and start a BPMN

The design and execution of a workflow in PIPEFORCE is usually a 4-steps approach:

1. Design and Save the workflow in the BPMN modeler, and save the result in your app global/app/your.app/workflow/name.

2. Deploy the BPMN into the workflow engine by pushing the DEPLOY button in the online designer, or upload the BPMN file using the pi CLI tool by calling the command: pi publish.

3. Start the BPMN workflow by using one of these approaches:

   1. Press the START button in the online designer.

   2. Execute the command workflow.start in a pipeline, and set the key of your process as the parameter key (see BPMN sources). You can use, for example, the pi tool to start a workflow:
      pi command workflow.start ”key=<ID>”

4. List and complete a user task - Once a workflow has been started and waits for an human interaction (user task) for a user it is listed in a task list. The user can then pick the task from the list, fill out the task form and complete it.

Online Task View and Task Form

Any user tasks waiting for completion by users are listed in the task view in the online portal. If a user clicks such a task, the task form will be opened. The user can then assign the task, fill-out the form and complete the task. Here is an example how such a task view with a task list on the left and a task form looks like:

Task Filter

By default a task can be claimed by any user who can see the task in the task list. Whether a user can see the task in the task list is defined by task filters in the task view:

The default task filters are these:

• All Tasks
  Shows all open tasks.

• Assigned to Me
  Shows only those tasks assigned to the currently logged-in user.

• Assigned to my Group
  Shows only those tasks where Candidate group is a group the currently logged-in user is member of.

• I’m involved
  Shows only those tasks the currently logged-in user has participated as a commenter or is related in some other way.

• Started by Me
  Shows only those tasks initially started by the currently logged-in user.

• TODO
  Shows only those tasks which must be finished but not yet assigned to any user.

These default filters can be managed or new ones can be created using the workflow.filter.* commands such as:

• workflow.filter.put
  Creates a new filter.

• workflow.filter.list
  Lists all filters the currently logged-in user is allowed to see.

• workflow.filter.delete
  Deletes an existing filter.

For more details see the API docs for the workflow commands: https://pipeforce.github.io/api.html#/Command%20API%20-%20workflow

Start a workflow via event pipeline​

A pipeline, executed when an app is started, is called a trigger pipeline. Each pipeline is written in YAML format.

1. This pipeline listens to the new form entry.

2. Sets the variables

3. Maps the form data to workflow model (workflow data).

4. Perform different operations on file / directories if needed.

5. 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:

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

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

   pipeline:
     - event.listen:
         key: "property.created"
         filter: "#{body.payload.target.key.contains('global/app/travelexpense/object.travelexpense/v1/instance')}"
     - set.var:
         key: "formData"
         value: "#{@convert.toMap(body.payload.target.value)}"
   

   Note: To get more details regarding this feature, please see: Convert

3. Initialize the variables: Set the values of variables and update / save them e.g.

   pipeline:
     - event.listen:
         key: "property.created"
         filter: "#{body.payload.target.key.contains('global/app/travelexpense/object.travelexpense/v1/instance')}"
     - set:
         value: "#{@user.firstName()?: ''}"
         output: "#{vars.creatorFirstName}"
     - set:
         value: "#{@user.lastName()?: ''}"
         output: "#{vars.creatorLastName}"     
   

4. 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:

   1. Create Directory / Folder

      vars:
        basePath: "global/app/appname/data"
      
      pipeline:
        - iam.run.as:
            username: "systemuser"
        - drive.mkdir:
            path: "#{vars.basePath}"
            recurse: "true"     
      

      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.

   2. Get Attachment and Get Content

      Get file from entry-form and save into a variable

      - set.var:
          key: "invoiceFileName"
          value: "#{vars.formData.formAttachment.filename}"
      

      Get content of file

      - property.attachment.content:
          key: "#{body.payload.target.key}"
          value: "#{vars.formData.formAttachment.content}"
      

      Note: To get more details regarding this feature, please see: property.attachment.chunk.get

   3. Save the file into drive

      - drive.save:
          path: "global/app/appname/data/#{vars.FileName}"
      

5. Create roles or groups : You can also create your own role or group of roles. e.g.

   pipeline:
     - iam.run.as:
         username: "systemuser"
     - iam.role.create:
         name: "CAN_APP_APPNAME"
   

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

6. Give permissions for accessing files to a role or a group.

   pipeline:
     - iam.run.as:
         username: "systemuser"
     - drive.share:
         to: "invoice-controller"
         type: "group"
         path: "global/app/accountspayable"
         permission: 1
   

7. Evaluate any expressions.

     - eval:
         expr: "#{body.name = 'assignedvalue'}"
   

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:

- workflow.model:
    mappings: "
    uuid: vars.uuid,
    createrFirstName: vars.createrFirstName,
    createrLastName: vars.createrLastName,
    createrEmail: vars.createrEmail,
    createrUsername: vars.createrUsername,
    createrDate: vars.createrDate
    "
    output: "#{vars.workflowModel}"      

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.

- property.schema.put:
    key: "global/app/appname/object/workflowmodel/v1/instance/#{vars.uuid}"
    value: "#{vars.workflowModel}"
    type: "application/json"      

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.

- workflow.start:
    key: "appname_V1"
    businessKey: "#{vars.uuid}"
    workflowModelInstanceKey: "global/app/appname/object/workflowmodel/v1/instance/#{vars.uuid}"
    variables: "#{{
    'fname': (vars.formDatap['firstname']),
    'email': @user.email(),
    'account': (vars.formData['account']),
    'comment': (vars.formData['comment'])
    }}"
- body.delete:

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

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:

1. Go to your BPMN model (for example, in the online editor)

2. Open the XML view of your model

3. Add this section below the field you would like to define as “read-only” and save it:

<camunda:validation>
  <camunda:constraint name="readonly" />
</camunda:validation>

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:

${pi.on(execution)...}