SINCE VERSION 1.0

1 What is a BPMN Workflow?
2 Business Process Model and Notation (BPMN) - Basics
- 2.1 Start Event
- 2.2 User Task
  - 2.2.1 Select the input form
  - 2.2.2 Assignment - Assign a user task
- 2.3 Service Task
  - 2.3.1 Link to an automation pipeline
  - 2.3.2 Passing workflow variables to a pipeline
  - 2.3.3 Returning workflow variables from a pipeline
  - 2.3.4 Reserved workflow variables piwf_
- 2.4 Decision Gateway
  - 2.4.1 Conditions
- 2.5 End Event
- 2.6 Expression Language (JUEL)
  - 2.6.1 Expression Helper pi
3 BPMN Management in PIPEFORCE
- 3.1 Pluggable Workflow Engine
- 3.2 Save a BPMN in PIPEFORCE
- 3.3 Deploy a BPMN in PIPEFORCE
- 3.4 Start a BPMN in PIPEFORCE
- 3.5 Online Task View
  - 3.5.1 Task List
  - 3.5.2 Task Filter
  - 3.5.3 Task Form
  - 3.5.4 Task Search
  - 3.5.5 Task Comments
- 3.6 Workflow Variables
  - 3.6.1 Default Worflow Variables _piwf
  - 3.6.2 Passing a file as workflow variable

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:

Workflow Designer in PIPEFORCE

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.

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 it 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 required to get stated with it in PIPEFORCE.

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 (marked by a user icon) 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.

A user task is typically linked to a form so a user can fill-out and complete a task.

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 added in the tab and will be displayed vertically one after another in the final task form. No additional configuration is required then. This is the simplest and fastest approach to define the form fields of a user task, but has its limitations. 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. This allows you to use the PIPEFORCE Form Framework to fully customize the fields and layout of a form.

Make sure the app is slected which contains your form configration.

In the dropdown field Workflow Form Name 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.

Assignment - Assign a user task

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

There are different ways to assign a task to a user:

Manual Assignment

The assignee of a task can be changed at runtime in the task view UI by clicking the Assignee or Claim button. This is called a manual assignment.

Fixed Assignment

Beside manually assigning a user task in the task view, a user task can also be assigned to a fixed username value at the time the BPMN is designed. This can be done by setting the username of this user in the field Assignee under section Assignment:

Dynamic Assignment

Another option is to calculate and set the assignee at runtime using the JUEL expression language. Here is an example which sets the assignee as given by the workflow variable salesUser:

${salesUser}

Whatever value the workflow variable salesUser at the time of the execution of the user task has, this user is automatically assigned to this task.

Assignment Candidates

Sometimes it is necessary to filter the potential users allowed to be assigned to a user task. This can be configured using the fields Candidate Users and Candidate Groups:

Candidate Users is a list of predefined usernames which are “allowed” to be assigned to the task
Candidate Groups is similar to Candidate Users but provides a list of group names of groups containing the usernames allowed to be assigned to the user task.

In order to set a fixed list of Canidate Users or Candidate Groups can specify them by separting the items by a comma:

username1,username2,username3

group1,group2,group3

Optionally, it is also possible to use the BPMN Workflows | Expression Language (JUEL) to define the candidate assignment at runtime. Here is an example to do so for the Candidate Users by reading the workflow variable salesManagers:

${salesManagers}

The similar can be done to set the Candidate Groups dynamically.

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 icon). 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.

Link to an automation pipeline

By default, such a service task must be 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.

A service task is typically linked to an automation pipeline to execute automated actions.

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 by clicking the plus icon.

Every time the workflow process arrives at this service task, the service task will delegate to the configured pipeline, passes the current workflow variables to this pipeline and executes it. The pipeline can then do its automation job. By default this is done in sync mode. This means the service task waits until the pipeline has finished its commands. Once the pipeline is finished, the service task is marked as completed and the workflow process goes on to the next step.

See this example where the Reject invoice service task is linked to a pipeline:

Passing workflow variables to a pipeline

When the service task delegates to a pipeline, every workflow variable of the current process state will be passed to the pipeline and becomes availabe as pipeline variable. Any existing pipeline variable with same name will be overwritten by the passed one.

Lets assume there is a workflow variable approvedDate. When delegating to a pipeline, this variable can be accessed from inside a pipeline like this:

