This section describes how to create your BPMN workflows and configure your workflows in Business service applications.

Authoring Workflow with the BPMN Editor

Since version 9.3.0, BAMOE includes a new fully featured BPMN Editor, bringing faster startup times and backward compatibility with BPMN Editor (classic). Both BPMN Editors are available on BAMOE Canvas, BAMOE Developer Tools for VS Code, and as a standalone JavaScript library.

Note
 The BPMN Editor is fully compatible with BPMN models created in BAMOE 8.0.x, including Work Item Definition (WID) files.

The following lists the main elements of the BPMN Editor:

bpmn editor main page
Figure 1. Editor page for a Workflow with highlighted elements of the BPMN Editor

  1. Process Variables → to edit process variables in a dedicated panel.

  2. Correlations → to manage the correlations used to bind Process instances to messages.

  3. Properties Management → to manage custom BPMN properties in a single panel

  4. Node palette → to select and drag node types into your workflow including the Data Object button. Note that variations on the base elements can be selected after dragging a node type onto the Canvas.

  5. Group and Text annotations buttons enable you to group and annotate elements of your BPMN.

  6. Custom Tasks (Keyboard Shortcuts) → to display custom tasks that have been integrated into the editor (e.g., AI and flexible process tasks as well as your custom work item handler tasks). The Keyboard button toggles a dialog containing the keyboard shortcuts.

  7. Overlays → to set graphical preferences and visual overlay elements that are not part of the BPMN file.

  8. Properties → to manage the properties of the currently selected workflow element.

  9. The Zoom Fit view and toggle interactivity buttons enable you to size the BPMN diagram and lock the diagram to inhibit changes.

Developing Workflows through BPMN files is a complex subject and has many intricacies that are beyond the scope of this document. For more information, see BPMN-specific material, Business Process Model And Notation (BPMN) specification.

Invoking a Decision from a Workflow

A common use case for a Workflow is to invoke Decisions as part of its logic. On your Workflow, create a new "Task" node and once on in the editor, change its type to Business Rule task.

decision task
Figure 2. Node palette open for Task nodes inside the BPMN Editor

In the “Properties” panel under the section Implementation you can choose between DRL or DMN. Select the file you that contains the required Decision DMN and the model name space and name are automatically completed, as shown in this example:

decision in workflow props
Figure 3. Properties panel for a Business Rule Task inside a Workflow

When your Workflow executes, this Decision will be invoked with the input parameters you specified, passed to the Business Rule task. The result of the Decision will be the output of the Business Rule task.

Process Properties

  1. Click anywhere in the diagram area and then click on the properties panel button to access the properties panel.

bpmn process props panel
Figure 4. BPMN Editor properties

  1. Set the following properties:

    • Name: Provide a label for your process.

    • Documentation Provide a detailed description of the process.

    • ID & Namespace Specify an identifier that will be used for endpoints.

    • Ad-hoc: Specify if your process is ad-hoc (see Case Management)

    • SLA Due Date Provide a date within which the process must be completed, and which takes into account a business calendar of work time (see Business calendars).

Property and variable management

You can manage all custom properties for your BPMN workflow using the Global Properties Management dialog.

bpmn props mngmnt
Figure 5. Properties management dialog
Process Variables are used to pass information (data) from node to node, in order to be able to execute the Workflow in the Process Instance at runtime. You can create and manage Process Variables for your BPMN workflow using the Process Variables dialog where you can define the input/output relationship between nodes.
bpmn process vars
Figure 6. Process variables dialog

When you create a new variable:

Name

is the ID and name of the variable which can be referenced via scripts or the input/output of activities.

Data type

refers to a Java type.

, and via I/O Assignments in BPMN Editor (classic). During migration, the state is preserved and Process and Task variables, Jobs schedules and SLAs remain unchanged.

Define Workflow elements

The following top level elements can be dragged out of the Node palette to define your workflow:

  • Start Event: Green circle indicating the starting point of the workflow.

  • Intermediate Catch & Throw Events: Yellow and Green circles to create catch and throw events that occur between the start and end points.

  • End Events: Red circle marking the end of the workflow.

  • Tasks: Empty rectangle representing any of the tasks or activities in the workflow (e.g., user task, gen AI task, milestone, …​).

  • Call activity Rectangle with embedded square representing a call to an activity that is external to the process definition, and could be a reusable element.

  • Subprocess: Rectangle with a square to create subprocesses that remain part of the current process definition.

  • Gateways: Diamond shape for decision points.

  • Lanes: Checklist icon to organize tasks by roles or departments.

  • Data Objects: Document icon to specify the flow of data in your workflow.

Each top level element you can create from the toolbar has variants that you can select using the menu accessed via the button on the bottom left corner of each element.

task element menu
Figure 7. Element menu

For the conformance level of BPMN elements, see Reference → Business Process Model and Notation (BPMN)

Using Script Tasks

Script tasks are automated activities in BPMN workflows that execute scripts written in different script languages. FEEL and Java are supported for script tasks. They allow you to perform custom logic, manipulate process variables, perform calculations, or execute any custom code within your workflow without requiring external services or user interaction.

Script tasks can directly access process variables defined in your workflow. You can use script tasks for operations such as:

  • Logging information during process execution

  • Transforming or calculating values

  • Setting process variables based on business logic

When you create a script task in the BPMN editor, you specify the script code that will be executed when the workflow reaches that task. In the properties panel, you can configure the task properties including Name, Documentation, ID, Script, Options (Async, Ad-hoc auto-start), and Metadata.