vars:
  approvedDate
pipeline:
  - mail.send:
      to: mail@domain.tld
      subject: Invoice approved
      message: |
        Hello,
        your invoice was approved at ${vars.approvedDate}

As you can see, the workflow variable is declared in the vars section at the top of the pipeline. This is optional but strongly recommended since it makes it clear which variables are in use.

Then the variable is used in the message text using the pipeline expression ${vars.approvedDate}. For more details on this, see Pipeline Expression Language (PEL).

Returning workflow variables from a pipeline

In case the pipeline contains a JSON in the body after final execution, the root elements of this JSON will be set as workflow variables. Whereas the name of the root element will become the workflow variable name and the value of it will become the value of the workflow variable. In case a workflow variable with this name already exists, it will be overwritten by the value from this JSON.

Here is an example which returns a new workflow variable emailSent from a pipeline to the user task:

pipeline:
  ...
  - body.set: {
      "emailSent": true
    }

This is similar to this structure, both are valid:

pipeline:
  ...
  - body.set:
      "emailSent": true

Reserved workflow variables piwf_

Any reserved workflow variable (those starting with piwf_) wont be passed to a pipeline nor will be returned as workflow variable. They will be filtered out.

Inside a called pipeline, they are provided in the request header. If required they can be accessed like this example shows, but they cannot be changed:

pipeline:
  - mail.send:
      to: user@domain.tld
      subject: User Task started
      message: Task was started by user ${request.headers['piwf_startedby']}

See the workflow variables section below for a full list of these reserved piwf_ variables.

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):

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}

Note: You can also use the short forms ${vacationApproved} and ${!vacationApproved} in the path conditions.

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

The gateway condition is defined by the JUEL (Java Unified Expression Language).

End Event

The end event (also known as the end state) defines when the process is complete. Typically, a BPMN workflow must have exactly one end event, although there are a few rare cases where this may differ.

Expression Language (JUEL)

In some configuration fields of a BPMN diagram like the Condition field of a Gateway or the Assignment field of a user task for example, the Java Unified Expression Language (JUEL) can be used to dynamically set values at runtime.

Such an expression is always embedded between ${ and }.

The workflow variables can be directly read and writting using this expression language.

Examples:

Lets assume you would like to check that a workflow variable decision 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}

In this example, the the field vacationApproved is set to true:

${vacationApproved = true}

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.

Expression Helper `pi`

Inside any JUEL expression, the optional variable pi helper can be used. It provides utility methods to simplify the integration with PIPEFORCE and can be called this way:

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

Whereas method(...) can be one of these:

Method	Description	Example

Method	Description	Example
`property(path)`	Loads the property value by given path from the property store and returns it as JSON.	`${pi.on(execution).property('data/person/123').name}`
`modelPath()`	Returns the path of the workflow model as configured by `workflow.start` parameter `workflowModelPath`.	`${pi.on(execution).modelPath()}`
`model()`	Loads the workflow model JSON from the property store as configured by `workflow.start` parameter `workflowModelPath`.	`${pi.on(execution).model().name}`
`assignee()`	Returns the name of the assignee of the current task regardless in which task context it is used.	`${pi.on(execution).assignee()}`
`modelInstanceId()`	Returns the instance id (last part) of the workflow model path as given by `workflow.start` parameter `workflowModelPath`. For example if model path is `data/person/123` then model instance id is `123`.	`${pi.on(execution).modelInstanceId()}`
`modelId()`	Returns the id (type) of the workflow model as given by `workflow.start` parameter `workflowModelPath`. For example if model path is `data/person/123` then model id is `person`.	`${pi.on(execution).modelId()}`
`appName()`	The name of the app, this workflow belongs to.	`${pi.on(execution).appName()}`
`appPath()`	The path of the app, this workflow belongs to.	`${pi.on(execution).appPath()}`
`data(name, id)` `data(name, id, failIfNotExists)`	Loads the JSON from the data folder of the app with given name and id.	`${pi.on(execution).data('person', '123').name}`

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 and processes.

Pluggable Workflow Engine

In order to execute a BPMN it needs to be deployed into a BPMN workflow engine which manages the states of the execution process. By default PIPEFORCE uses the open source workflow engine Camunda under the hood. But this is designed in a way so workflow engines can be switched if required and any other BPMN-comtabile engine can be used instead.

Save a BPMN in PIPEFORCE

Any BPMN definition must be stored in the property store of PIPEFORCE in order to work properly.

You can do so in two ways in PIPEFORCE:

by clicking SAVE in the Online BPMN Designer or
by using the command property.put in case you would like to automate this step.

In case of an import, make sure the BPMN definition is stored in this location, so PIPEFORCE can recognize and handle it correctly:

global/app/{yourApp}/workflow/{wfName}

Replace {yourApp} by the name of your app an {wfName} by the name of your workflow definition.

If a BPMN definition is stored at any other location, deployment and start will not work properly since PIPEFORCE uses this location for additional metadata.

Deploy a BPMN in PIPEFORCE

After you have designed and stored your BPMN, it must be deployed into the workflow engine in order to active it. You can do so in two ways in PIPEFORCE:

Click the DEPLOY button in the Online BPMN Designer.
Use the command workflow.definition.deploy in case you would like to automate this step.

Start a BPMN in PIPEFORCE

After you have deployed a BPMN definition into the workflow engine, you can start the workflow.

A started workflow is called a process.

You can start a workflow in two ways in PIPEFORCE:

Click the START button in the Online BPMN Designer.
Use the command workflow.start in case you would like to automate this step.

Here is an example to start a workflow from inside an automation pipeline:

pipeline:
  - workflow.start:
      key: definition_key

Make sure to replace definition_key by the key of the BPMN definition.

You can also pass initial workflow variables to the workflow start:

pipeline:
  - workflow.start:
      key: definition_key
      variables:
        myVar1: myValue1
        myVar2: myValue2
        ...

These variables can then be used inside the BPMN process using the JUEL expression language for example.

In case the BPMN starts with a user task and you would like to assign this very first user task to a user so it immediately appears in his task list, you can set the claim parameter accordingly:

pipeline:
  - workflow.start:
      key: definition_key
      claim: someUsername

Online Task View

Once a workflow was started, 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:

The components on such a task view are highly customizable to fit the business requirements.

Task List

On the left side of the task view, the task list is shown. This list contains all tasks, the currently logged-in user is allowed to see depending on the selected task filter.

Each entry in the task list is called a task card. The card contains information such as the title of the task, the unique task id, when the task was created and who is currently assigned to the task. If the user clicks this card, the task form is shown.

Labels: Show workflow variables on Task Cards

Optionally, the value of workflow variables can be defined to be shown on a task card. In order to configure this, you have to add a tag showTaskTags to the property which stores the BPMN in the property store. This tag tag must contain a JSON which defines the name of the label to be shown and the name of the workflow variable to be shown. Example:

pipeline:

  - property.tag.put:
      path: global/app/de.myapp/workflow/myworkflow
      name: showTaskTags
      value: |
        {"Approved": "vacationApproved"}

As you can see in this example, the tag with name showTaskTags was added to the workflow property. The value of this tag is a JSON which defines the name of the label to be Approved and the workflow variable to be be displayed vacationApproved. There can be multiple workflow variables defined this way in the JSON.

Since defining those filters are done via a property tag you can fully automate this setup in your app using a setup pipeline: Whenvever your app gets installed, this tag will be set so the task card is setup without any manual step. For more information how to do this, see: Automation App

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

Task Form

After the user has clicked a task card in the task list, the task form related to this task is opened. In case the task is not assigned to the current user, the form is in read-only mode. This means the user can view it and can add comments but cannot change values of the form or complete the task.

Depending on the user’s permissions action buttons are shown at the top of the form. The user can for example assign a task, claim or cancel, depending on his permissions.

After the task has been assigned to currently logged-in user, the form becomes editable. The user then can fill-out the form and complete the task.

The layout and the fields of the task form can be fully customized using the built-in form framework of PIPEFORCE. See above for User Tasks how to configure this and the forms framework documentation how to customize the forms: Forms.

Task Search

You can search for tasks in a task view in two ways:

The quick task search at top right corner. This is a text search which searches for tasks in the currently selected task filter and is available for all users who have access to the task list.

The advanced task search. This search allows to search on all tasks accross all workflows and is available only for admin users.

In case you would like to give a user the permission to see and use this advanced task search, make sure he is assigned to the role CAN_FTR_workflow_tasksearch in IAM.