Review the following list of suggestions before using a script task:

  • Avoid low-level implementation details in the process. Although you can use a script task to manipulate variables, consider using a service task when modeling more complex operations.

  • Ensure that the script is executed immediately. If the script is not intended to be executed immediately, consider using an asynchronous service task.

  • Avoid contacting external services through a script task. Use a service task to model communication with an external service.

  • Ensure scripts do not generate exceptions. Runtime exceptions should be caught and managed inside the script or transformed into signals or errors that can then be handled inside the process.

Process Context (kcontext)

The kcontext variable provides access to the process context within script tasks. It is a global context for the process that allows you to access and modify process variables. The kcontext variable is an instance of the KogitoProcessContext interface (org.kie.kogito.internal.process.runtime.KogitoProcessContext).

You can access process variables in script tasks in two ways:

  • Directly by name: Process variables can be accessed directly by their variable name in the script. For example, if you have a process variable named traveler, you can access it directly as traveler.getHotelId().

  • Using kcontext methods: You can also use the kcontext variable to access and modify process variables programmatically.

You can use the following methods with kcontext:

  • kcontext.getVariable("variableName") - Reads the value of a process variable

  • kcontext.setVariable("variableName", value) - Sets or updates a process variable

  • kcontext.getProcessInstance() - Returns the process instance currently being executed

  • kcontext.getNodeInstance() - Returns the node instance currently being executed

  • kcontext.getHeaders() - Returns the headers associated with the process instance

  • kcontext.getKogitoProcessRuntime() - Returns the process runtime

  • kcontext.getContextData() - Returns context data as a map

// Set a variable
kcontext.setVariable("name", "John");

// Update a variable
kcontext.setVariable("fullName", firstName + " " + lastName);

Using Flexible processes for Case Management

BAMOE uses BPMN extensions to provide Case Management functionality through flexible processes. A flexible process is any process definition that uses ad-hoc components or other features that enable the process to be executed more flexibly than traditional processes.

An ad-hoc task can be initiated dynamically during the execution of a business process, rather than being predefined in the process model. These tasks are particularly useful in scenarios where the workflow needs to accommodate unforeseen or exceptional activities that arise during runtime.

A typical example of a case or flexible process is related to healthcare. A patient has a file that is accessible to the doctor and to any health professionals (or knowledge workers) who are assigned to the patient. These assigned workers take action and make different decisions and assessments until the patient is diagnosed and treated, completing the case or flexible process.

In BAMOE a flexible process supports case-related usecases via the following basic components:

  • Optional start event which may or may not be explicit

  • Optional node connections, which may or may not connect all nodes

  • Enabled Ad-Hoc process property set in the process definitions

  • One or more subprocesses which may or may not be ad-hoc subprocesses

  • Ad-hoc auto-start fragments, such as ad-hoc subprocesses or ad-hoc tasks

  • Milestones that flag or trigger events

  • End event to terminate the process

The following sections contain more information on each of the components of a flexible process:

Ad-hoc processes

You can create an ad-hoc process by enabling the Ad-Hoc property in the process definition properties panel. This property enables the process to use ad-hoc auto-start fragments, such as ad-hoc subprocesses and ad-hoc tasks. Once your process definition is set to ad-hoc, it no longer requires strict start and end events.

Ad-hoc process properties

Ad-hoc subprocesses

An ad-hoc subprocess is similar to a Stage in Case Management. It contains embedded inner activities and is itself part of another process. It is a standard BPMN component and therefore supported by BAMOE.

Ad-hoc subprocess

Ad-hoc auto-start fragments

An ad-hoc auto-start fragment is any ad-hoc process, ad-hoc subprocess, or ad-hoc task with the AdHoc Autostart property enabled. This property enables the fragment to automatically start when the process is created instead of being started by the completion of the previous node or by a signal event.However, when this flag is not set, the only way to trigger the node execution is with a signal. Processes receive signals externally through the REST API, internally by using events or programmatically.

Ad-hoc auto-start properties

Milestones

A milestone is a standard CMMN component that is represented as a BPMN custom task. A milestone represents a single point of achievement within a process instance. You can use milestones to flag certain events to trigger other tasks or track the progress of the process.

Ad-hoc milestone

REST API requests as Signals

A REST API request can serve as a signal event to trigger Milestones or to create and start ad-hoc fragments such as ad-hoc processes, ad-hoc subprocesses, or tasks. For non-flexible processes, an empty POST request for a process triggers the start node, whereas in a flexible process, the request creates the process instance. Similarly for ad-hoc tasks, an empty POST request instantiates the task node. All ad-hoc auto-start fragments with the Ad-Hoc Autostart property, are started automatically when the process is created.

Implementing flexible, one-off business cases

An example application flexible-process-quarkus can be found in Example Business Service projects. This example shows the use of flexible processes to implement a Case Management scneario using Ad-hoc subprocesses, Milestones, and a DMN Business Rule Task.

Correlating message events to a Message Event

Correlations are used when multiple process instances are running concurrently and only one specific instance needs to be notified. Using a correlation you can bind process instances to messages that contain specific property values.

A dedicated dialog can be displayed through the Correlations toggle button. See Editor presentation. In this panel you can configure a Property that binds to one or more message types, as well as the Key values that will trigger the execution of a specific process instance.

correlations bmpn dialog
Figure 8. Correlation dialog

Correlation ensures messages are routed only to process instances that match specific criteria based on message content.

For more information on how correlation works at runtime see Working with Events.