Be aware that if a user has access to advanced search he is able to search and list any task of the system.

Task Comments

Any task form also shows a COMMENT section at the bottom. User comments can be added there and files attached. These comments are visibale for the whole process and will be shown-up on any user task of the process so users can communicate across multiple user tasks.

Workflow Variables

As already mentioned before, workflow variables are variables to be used inside a process in order to decide on gateways using JUEL or to pass along to pipelines and forms. Those variables can be passed initially to a workflow like this example shows:

pipeline:
  - workflow.start:
      key: definition_key
      variables:
        myVar1: myValue1
        myVar2: myValue2
        ...

Or they can be generated at runtime by a pipeline which was executed by a service task for example and returns a JSON where the root elements of this JSON will become the new workflow variables.

Default Worflow Variables _piwf

With every start of a workflow from inside PIPEFORCE, there is a certain set of default variables always passed and available at any step of the process. These default variables contain meta information about a process. By default they will be filtered out when calling a pipeline from a service task. All of these variables do have the prefix piwf_:

Variable	Description

Variable	Description
`piwf_appName`	The name of the app, this workflow belongs to.
`piwf_appPath`	The path of the app in the property store, this workflow process belongs to.
`piwf_index`	The index of the process. This is a short form of the process instance id for more simple referencing.
`piwf_namespace`	The instance namespace this workflow process was started from.
`piwf_processInstanceId`	The unqiue id of this workflow process.
`piwf_workflowModelInstanceId`	The id of the workflow model in the property store.
`piwf_workflowModelPath`	The path of the workflow model in the property store.
`piwf_startedByPipeline`	The path to the pipeline which initially started this workflow process.
`piwf_startedByUsername`	The username of the user who initially started this workflow process.

Passing a file as workflow variable

In order to pass a file as workflow variable, this is always handled in outbound-mode in PIPEFORCE. This means not the file itself is set as variable value but a reference to it. This is called a content reference which is a JSON contain all required information to load and show a file. See here: Content References (Files).

Whenver a file (content object) is passed as a variable to workflow.start, it will be automatically converted to a content reference JSON. This content reference is then passed to the workflow engine and any subsequent tasks and pipelines.

PIPEFORCE Academy

BPMN Workflows

What is a BPMN Workflow?

Business Process Model and Notation (BPMN) - Basics

Start Event

User Task

Select the input form

Form Type: Simple

Form Type: Custom

Assignment - Assign a user task

Manual Assignment

Fixed Assignment

Dynamic Assignment

Assignment Candidates

Service Task

Link to an automation pipeline

Passing workflow variables to a pipeline

Returning workflow variables from a pipeline

Reserved workflow variables piwf_

Decision Gateway

Conditions

End Event

Expression Language (JUEL)

Expression Helper `pi`

BPMN Management in PIPEFORCE

Pluggable Workflow Engine

Save a BPMN in PIPEFORCE

Deploy a BPMN in PIPEFORCE

Start a BPMN in PIPEFORCE

Online Task View

Task List

Labels: Show workflow variables on Task Cards

Task Filter

Task Form

Task Search

Task Comments

Workflow Variables

Default Worflow Variables _piwf

Passing a file as workflow variable

Related content

BPMN Workflows

What is a BPMN Workflow?

Business Process Model and Notation (BPMN) - Basics​

Start Event

User Task ​

Select the input form

Form Type: Simple

Form Type: Custom

Assignment - Assign a user task

Manual Assignment

Fixed Assignment

Dynamic Assignment

Assignment Candidates

Service Task ​

Link to an automation pipeline

Passing workflow variables to a pipeline

Returning workflow variables from a pipeline

Reserved workflow variables piwf_

Decision Gateway

Conditions

End Event

Expression Language (JUEL)

Expression Helper pi

BPMN Management in PIPEFORCE

Pluggable Workflow Engine

Save a BPMN in PIPEFORCE

Deploy a BPMN in PIPEFORCE

Start a BPMN in PIPEFORCE

Online Task View

Task List

Labels: Show workflow variables on Task Cards

Task Filter

Task Form

Task Search

Task Comments

Workflow Variables

Default Worflow Variables _piwf

Passing a file as workflow variable

Related content

Business Process Model and Notation (BPMN) - Basics

User Task

Service Task

Expression Helper `pi`