Manage your workflows effortlessly with OrqueIO !

1. Introduction

Keep your workflows running smoothly while easily implementing improvements. Use a reliable and stable platform to manage your processes with confidence.

Welcome to the Orque IO Documentation! Orque IO is an open-source platform for Business Process Management. The Manual introduces key concepts in Orque IO, provides installation procedures as well as a comprehensive reference section.

Orque IO is an open-source fork of the Camunda 7 business process management platform.

It is a powerful tool for building and managing business processes, with a focus on ease of use and flexibility. Orque IO allows you to model, execute, and monitor business processes using BPMN (Business Process Model and Notation) standards.

1.1. Migrating from Camunda 7 to Orque IO

If you are migrating from Camunda 7 to Orque IO, you will find that the core concepts and functionalities remain similar, but with enhancements and improvements. The migration process is designed to be straightforward, allowing you to leverage your existing BPMN models and workflows with minimal changes.

1.1.1. Key Improvements Over Camunda 7

OrqueIO builds on the solid foundation of Camunda 7 while delivering important upgrades for a smoother, safer, and more efficient experience. Here are the key enhancements you’ll benefit from:

  • Full compatibility with existing assets : Your BPMN diagrams, process definitions, and integrations continue to work without major modifications.

  • Maintenance and security guaranteed : OrqueIO ensures that your processes remain secure and stable over time, reducing the risks associated with unsupported platforms.

  • Incremental enhancements : New features have been added to improve daily workflow management without forcing paradigm changes.

  • Performance and stability improvements : Optimized execution of processes ensures consistent performance for your workloads.

  • Expert support available : Assistance from BPM experts is provided to help with migration and ongoing operations.

1.2. Licenses

OrqueIO is fully open and free to use, providing all its features under open-source licenses. The entire platform is distributed under various open-source licenses, mainly Apache 2.0 and MIT. Each component clearly indicates its license in the header of the source file or in a LICENSE file located at the root of the repository. Users can freely use the platform while respecting the terms of these licenses.

  • Third-Party Libraries
    OrqueIO makes use of several third-party libraries to provide additional functionality. Each of these libraries is licensed under its own open-source terms.
    For detailed information, you can refer to:

    Third-Party Libraries Overview: An overview of the dependencies Camunda distributes. Additionally, this page points out particularly important third-party licenses to be aware of.
    HTML License Book OrqueIO: A list of all dependencies Camunda distributes with the Camunda 7 artifacts, including their licenses and notices
    Plain Text License Book OrqueIO: A plain text version of the license book.

  • Contact
    If you have a question specifically about the licensing or distribution of OrqueIO software and it has not been answered by this page, please contact the Open Source Compliance team at contact@orqueio.io.

1.3. Implemented Standards

OrqueIO supports the main standards in the Business Process Management (BPM) domain: BPMN 2.0, CMMN 1.1, and DMN 1.3. These standards are defined by the Object Management Group (OMG).

OrqueIO provides open-source implementations for executing processes, cases, and decisions compatible with them.

  • BPMN : Business Process Model and Notation (BPMN) is the industry standard for workflow and process automation. OrqueIO fully supports BPMN 2.0, allowing you to execute and monitor business processes efficiently.

  • CMMN : Case Management Model and Notation (CMMN) is the standard for case management. OrqueIO supports CMMN 1.1, enabling the execution of flexible case-based processes.

  • DMN : Decision Model and Notation (DMN) is the standard for business decision management. OrqueIO supports DMN 1.3, allowing you to implement and execute decision tables and rules seamlessly. Key resources for DMN in OrqueIO:

1.4. Architecture Overview

OrqueIO is a Java-based framework. Its core components are built in Java, offering powerful tools for designing, executing, and managing business processes on the JVM. To make the process engine accessible to non-Java developers, OrqueIO also provides a REST API, enabling applications in any language to connect to a remote process engine.

OrqueIO can run as a standalone process engine server or be embedded within custom Java applications. This embeddable design drives many architectural decisions, such as keeping the engine lightweight with minimal third-party libraries, supporting Spring-managed or JTA transactions and the threading model.

The illustration below shows the main components and typical user roles, giving you a clear picture of how the engine, web applications, and external systems interact.

architecture overview

1.4.1. Process Engine Architecture

process engine architecture
  • Process Engine Public API : Service-oriented API allowing Java applications to interact with the process engine. The different responsibilities of the process engine (i.e., Process Repository, Runtime Process Interaction, Task Management, …) are separated into individual services. The public API features a command-style access pattern : Threads entering the process engine are routed through a Command Interceptor which is used for setting up Thread Context such as Transactions.

  • BPMN 2.0 Core Engine : This is the core of the process engine. It features a lightweight execution engine for graph structures (PVM - Process Virtual Machine), a BPMN 2.0 parser which transforms BPMN 2.0 XML files into Java Objects and a set of BPMN Behavior implementations (providing the implementation for BPMN 2.0 constructs such as Gateways or Service Tasks).

  • Job Executor : The Job Executor is responsible for processing asynchronous background work such as Timers or asynchronous continuations in a process.

  • The Persistence Layer : The process engine features a persistence layer responsible for persisting process instance state to a relational database. We use the MyBatis mapping engine for object relational mapping.

1.4.2. OrqueIO Architecture

OrqueIO is a flexible workflow framework designed for multiple deployment scenarios. This section presents the most common ways to deploy and run the engine.

Embedded Process Engine
embedded process engine

In this setup, the process engine is packaged as a library within a custom application. This allows it to start and stop automatically with the application lifecycle. If required, multiple embedded process engines can also operate on a shared database.

Shared, Container-Managed Process Engine
shared process engine

In this scenario, the process engine runs inside a runtime container (e.g., Servlet Container, Application Server). The process engine is provided as a shared container service and can be accessed by all applications deployed within that container.
This concept is similar to a JMS Message Queue provided by the runtime, which can be used by multiple applications.
There is a one-to-one relationship between process deployments and applications: the engine tracks the process definitions deployed by an application and delegates execution to that application.

Standalone (Remote) Process Engine Server
standalone process engine

In this case, the process engine is offered as a network service. Applications running on the network can interact with the engine through a remote communication channel. The simplest way to access the engine remotely is via the built-in REST API. Other communication channels, such as SOAP Web Services or JMS, are also possible but must be implemented by the user.

1.4.3. Clustering Model

To provide scale-up or fail-over capabilities, the process engine can be distributed across multiple nodes in a cluster. Each engine instance connects to a shared database.

clustered process engine

Individual engine instances do not maintain session state across transactions. Whenever a transaction is executed, the full state is written to the shared database. This allows subsequent requests for the same process instance to be routed to different nodes in the cluster. This approach is simple to understand and imposes minimal restrictions for cluster deployment. From the engine’s perspective, there is no difference between a scale-up setup and a fail-over setup, since no session state is kept between transactions.

Session State in a Clustered Environment

OrqueIO does not provide built-in load-balancing or session replication. Load-balancing must be handled by an external system, and session replication must be managed by the host application server.

In a clustered environment, if users access web applications, additional configuration is needed to avoid repeated login prompts. Two common approaches are:

  • Sticky sessions: could be configured and enabled within your load balancing solution. This would ensure that all requests from a given user are directed to the same instance over a configurable period of time.

  • Session sharing: Enable session sharing in the application server so that multiple server instances share session state, allowing users to connect to different nodes without re-authentication.

Without one of these configurations, users connecting to multiple nodes—intentionally or via a load balancer—may be prompted to log in multiple times.

Consistent hashing
If a cookie based consistent hashing is used, make sure that the cookie name is not JSESSIONID which is used by OrqueIO.
The Job Executor in a Clustered Environment

The process engine job executor in OrqueIO is also clustered and runs on each node. This ensures that there is no single point of failure for the process engine. The job executor can operate in both homogeneous and heterogeneous clusters.

Time zones
The are some limitations on time zone usage in a cluster.

1.4.4. Multi-Tenancy Models

To serve multiple, independent parties with a single OrqueIO installation, the process engine supports multi-tenancy. The following multi-tenancy models are supported:

  • Table-level data separation using different database schemas or databases

  • Row-level data separation using a tenant marker

Users should choose the model that fits their data separation needs. OrqueIO’s APIs provide access to processes and related data specific to each tenant. More details can be found in the multi-tenancy section.

1.5. Supported Environments

OrqueIO is designed to run in any environment that supports Java, making it flexible for a wide range of deployment scenarios. The platform has been tested in various environments to ensure stability and performance.

1.5.1. Container/Application Server for Runtime Components

This section presents the different environments in which the OrqueIO process engine can run.

Application-Embedded Process Engine

The process engine can be embedded directly into your Java application. The following options are supported for embedding and running the engine:

  • All Java application servers

  • Camunda Spring Boot Starter: Embedded Tomcat

    • Supported versions

    • Deployment scenarios

  • Camunda Engine Quarkus Extension

    • Supported versions

    • Deployment scenarios

Container-Managed Process Engine and Camunda Webapps

The following application servers are supported for deploying the container-managed process engine and web applications:

  • Apache Tomcat 9.0 / 10.1

  • JBoss EAP 7.4 / 8.0

  • WildFly Application Server 33.0 / 35.0 / 37.0

1.5.2. Databases

This section lists the database products that are supported for storing process engine state.

Supported Database Products

These are the versions tested and recommended for use with OrqueIO.

Database Supported Versions / Notes

MySQL

8.0

Oracle

19c, 23ai

IBM DB2

11.5 (excluding IBM z/OS)

PostgreSQL

14 / 15 / 16 / 17

Amazon Aurora

PostgreSQL compatible (14 / 15 / 16)

Microsoft SQL Server

2017 / 2019 / 2022

Microsoft Azure SQL

SQL Server compatibility levels supported; includes Azure VM, Managed Instance, and Azure SQL Database

H2

2.3 (not recommended for Cluster Mode - see Deployment Note)

Database Clustering & Replication

Clustered or replicated databases are supported under certain conditions. The communication between Camunda and the database cluster must be configured consistently with the non-clustered or non-replicated setup. It is particularly important to ensure that the database cluster preserves the equivalent behavior of the READ-COMMITTED isolation level.

1.5.3. Web Browsers

OrqueIO web applications are compatible with the latest versions of:

  • Google Chrome

  • Mozilla Firefox

  • Microsoft Edge

1.5.4. Java Versions

OrqueIO is tested and supported on the following LTS versions of Java:

  • Java 11

  • Java 17

  • Java 21 (tested with Eclipse Temurin JDK)

1.6. Third-Party Libraries

This section provides an overview of the third-party libraries used in OrqueIO and their associated licenses. It also points to the license book for full legal reference.

OrqueIO relies on a set of open-source libraries to provide additional functionality and long-term maintainability. The libraries are included in the platform according to their respective licenses.

For detailed information on each dependency, please refer to the OrqueIO License Book.

1.6.1. License Book

The License Book contains a complete listing of all third-party libraries bundled with OrqueIO. It clearly indicates the license for each library, helping you comply with legal requirements and understand the usage terms.

All dependencies included in OrqueIO are distributed under standard open-source licenses (such as Apache 2.0 or MIT), unless explicitly stated otherwise in the License Book.

Java dependencies
Library Version License

logback-classic

1.5.18

EPL 1.0

logback-core

1.5.18

EPL 1.0

jackson-annotations

2.15.2 / 2.18.3

Apache 2.0

jackson-core

2.15.2 / 2.18.3

Apache 2.0

jackson-databind

2.15.2 / 2.18.3

Apache 2.0

jackson-dataformat-csv

2.15.2 / 2.18.3

Apache 2.0

jackson-datatype-jdk8

2.18.3

Apache 2.0

jackson-datatype-jsr310

2.15.2 / 2.18.3

Apache 2.0

java-uuid-generator

4.3.0 / 5.1.0

Apache 2.0

classmate

1.7.0

Apache 2.0

gson

2.8.9

Apache 2.0

h2

2.3.232

EPL 1.0

asyncutil

0.1.0

Apache 2.0

icu4j

71.1

Unicode

json-path

2.9.0

Apache 2.0

fastparse_2.13

3.1.1

MIT

geny_2.13

1.1.0

MIT

sourcecode_2.13

0.4.0

MIT

content-type

2.2

Apache 2.0

lang-tag

1.7

Apache 2.0

nimbus-jose-jwt

9.37.3

Apache 2.0

oauth2-oidc-sdk

9.43.6

Apache 2.0 …​

spring-boot-starter-web

3.4.4

Apache 2.0

spring-security-core

6.4.4

Apache 2.0

wildfly-common-ee-dependency-management

35.0.0.Final

Apache 2.0

snakeyaml

2.3

Apache 2.0

1.7. Camunda Web Applications – JavaScript Dependencies

Package Version License

@bpmn-io/align-to-origin

0.7.0

MIT

@bpmn-io/cm-theme

0.1.0-alpha.2

MIT

@bpmn-io/diagram-js-ui

0.2.3

MIT

@bpmn-io/dmn-migrate

0.5.0

MIT

@bpmn-io/dmn-variable-resolver

0.4.0

MIT

@bpmn-io/draggle

4.1.1

MIT

@bpmn-io/feel-editor

1.9.1

MIT

@bpmn-io/feel-lint

1.3.1

MIT

@bpmn-io/form-js

1.8.7

SEE LICENSE IN LICENSE

@bpmn-io/form-js-editor

1.11.3

SEE LICENSE IN LICENSE

@bpmn-io/form-js-playground

1.11.3

SEE LICENSE IN LICENSE

@bpmn-io/form-js-viewer

1.11.3

SEE LICENSE IN LICENSE

@bpmn-io/properties-panel

3.25.0

MIT

@codemirror/autocomplete

6.18.2

MIT

@codemirror/commands

6.7.1

MIT

@codemirror/lang-json

6.0.1

MIT

@codemirror/language

6.10.3

MIT

@codemirror/lint

6.8.2

MIT

@codemirror/search

6.5.7

MIT

@codemirror/state

6.4.1

MIT

@codemirror/view

6.34.2

MIT

@ibm/plex

6.4.0

OFL-1.1

@kurkle/color

0.3.2

MIT

@lezer/common

1.2.3

MIT

@lezer/highlight

1.2.1

MIT

@lezer/json

1.0.2

MIT

@lezer/lr

1.4.2

MIT

@lezer/markdown

1.3.2

MIT

@neverendingsupport/angularjs

1.9.7

SEE LICENSE IN LICENSE.md

@neverendingsupport/angularjs-route

1.9.7

SEE LICENSE IN LICENSE.md

@neverendingsupport/angularjs-cookies

1.9.7

SEE LICENSE IN LICENSE.md

@neverendingsupport/angularjs-animate

1.9.7

SEE LICENSE IN LICENSE.md

@neverendingsupport/angularjs-resource

1.9.7

SEE LICENSE IN LICENSE.md

@neverendingsupport/angularjs-sanitize

1.9.7

SEE LICENSE IN LICENSE.md

@neverendingsupport/angularjs-essentials

2.5.6-angular-ui-bootstrap-2.5.7

HeroDevs NES License

@neverendingsupport/angularjs-essentials

1.3.0-angular-moment-1.3.2

HeroDevs NES License

@neverendingsupport/angularjs-essentials

2.19.1-angular-translate-2.20.4

HeroDevs NES License

@neverendingsupport/bootstrap

3.4.5

HeroDevs NES License

angular-data-depend

1.0.0

MIT

array-move

4.0.0

MIT

big.js

6.2.2

MIT

bpmn-font

0.12.1

SIL

bpmn-js

16.5.0

SEE LICENSE IN LICENSE

bpmn-moddle

8.1.0

MIT

call-bind

1.0.7

MIT

camunda-bpm-webapp

7.23.0-SNAPSHOT

camunda-dmn-js

1.8.0

MIT

camunda-dmn-moddle

1.3.0

MIT

chart.js

4.4.1

MIT

classnames

2.5.1

MIT

clipboard

2.0.11

MIT

clsx

2.1.1

MIT

cmmn-js

0.20.0

SEE LICENSE IN LICENSE

cmmn-moddle

5.0.0

MIT

codemirror

6.0.1

MIT

component-emitter

1.3.1

MIT

crelt

1.0.6

MIT

css.escape

1.5.1

MIT

define-data-property

1.1.4

MIT

diagram-js

13.4.0

MIT

diagram-js-direct-editing

2.1.2

MIT

diagram-js-grid

0.2.0

MIT

diagram-js-origin

1.4.0

MIT

didi

4.0.0

MIT

dmn-font

0.6.2

SIL

dmn-js

15.1.0

SEE LICENSE IN LICENSE

dmn-js-decision-table

15.1.0

SEE LICENSE IN LICENSE

dmn-js-drd

15.1.0

SEE LICENSE IN LICENSE

dmn-js-literal-expression

15.1.0

SEE LICENSE IN LICENSE

dmn-js-properties-panel

3.2.1

MIT

dmn-js-shared

15.1.0

SEE LICENSE IN LICENSE

dmn-moddle

10.0.0

MIT

dom4

2.1.6

MIT

dompurify

3.2.4

MPL-2.0 OR Apache-2.0

downloadjs

1.4.7

MIT

es-define-property

1.0.0

MIT

es-errors

1.3.0

MIT

escape-html

1.0.3

MIT

events

3.3.0

MIT

fast-safe-stringify

2.1.1

MIT

fast-xml-parser

4.3.4

MIT

feelers

1.4.0

MIT

feelin

3.1.2

MIT

file-drops

0.5.0

MIT

flatpickr

4.6.13

MIT

focus-trap

7.6.0

MIT

function-bind

1.1.2

MIT

get-intrinsic

1.2.4

MIT

gopd

1.0.1

MIT

hammerjs

2.0.8

MIT

has-property-descriptors

1.0.2

MIT

has-proto

1.0.3

MIT

has-symbols

1.0.3

MIT

hasown

2.0.2

MIT

htm

3.1.1

Apache-2.0

ids

1.0.5

MIT

inferno

5.6.3

MIT

inherits

2.0.4

ISC

inherits-browser

0.1.0

ISC

jquery

3.7.1

MIT

jquery-ui

1.13.2

MIT

lang-feel

2.2.0

MIT

lezer-feel

1.4.0

MIT

luxon

3.5.0

MIT

marked

14.1.3

MIT

min-dash

3.8.1

MIT

min-dom

3.2.1

MIT

mitt

3.0.1

MIT

moddle

4.1.0

MIT

moddle-xml

7.5.0

MIT

moment

2.30.1

MIT

mousetrap

1.6.5

Apache-2.0 WITH LLVM-exception

object-inspect

1.13.2

MIT

object-refs

0.4.0

MIT

path-intersection

3.1.0

MIT

preact

10.24.3

MIT

q

1.5.1

MIT

qs

6.13.0

BSD-3-Clause

saxen

8.1.2

MIT

selection-ranges

4.0.2

MIT

selection-update

0.1.2

MIT

set-function-length

1.2.2

MIT

side-channel

1.0.6

MIT

style-mod

4.1.2

MIT

superagent

8.1.2

MIT

tabbable

6.2.0

MIT

table-js

9.2.0

MIT

tiny-svg

2.2.4

MIT

w3c-keyname

2.2.8

MIT

1.8. Public API

OrqueIO provides a well-defined public API to ensure stable integration points for developers. This section explains what is considered part of the public API and how backwards compatibility is handled during version updates.

1.8.1. Definition of Public API

The OrqueIO public API is limited to the following components:

Java API All non-implementation Java packages (those whose package names do not contain impl) in the following modules are considered public:

  • orqueio-engine

  • orqueio-engine-spring

  • orqueio-engine-cdi

  • orqueio-engine-dmn

  • orqueio-bpmn-model

  • orqueio-cmmn-model

  • orqueio-dmn-model

  • orqueio-spin-core

  • orqueio-connect-core

  • orqueio-commons-typed-values

HTTP API (REST API)

  • orqueio-engine-rest: The HTTP interface (the set of REST endpoints documented in the OrqueIO REST API reference ).
    NOTE : The underlying Java classes used to implement the REST API are not part of the public API.

1.8.2. Backwards Compatibility for Public API

OrqueIO follows the Semantic Versioning scheme (MAJOR.MINOR.PATCH).

  • Minor updates (e.g., from 7.1.x to 7.2.x) will not break the public API.

  • Patch updates (e.g., 7.2.1 to 7.2.2) are fully compatible and typically include only bug fixes.

  • Major updates (e.g., 7.x to 8.x) may introduce breaking changes and will be clearly documented.

This guarantees that applications built on the OrqueIO public API remain stable across regular feature and maintenance releases.

2. Getting Started

This section provides a quick start guide to help you get up and running with Orque IO. It covers the prerequisites, installation steps, and basic configuration needed to start using the platform.

2.1. Prerequisites

Please make sure you have the following installed:

Ensure you have the following to run OrqueIO:

  • Java Runtime Environment 17 (JDK 17 recommended) – OrqueIO is built on the same Java platform as Camunda 7. :contentReference[oaicite:0]{index=0}

  • Modern web browser (e.g., Chrome, Firefox, Edge) to access the OrqueIO web applications.

  • Optional: Apache Maven or Gradle if you plan to build custom plugins or integrate OrqueIO as part of your Java applications.

java -version

If you need to install Java Runtime Environment, you can find the download from Oracle link: here.

These prerequisites align with OrqueIO requirements for a smooth installation and development experience.

2.2. Installation

To install Orque IO, you can use the provided Docker images or download the source code and build it yourself. The recommended way is to use Docker for easy setup and deployment.

2.3. Executable Process

OrqueIO can be run in multiple ways—both rapid setup and flexible deployment are supported:

  • Docker / OrqueIO Run distribution: Launch OrqueIO in a single-command setup via Docker or the provided executable JAR. This starts the process engine and bundled web applications (Welcome, Cockpit, Tasklist, Admin) immediately.

  • WAR deployment: Embed OrqueIO into a servlet container such as Apache Tomcat, WildFly, GlassFish, etc. Just drop the WAR file into your server and start.

  • Spring Boot / Embedded Engine: Use OrqueIO as part of a Spring Boot application. Simply include the engine starter dependency and configure via application.yml.

Access OrqueIO in your browser at http://localhost:8080 once running.

2.4. Minimal Configuration

For a basic, production-ready installation of OrqueIO, consider:

  • Database setup: Use a production-grade relational database (PostgreSQL, MySQL, Oracle). Initialize Camunda/OrqueIO’s required tables using provided SQL scripts.

  • Hardware requirements:

  • Disk space: ~1 GB for core installation plus logs; plan for at least 2 GB.

  • CPU/RAM: For light/mid workloads, a simple machine (1–2 CPUs, 1–8 GB RAM) suffices; scale up to (4–64 CPUs, 16–128 GB) for high load.

  • Production readiness: Configure secure access (HTTPS, authentication, CORS), set up monitoring (metrics, alerts), and tune job executor, history levels, and identity settings.

2.5. Next Steps

Once your environment is up and running, you can:

  • Deploy BPMN processes via the web apps or REST API

  • Monitor and troubleshoot using Cockpit

  • Build and integrate OrqueIO plugins or external task workers

  • Plan for future migration to Camunda 8, or simply confirm compatibility of your existing workflows

3. Web Applications

3.1. Tasklist

Web application for human task management.

Tasklist is a component of the OrqueIO distribution. On the OrqueIO start page, you’ll find the Tasklist icon. Click on it to open the Tasklist.
Tasklist can also be used by opening http://localhost:8080/webapp/#/seven/auth/tasks/.

tasklist

3.1.1. Working with Tasklist

In this section, we will walk through a typical human workflow scenario using OrqueIO Tasklist. In the prepackaged distribution, Tasklist includes demo users assigned to different user groups. For this example, sign in with the user demo.

Start a Process

To start a process instance via Tasklist, click on Start process in the dashboard header menu and select one of the available process definitions. If no process definitions are shown, verify that your process application is correctly deployed and that you have the required permissions to start a process.

For our example, start the Invoice Receipt process. After selecting it, complete the start form and click Start to proceed.

Required permissions: - CREATE_INSTANCE and READ on the process definition level - CREATE on all process instances

Create a Filter

Once the process has started, you can create a filter to easily view related tasks.

For example, create a filter to display all tasks assigned to the currently logged-in user that belong to the Invoice Receipt process definition. To do so:
. Click on Create a Filter and provide a name (e.g., My Invoice Tasks).
. Under Criteria, add a criterion:
- Select Name in the Process Definition submenu as the key and enter Invoice Receipt as the value.
. Add another criterion:
- Select Assignee under User/Group and set the value to ${ currentUser() }.
. To share the filter with colleagues, go to Permissions and check Accessible by all users.
. Finally, click Save.

The filter will appear in the left sidebar of the dashboard. Select it to display the corresponding user tasks.

See the Filters section for more details.

Claim Tasks

Before working on a task, you must claim it. Click on Claim in the task view section. If necessary, you can reassign the task to another user by clicking the assignee’s name (e.g., Demo Demo) and entering a new username.

See the Claiming, Unclaiming, and Reassigning Tasks section for more information.

Working on Tasks

To start working on a task, select it from the filter results. On the right-hand side, the embedded task form will appear.

In our example, the form asks whether you approve an invoice. Tick Do you approve? and click Complete. After completion, the task will be marked as done, and the process will advance to the next step (e.g., Prepare Bank Transfer).

You can also visualize the process flow by clicking the Diagram tab in the task view.

See the Task Forms section for more details.

Set a Follow-Up Date

If a task arrives just before the end of the working day, you can set a reminder to handle it later. Click on Set follow-up date in the task view section and select a date in the calendar that is displayed. We can also set an exact time for the follow-up.

See the Follow-Up section for more details.

Comment a Task

You can add comments for other Tasklist users. Click on Add Comment in the task view section, type your message (e.g., “Hi Mary, please review this task”), and save it. The comment will appear in the task history.

See the Comments section for more details.

Set Due Date

To ensure timely completion, you can assign a due date to a task. Click on Set due date in the task view section, pick a date from the calendar, and optionally specify a time.

See the Due Dates section for more details.

This concludes our example. You have now seen how to start processes, create filters, claim and work on tasks, and use additional features like reminders, comments, and deadlines in OrqueIO Tasklist.


3.1.2. Dashboard

On the OrqueIO Tasklist dashboard, you can view all pending tasks at a glance. The left panel displays the available filters, while the upper-right section allows you to set follow-up or due dates, claim or unclaim tasks, reassign tasks, and add comments.

Below this area, the embedded task form is displayed (external task forms are not supported here). You can also switch to the task history, view the process diagram, or see a detailed description of the user task.

tasklist dashboard
Toggle view

Tasklist allows you to adjust the dashboard view according to your needs. You can focus on the filters, the filter results, the task view, or display the full dashboard by clicking the corresponding toggle view button. At any time, you can expand the task view to full focus by clicking the expand button.

tasklist toggle view
Start a process

To start a process instance in Tasklist, click the Start process button in the header menu and select a process from the list of available process definitions. If no processes are shown, ensure that your process application has been deployed correctly.

If a start form is defined for the selected process, it will be displayed. Otherwise, Tasklist will notify you that no start form exists and present a generic start form, allowing you to add variables to the new process instance.

tasklist start process

Create a standalone task

Tasklist allows you to create standalone tasks. To do this, click the Create task button. In the form that appears, you can enter a task name, assign it to a user, and provide a description. Click Save to create the task.

The newly created standalone task will appear in the filter results and can be managed like any other task. You can add variables and complete the task. Once completed, the task data is saved to the database, and the task is removed from the Tasklist view.

tasklist create task

Filter results

This section provides an overview of all tasks for the selected filter. Filters are displayed according to priority, with the lowest-priority filter shown first. After selecting a filter, you will see all associated tasks, sorted by a default criterion (typically the creation date). You can change the sorting by clicking on the column header of the desired property, and toggle between ascending and descending order.

Multiple sorting criteria can be applied by adding additional properties using the plus button. Sorting is hierarchical, meaning the first property takes precedence, followed by the second, and so on. You can also sort tasks based on variable values, enabling use cases such as ordering invoices by their amount.

To begin working on a task, simply select it from the list.

tasklist filter results

  • Search for tasks
    Above the filter results, you can search for user tasks within the selected filter. Click in the search box and choose the property to search for. You can also start typing to quickly find the desired property. Depending on the property, you may need to specify a value. Some properties support additional operators, such as:

  • like – searches for tasks where the entered value is a substring of the property value

  • in – allows a comma-separated list of possible values

When searching for variables, you must provide the variable name. If the selected filter defines labels for variables, you can choose the label as the variable name. Otherwise, you must enter the exact variable name. Changing the selected filter updates the search results accordingly.

For string variables containing numeric, boolean, or null values, wrap the value in single quotes (e.g., '93288' or 'NULL').

Additionally, you can:

  • Copy a link to the current search query using the 🔗 button

  • Save a search query to your browser’s local storage using the 💾 button and providing a name. Later, you can retrieve it by clicking the 💾 button and selecting the saved query from the dropdown menu.

tasklist search tasks
  • Case insensitive search
    In some searches, the capitalization of values may not be relevant. For Process, Task, and Case Variables, you can configure whether the search is case-sensitive or case-insensitive. For example, a case-insensitive search for Fruits Inc. will also match fruits inc. or FRUITS Inc..

    When your search includes one of these variables, two checkboxes appear, allowing you to set case handling independently for the variable name and variable value. The selected option applies to all variable queries within the same search.

  • IN Operator

tasklist in operator

Tasklist supports the IN operator for the following query criteria: Tenant ID and Process instance ID.

By default, search criteria are combined using a logical AND (conjunctive normal form). However, you may need to search for multiple values for a single criterion. The IN operator allows you to find tasks where any of the specified values match.

To use the IN operator, select a criterion that supports it and enter the values as a comma-separated list. To modify the list, click on the value to start editing. For easier editing, you can expand the value in a modal dialog by clicking the ⤢ button.

tasklist criterion value
Task view

The right section of the dashboard displays the task view. From here, you can work on tasks and perform various actions.

tasklist task view
  • Set due dates and follow-up dates
    At the top of the task view, you can set a due date and a follow-up date for the selected task. The due date indicates when the task should be completed, while the follow-up date serves as a reminder or for monitoring purposes.

  • Claim, unclaim, and reassign tasks
    Within the task view, you can claim, unclaim, and reassign tasks.

    • To claim a task, click Claim.

    • To unclaim a task, click the ✖ button next to the username of the claimed task.

    • To reassign a task to another user, click the username and enter the target user’s name.

    • You can also assign tasks to user groups by clicking Add Groups.

  • Comments
    In Tasklist, you can add and view comments for individual tasks. After selecting a task from the filter results, click Add Comment at the top of the task view section to add a comment. All comments for a task can be viewed in the task history.

Task Detail Tabs

In the lower section of the task view, several tabs allow you to access both the task form and additional information related to the selected user task:

  • Task form view – The Form tab, selected by default, displays the task form (embedded, generated, or generic). You can work on and complete the task here.

  • Task history – The History tab shows the history of the user task, including assignment changes, updates to due and follow-up dates, task claims/unclaims, and comments.

  • Diagram view – The Diagram tab presents the process definition diagram, with the current user task highlighted.

  • Task description – The Description tab displays the user task description. See the BPMN 2.0 reference for more details on task descriptions.

tasklist task detail tabs

3.1.3. Filters

tasklist filters

In Tasklist of OrqueIO, you can create and select filters to display task lists based on specific criteria. To create a filter, click Create a Filter. The configuration screen provides several sections:

General
  • Name and Description – Define the filter’s name and description.

  • Color – Assign a color for visual identification.

  • Priority – Set the display order of filters on the dashboard.

  • Auto-Refresh – Enable automatic refresh of the filter results. The default refresh interval is 10 seconds.

Permissions
  • Specify which users or groups can view the filter.

  • The Accessible by all users checkbox makes it globally visible.

  • This permission is equivalent to a READ right.

  • To assign other permissions, use the Authorizations tab in the OrqueIO Admin.

Criteria
  • Define which tasks will be displayed when the filter is selected.

  • Each criterion requires a key and a value.

  • Keys are grouped into several categories:

    • Process Instance: ID, Business Key

    • Process Definition: ID, Key, Name

    • Case Instance: ID, Business Key

    • Case Definition: ID, Key, Name

    • Other: Process Instance State, Activity Instance ID, Execution ID

    • User/Group: Assignee, Owner, Candidate User/Group, Involved User, Unassigned, Delegation State

    • Task: Definition Key, Name, Description, Priority

    • Dates: Created Date, Due Date, Follow Up Date

  • Keys marked with a * accept expressions as values.

Variables
  • Specify which variables are displayed in the filter results section.

  • Variables defined here do not influence which tasks are shown.

  • For each variable, provide:

    • Name – the technical (coded) name of the variable.

    • Label – the label used in the filter results list.

Expressions in Filters

Several filter criteria in Tasklist support expressions as values. These expressions are written in JUEL. For filters related to times and dates, you can use the dateTime class, which returns a Joda-Time object.

Security Consideration
Filter expressions can potentially be abused to execute arbitrary code when the query is evaluated. Because of this, any user authorized to create filters must be trusted.
The default behavior of evaluating filter expressions can be disabled in the process engine configuration.
Refer to the Security Considerations for Custom Code section for more details.
Common Filters
tasklist common filters

Below is a list of some of the most common and useful filters you can create in Tasklist, along with their recommended configuration.

Filter name Description Criterion Key Criterion Value

All my tasks

Displays all tasks assigned to the currently logged-in user

Assignee

${currentUser()}

Tasks of a specific user

Displays all tasks assigned to a specified user

Assignee

User ID of the user (e.g., demo)

All my groups

Displays all tasks assigned to any group of which the current user is a member

Candidate Groups

${currentUserGroups()}

Tasks of a specific group

Displays all tasks assigned to a specific user group

Candidate Groups

Group name (e.g., accounting)

Unclaimed tasks of a specific group

Displays all tasks assigned to a specific group which have not been claimed yet

Candidate Groups, Unassigned

Group name (e.g., accounting), N/A

Unassigned tasks

Displays all tasks that have not yet been claimed

Unassigned

N/A

Overdue tasks

Displays all tasks with a due date set in the past

Due Before

${now()}

Tasks due today

Displays all tasks with a due date set for the current date

Due After, Due Before

${dateTime().withTimeAtStartOfDay()}, ${dateTime().withTimeAtStartOfDay().plusDays(1).minusSeconds(1)}

Tasks due after a specific date

Displays all tasks with a due date set after a specified date

Due After

Date in ISO 8601 format (e.g., 2015-01-01T00:00:01)

Tasks due within a specific timespan

Displays all tasks with a due date within a specified timespan (example: within 2 days)

Due After, Due Before

${now()}, ${dateTime().plusDays(2)}

Tasks due after a specific timespan

Displays all tasks with a due date after a specified timespan (example: after 2 days)

Due After

${dateTime().plusDays(2)}

Tasks with a certain priority

Displays all tasks marked with a specified priority (example: priority 10)

Priority

10

Follow-up tasks

Displays all tasks with a follow-up date set in the past

Follow Up Before

${now()}

3.1.4. Task Lifecycle

The following diagram presents the task lifecycle along with the available transitions in OrqueIO. For guidance on managing these transitions programmatically within your application, consult the Java API Reference.

tasklist task lifecycle

3.1.5. Plugins

OrqueIO Tasklist uses plugins to add custom functionality without extending or modifying the core web application.
For more details about the concepts behind plugins, refer to the Cockpit plugins section.

Difference Between Cockpit and Tasklist Plugins
To publish a plugin with Tasklist, the class name must be added in a file called org.orqueio.bpm.tasklist.plugin.spi.TasklistPlugin located in the META-INF/services directory.
Tasklist plugins cannot provide additional SQL queries via MyBatis mappings.
Plugin Points

Below are the plugin points where you can add your own functionality:

  • tasklist.navbar.action

tasklist navbar action
  • tasklist.task.action

tasklist task action
  • tasklist.header

tasklist header
  • tasklist.task.detail

tasklist task detail

his plugin point has a label property which will be rendered in the navigation even when the plugin is not selected.

properties: {
  label: "My Plugin"
}

The render function receives the following additional data: taskId


The placement of your plugin can be configured as shown in the following example:

var ViewConfig = ['ViewsProvider', function(ViewsProvider) {
  ViewsProvider.registerDefaultView('tasklist.task.detail', {
    id: 'sub-tasks',
    priority: 20,
    label: 'Sub Tasks'
  });
}];

For more information on creating and configuring your own plugin, see:

3.1.6. Configuration

You can customize the default behavior and appearance of the OrqueIO Tasklist through the central configuration file located at app/tasklist/scripts/config.js. Available options include:

Date Format

Configure how dates are displayed using the dateFormat object. Each property should follow moment.js formatting. Common formats:

  • monthName – full month name (e.g., January)

  • day – numeric day of the month (1..31)

  • abbr – short date format including time

  • normal – standard date format with time

  • long – verbose date format including day of the week and time

  • short – compact format without time

Example

export default {
  // …
  "dateFormat": {
    "monthName": "MMM",
    "long":   "LLLL"
  }
}

3.2. Cockpit

Web application for monitoring and operations

OrqueIO cockpit provides access to deployed BPMN processes and DMN decisions, allowing you to search through both running and completed instances and perform operations on them. By hovering over the icon with your mouse or using the tab key, several options are displayed, including processes, decisions, human tasks, deployments, and batches. These options are highlighted in the following screenshot. Web application for monitoring and operations


3.2.1. Dashboard

The OrqueIO Cockpit dashboard provides a quick overview of running and historic operations, as well as information about deployments.

At the top of the dashboard, a plugin displays pie charts showing the number of running process instances, open incidents, and open human tasks. Clicking on a number or a section of a pie chart redirects you to the corresponding search with preselected query parameters.

On the right side, you can view an overview of deployed process definitions, decision definitions, case definitions, and the total number of deployments.

The dashboard can be extended with additional plugins to display custom metrics or information relevant to your environment.v

cockpit

3.2.2. BPMN Processes

OrqueIO Cockpit enables monitoring of BPMN processes. The dashboard serves as the entry point to all process monitoring features.

From the dashboard, you can either select a deployed process definition or search for a specific process instance. Based on your selection, you will be directed to the corresponding process definition view or process instance view to inspect and analyze process execution.

Dashboard

The Processes Dashboard in OrqueIO Cockpit serves as the main entry point for process monitoring. It includes a pre-installed plugin that displays all deployed process definitions. You can also enhance the dashboard by adding additional plugins to extend its functionality.

Deployed Processes

This plugin allows you to quickly monitor the status of a process definition. Green and red indicators show running and failed jobs, respectively. A red indicator signals that at least one process instance or sub-process instance has an unresolved incident. You can investigate and pinpoint the issue using the process definition view.

cockpit deployed processes

Above the table of deployed processes, the search component allows you to find processes by their name or key. Click in the search box and select the desired property. Both properties support the like operator, which enables searching for process definitions where the entered value is a substring of the property.

You can also copy a link to the current search query to your clipboard or save search queries to your browser’s local storage. To save a query, click the save button, enter a name in the drop-down menu, and retrieve it later by selecting the saved name.

cockpit deployed processes 1

You can switch to the Preview tab to view the rendered process model for each deployed process. This view also shows how many instances of the process are currently running and the current state of the process. Green and red dots indicate running and failed jobs, respectively. Clicking on a process model takes you to the process definition view for more detailed inspection.

cockpit deployed processes 2

Process Definition View

The Process Definition view provides information about the definition and current status of a process. On the left side, you can see the available versions and how many instances of each version are running. Incidents from running process instances are highlighted directly on the rendered diagram with counters, making it easy to identify failed activities. You can navigate the diagram with your mouse: use CTRL + scroll to zoom, and hold the left mouse button to pan. At the bottom left, you can maximize either the diagram view or the detailed information panel.

The Process Instances tab lists all active instances in a table with details such as start time, business key, and state. Selecting an instance by its ID takes you to the process instance view.

The Called Process Definitions tab shows child processes invoked by the current process. Names of called sub-processes are listed and can be clicked to open them in the process definition view. A Parent filter is automatically applied so you only see instances linked to the parent process. In the Activity column, you can select the instance that triggered the child process.

The Job Definitions tab displays job definitions associated with the process definition, including the activity name, type of job, configuration, and state. From here, you can suspend or re-activate job definitions and adjust job priorities.

cockpit process definition view

  • Filter
    At the bottom of the Process Instances tab in the Process Definition View, you can filter specific instances by variables, business keys, activity IDs, or date and time. You can also filter by process definition version by selecting the desired version on the left side of the view. Multiple filters can be combined, and they are applied as logical AND conditions. Variable filters follow the format variableName OPERATOR value, where the supported operators are =, !=, >, >=, <, , and like. The like operator applies only to string variables, and the % character can be used as a wildcard in the value. String and date values must be enclosed in quotation marks " ".

    Note that complex data types are not supported by this filtering feature.

    In addition, you can copy the current filter query to your clipboard or save it to your local browser storage by providing a name in the dropdown menu. Saved queries can later be retrieved and reused directly from the same menu.


  • Runtime View
    ou can add filters in the Process Definition View to refine the list of process instances. Filters can be applied based on variables, the start date and time, the activity ID, or the business key of process instances.

    cockpit runtime view
    • Business Key For example, you can filter process instances by their business key to focus only on instances related to a specific business context.

      cockpit business key
    • Start Date and Time You can filter process instances by their start date. The date value must follow the ISO 8601 standard format. This allows you to narrow down instances that started on or after a specific date and time.

      cockpit start date

When filtering process instances by start date, you can choose between before and after. For example, selecting before will display only the instances that were started prior to the given date.

cockpit start date filter
  • String variable You can filter process instances by matching a string value. Important: do not enclose the string value in quotation marks.

    cockpit string variable
  • Boolean variable You can filter process instances by using a boolean variable. Simply specify the variable name and set its value to either true or false.

    cockpit boolean variable
  • Numeric variable You can filter process instances using numeric variables such as double, integer, long, or short. Specify the variable name together with the numeric value you want to filter on.

    cockpit numeric variable

  • Set Job priority
    In OrqueIO, you can override the default job priority defined in the BPMN 2.0 XML. To do this, open the Job Definitions tab and click the corresponding icon. In the dialog that appears, you can assign a new priority value. If a custom priority is already set, you can reset it to return to the priority defined in the BPMN XML. You can also choose to apply the new priority to existing jobs.

    Additionally, by using the button located to the right of the process diagram, you can update the job priority for all jobs associated with the process definition at once.

    cockpit set job priority

  • Call Activity Navigation
    n OrqueIO, you can navigate from a process containing Call Activities to the corresponding called process definitions. Hover over a Call Activity in the BPMN diagram to reveal a link in the upper right corner of the activity.

Limitation
If the called process is referenced via a process variable or an expression, the target process can only be determined at runtime. For these Call Activities, the diagram will display a greyed-out overlay unless there is an active process instance currently executing that call activity.

You can also use the Called Process Definitions tab to see which Call Activity invokes which process definition. OrqueIO distinguishes three states:

  • Referenced: The called process definition can be determined without runtime information.

  • Running and Referenced**: The called process definition can be determined without runtime information, and a call activity is currently executing it.

  • Running: A process instance is currently calling this process definition, but the called process can only be resolved at runtime and is specific to that instance.

cockpit call activity navigation

Failed Jobs

In OrqueIO, unresolved incidents of a process instance or a sub-process instance are indicated as failed jobs. To pinpoint which instance encountered a failure, you can use the status indicators in the Process Definition View.

Click on a red status dot of the affected instance to see an overview of all incidents. The Incidents tab in the Detailed Information Panel lists the failed activities along with additional information. You can also drill down to the specific failing instance of a sub-process to further investigate the issue.

  • Retry a Failed Job
    In the Process Instance View, you can resolve a failed job by clicking the retry button on the right side of the instance details.

A modal dialog will open where you can:

  • Decide whether to keep the previous due date or set a new absolute date/time.

  • Select which failed jobs should be retried.

After confirming by clicking Retry, OrqueIO will re-trigger the selected jobs and update their retry counts in the database, allowing the Job Executor to acquire and execute them again.


Suspension

In both the Process Definition View and the Process Instance View, you can suspend a selected process definition or process instance by clicking the suspend button on the right side. This temporarily pauses the execution until the process or instance is resumed.

  • Process Definition Suspension
    Suspending a process definition prevents any new instances of that process from being started. While suspended, no operations can be performed on the process definition. You can reactivate a suspended process definition at any time by clicking the reactivate button ▶ on the right side. In the confirmation dialog, you can choose to suspend or reactivate all associated process instances as well, and you can specify whether the action should take effect immediately or at a scheduled time. For more details, see the section on suspending process definitions in the Process Engine chapter.

  • Process Instance Suspension
    If you suspend a process instance in OrqueIO, its execution—including all associated tasks—will be paused. You can reactivate the process instance at any time by clicking the play button ▶ on the right side. For more details, see the section on suspending and reactivating process instances in the process engine chapter.

  • Job Definition Suspension
    In the Process Definition View of OrqueIO, you can suspend a job definition by clicking the pause button ⏸ in the Action column of the Job Definitions tab at the bottom of the screen. This prevents the job definition from being executed in any process instances of the selected process definition. To reactivate the job definition, simply click the play button ▶ in the same Action column. For more details, see the section on suspending and activating job execution in the user guide.


3.2.3. DMN Decisions

In OrqueIO, DMN Decisions can be monitored via the Cockpit dashboard. The dashboard provides an entry point to access the decision monitoring features. By selecting a deployed decision definition, you can view its details in the decision definition view.

All information shown for decision definitions and decision instances is based on historical data. Since decisions are executed instantly without intermediate wait states or persistence points, no runtime data is available.


Dashboard

he Decisions Dashboard in OrqueIO serves as the central hub for monitoring decision executions. It includes a built-in plugin that displays all deployed decision definitions. You can also extend the dashboard by adding additional plugins to enhance decision monitoring capabilities.

Deployed Decisions

This plugin displays a list of deployed decision definitions. Clicking on a decision name opens its decision definition view, where you can access details such as the DMN table and executed decision instances. Similarly, clicking on a decision requirements definition name takes you to its corresponding decision requirements definition view.

dmn deployed decisions

Deployed Decision Requirements Definition

This plugin displays a list of deployed decision requirements definitions (DRDs) in OrqueIO. Click on the name of a DRD to open the decision requirements definition view, where you can access detailed information such as the DRD diagram and the executed decision instances.

Decision Definition View

In the decision definition view, you can see the deployed decision definition displayed as a decision table or literal expression. You can switch between different versions of the decision definition using the dropdown menu on the left, and the table or expression will update automatically. You can also navigate to the deployment containing the selected version by clicking the Navigate to Deployment button, which opens the deployment view. To focus on either the table or the detailed information panel, use the maximize buttons located at the bottom left of the table view.

Below the decision table, all instances of this decision definition are listed. You can search for specific decision instances by entering search criteria in the search box. Start typing to quickly find the desired parameter, then specify its value. You can combine multiple search parameters to refine the results.

You can copy a link to the current search query using the Copy Query button, or save queries locally in your browser by clicking the Save Query button and providing a name. Saved queries can later be retrieved via the Load Query button and selecting the corresponding name.

If a decision instance was executed as part of a process, the view also shows the process definition and the process instance ID that triggered it. Clicking these links navigates to the respective pages. Clicking the decision instance ID opens the detailed decision instance view.

decision definition view

Decision Instance View

he decision instance view displays the decision table or literal expression of the executed decision, along with the values of input variables and the resulting outputs. Input and output values are shown directly in the table cells and are also available under the Inputs and Outputs tabs below the table.
Complex variables, such as Objects, Files, and Bytes, are not shown in the table and must be accessed via the Inputs and Outputs tabs.
Rules that matched during the decision execution are highlighted in the table for easy identification.
You can maximize either the table view or the detailed information panel by clicking the corresponding maximize buttons at the bottom left of the table view.


3.2.4. Deployment View

The deployment view in OrqueIO gives a comprehensive overview of all deployments and their resources. You can view the content of each resource, delete deployments, redeploy previous resources, or create new deployments. Individual resources can also be downloaded directly from this view.

cockpit deployment view

Use the search field at the top of the deployment list to find specific deployments. Similar to the search functionality on the dashboard and in task lists, you can search deployments using a variety of criteria.

Valid search criteria include:

  • Unique ID – the deployment’s unique identifier

  • Name – the deployment name, which does not need to be unique

  • Deployment Time – the timestamp of the deployment

  • Source – the origin of the deployment. This can be set when creating a deployment. For example:

  • process application – deployment created by the application at startup

  • cockpit – deployment made directly in OrqueIO (e.g., via live editing)

  • Source undefined – deployments with no source specified

You can copy a link to the current search query using the Copy Query button. Queries can also be saved locally in your browser using the Save Query button by providing a name. Saved queries can be retrieved later via the Load Query button.

Additionally, the deployment list can be ordered independently of search using the sorting parameter above the search field. You can sort by ID, Name, or Deployment Time, and toggle between ascending and descending order using the arrow next to the sorting criterion.


Delete

To delete a deployment, hover over the desired deployment and click the Delete icon. In the confirmation dialog, you can:

  • Enable Cascade Deletion to also remove running and historic process instances

  • Choose to Skip Custom Listeners and I/O Mappings

Once confirmed, the deployment and any selected associated data will be deleted.


3.2.5. Open Tasks Dashboard

The Open Tasks Dashboard allows you to view how open tasks are distributed across different factors.

For information on adding a custom open tasks dashboard plugin, see the OrqueIO Plugins section.

cockpit open tasks dashboard
Assignments by type

This section shows the total number of open tasks and provides an overview of how these tasks are distributed by type.

Assignment by group

This section displays how all open tasks assigned to groups are distributed among the individual groups.

3.3. Admin

OrqueIO includes the Admin application, which enables you to manage users and groups through the engine’s Identity Service and configure authorizations using the Authorization Service. Admin also supports integration with LDAP systems for centralized user management.

admin

3.3.1. User Management

Users Menu

The Users menu lets you create, edit, and delete user profiles. You can also manage group memberships and update user passwords.

admin users menu

My Profile

By clicking your user name in the Users menu, you can open the My Profile menu. Here, you can edit your personal account settings:

  • Profile – Update your name or email address. The user account ID cannot be changed.

  • Account – Change your password or delete/unlock your account. Note that account deletion is permanent.

  • Groups – View all groups you belong to. With administrator rights, you can assign your account to available groups.

The My Profile menu is also accessible from any OrqueIO web application by clicking your user name in the top-right corner and selecting My Profile.


Initial User Setup

If no administrator account is configured, a setup screen appears the first time a process engine is accessed via Cockpit or Tasklist, allowing you to create an initial admin account.

Administrator accounts are engine-specific, so a separate admin must be configured for each engine instance.

In default or demo installations, pre-configured users are provided for testing. The default admin account can be accessed with the following credentials:

  • Username: demo

  • Password: demo

admin initial user setup

Administrator Account

Users of the orqueIO-admin group (automatically configured in demo process applications) are granted administrator privileges. At least one user must be part of this group; otherwise, the initial setup screen will be displayed.

Administrators can manage users and groups, as well as define authorization rules for various resources. For further information, refer to the chapter on Authorizations.

3.3.2. Group Management

Groups Menu

The Groups menu lets you create, edit, and delete user groups. You can also view the members of each group.

admin groups menu

3.3.3. Tenant Management

Tenants Menu

The Tenants menu allows you to create, edit, and delete tenants. You can also view which users or groups belong to each tenant.

admin tenants menu

  • Create a new tenant
    To create a new tenant:

    • Click the Create new tenant button.

    • Enter the Tenant ID and Tenant Name in the respective fields.

    • Click Create new Tenant to finalize the creation.

A new tenant will then be added to the system.


  • Add an user to a tenant
    To add a user to a tenant, open the user’s account settings and select the Tenants menu on the left.

    In this menu, click Add to a tenant and choose the tenants to which the user should be assigned.


  • Add a group to a tenant
    To add a group to a tenant, open the group’s settings and select the Tenants menu on the left.

    Then, click Add to a tenant and choose the tenants to which the group should belong.


3.3.4. Authorization Management

Administrators can manage authorizations for various resources, such as Applications, Groups, and Filters. The following sections provide simple use cases demonstrating how to work with an administrator account.

For more details, see the Authorization Service documentation.

admin authorization management
Accessing the Authorization Management Menu
The Authorization Management menu is accessible only to users who have been granted Read permission for authorizations.

Grant Basic Permissions

In this use case, we will assign basic permissions. To begin, you need some users and a group.

  • Create two new users via the users menu.

  • Create a group named support in the groups menu.

  • Add the newly created users to the support group through the users menu.


  • Application Access
    Next, configure the authorizations for the newly created group and users.

    1. Define which application the members of your new group can access.

      • Open the Applications menu and create a new Application Authorization rule.

      • Since the support group should have access to Tasklist, add the corresponding rule. → All members of the support group can now use Tasklist.

admin application access 1
  1. Additionally, assign application-specific access to one of the new users.

    • Create a user-specific authorization rule for the user lemmy.

    • Grant lemmy access to Cockpit.

admin application access 2

Finally, log in with the newly created user accounts to verify that each has access to the appropriate applications.

admin application access 3
  • Filter Access
    Currently, users in the support group can only view the predefined filters in Tasklist. To allow them to access an additional filter, create a new authorization rule for that specific filter.

    admin filter access

The permissions you configure here correspond to those available in the filter settings within Tasklist. The resource ID of the filter can be retrieved from the database table ACT_RU_FILTER.

For more details on managing filters, refer to the section of Filters.

  • Member Visibility
    The visibility of users and groups in Tasklist depends on the configured authorizations. At the moment, you can only see the support group folder, but not individual colleagues.

    To change this, log in to the OrqueIO Admin application as an administrator, open the User Authorization menu, and create the necessary rules.

    admin member visibility

    With these rules in place, all members of the support group will be able to view the newly added users lemmy and ozzy.


Application-Specific Permissions

This use case shows how to grant a group access to Cockpit while restricting them to read-only permissions. We will continue with the support group created in the previous example.

To configure this, we first need to identify the resources available in Cockpit in order to assign the correct permissions. Among the predefined resources, the most relevant are:

  • Process Definitions

  • Process Instances

  • Tasks

admin application specific permissions 1

Start by granting the group permission to access Cockpit.

admin application specific permissions 2

Then, assign the READ permission for all available resource IDs (using an asterisk *) for each of the resources listed above.

With this setup, all members of the support group will be able to open Cockpit and view every element inside, without being able to modify anything. Keep in mind that if an individual user has more specific permissions, those will override the group-level permissions.

Once you have one group with full read access to Cockpit, you may also define another group with restricted rights, for example, to manage only a single process.


Restrict Process Permissions

Not every process should be visible or manageable by all users or groups. Depending on the organizational structure, it is often necessary to restrict access so that only specific groups can view or control certain processes.

In this example, we want to grant the accounting group (already created and with access to Cockpit, full access to the invoice process, and only to this process.

To allow a group or user to see process definitions, they must have at least the READ permission on the Process Definition resource. Similarly, to view active process instances, the READ permission is also required on the Process Instance resource.

admin restrict process permissions

Since the accounting group should manage the invoice process completely, we grant them all permissions for that process. The resource ID used in the authorization rule corresponds to the process definition key.

Finally, once these permissions are in place, it is often useful to create an additional user with administrator rights to oversee and manage such access configurations.


Create a User with All Permissions

During the initial setup, you were required to create an administrator account. In real-world scenarios, it is often useful to have more than one administrator account to ensure continuity in managing users and authorizations.

An administrator in OrqueIO is simply a user who holds the ALL permission for every available resource and resource ID. For example, to give the accounting group full control over authorizations, you would assign them an authorization rule with ALL permissions for the Authorizations resource.

admin create user with all permissions

There are several ways to create an additional administrator account:

  • Add a user to the default orqueio-admin group (if it was kept from the demo configuration).

  • Use the Administrator Authorization Plugin, configuring it to grant all permissions to a specific user or group.

  • Create your own administrator group, assign it full permissions, and then add users to this group.

  • Directly grant a specific user all permissions across all resources.

Once the new administrator account is created, you can proceed with managing authorizations, users, and starting processes as needed.


Grant Permission to Start Processes from Tasklist

In OrqueIO, processes are started directly from Tasklist. For a user or group to initiate a process, specific permissions need to be assigned.

admin grant permissions to start 1

In this example, we want the accounting group to be able to start the invoice process from Tasklist. The configuration steps are as follows:

admin grant permissions to start 2
  1. Grant access to Tasklist First, provide the group with the necessary authorization to access the Tasklist application (see Application-Specific Permissions).

  2. Grant READ and CREATE_INSTANCE on the process definition These permissions allow the group to view the invoice process definition and create new instances of it from Tasklist.

admin grant permissions to start 3
  1. Grant CREATE on process instances* This permission ensures that the group can actually create new process instances. Since process instance IDs are generated dynamically, the resource ID must be set to the asterisk (*), representing all instances.

With these rules, members of the accounting group can start new instances of the invoice process directly from Tasklist.

Next, we will look at how to restrict permissions on specific running process instances.


Grant Permission for Single Process Instance

In OrqueIO, it is possible to restrict a user’s or group’s permissions to a single process instance. Once the process ends, the group or user will no longer have the ability to interact with any other running instances.

For example, let’s use the accounting group. We assume this group already has access to Cockpit (see Application Access) and that a process with the name and key OrderProcess exists.

admin grant permissions to single process 1

To allow the group to view the process in Cockpit, first grant the READ permission on the process definition.

admin grant permissions to single process 2

Next, retrieve the process instance ID from Cockpit. This ID can be found by clicking on the process definition name or the diagram preview in the Cockpit dashboard.

admin grant permissions to single process 3

Use this instance ID as the resource ID when granting the group full permissions for the Process Instance resource. This ensures that the group’s permissions apply only to that specific running instance.

Similarly, permissions can also be restricted at the task level, allowing fine-grained access control over individual tasks.


Grant Permission for Single Tasks

Since multiple groups may participate in the same process, it is often necessary to restrict certain tasks to specific users or groups. In this example, we will reuse the accounting group and the invoice process introduced earlier. For this setup, ensure that at least one instance of the process is running.

admin grant permissions for single tasks 1

First, grant the accounting group the READ permission on filters so that related tasks are visible in Tasklist.

admin grant permissions for single tasks 2

Next, open Cockpit and assign the desired task to the accounting group. This action automatically creates an authorization entry for the task in Admin, using the task ID as the resource ID, and grants the group READ and UPDATE permissions.

These examples illustrate the most common scenarios for combining resources, permissions, and resource IDs in OrqueIO.


3.3.5. System Management

The System Settings menu provides general information about the process engine. It allows users with the necessary system permissions to access details such as diagnostics and metrics.

Accessing the System Settings menu
The System Settings menu is only available to users who have been granted the ALL permission for authorizations.
admin system management

Diagnostics

The Diagnostics menu provides access to important information about your OrqueIO environment. Its main purpose is to increase transparency by allowing you to easily view and copy system diagnostics data. In case of an issue, this information helps to quickly understand your OrqueIO setup and facilitates troubleshooting and support.

admin diagnostics

Execution Metrics

The Execution Metrics menu in Admin provides an overview of the approximate number of Flow Node Instances (FNI), Executed Decision Elements (EDE), Process Instances (PI), Decision Instances (DI), and Task Users (TU) assigned to user tasks within a selected start date range.

The dashboard displays metrics for the last 12 months in both chart and table formats. Legacy metrics (FNI, EDE) are hidden by default but can be shown by selecting the "Display legacy metrics" checkbox. Below the chart, all available annual usage metrics are listed.

Metrics and diagnostics data can be copied to the clipboard by clicking the copy button. The copied content includes two parts: the first part contains the key metrics useful for monitoring OrqueIO usage, and the second part contains system diagnostics data to help with troubleshooting and support. Users can choose whether to share the diagnostics data.

admin execution metrics

3.3.6. Admin Plugins

Plugin Compatibility
Note that plugin code may need to be updated when upgrading OrqueIO Admin, for example due to changes in CSS or JavaScript APIs.

OrqueIO Admin supports plugins to extend functionality without modifying the core application.
For a deeper understanding of the plugin architecture, refer to the Cockpit plugins section, as the concepts are similar.

Difference Between Cockpit and Admin Plugins
To register a plugin in OrqueIO Admin, its class name must be listed in a file called org.orqueio.admin.plugin.spi.AdminPlugin located in META-INF/services.
Unlike Cockpit plugins, Admin plugins cannot provide additional SQL queries using MyBatis mappings.

Plugin Points

OrqueIO Admin provides several points where you can add your own plugins. * Route
Name: admin.route

This plugin point defines the path attribute, which specifies the hash route for the page. The page will be rendered when the user navigates to the corresponding URL in the browser, e.g., #/my-path.

properties: {
  path: "/my-path"
}

  • Dashboard
    Name: admin.dashboard.section

OrqueIO Admin features a plugin-based dashboard similar to Cockpit. This plugin point uses the label and pagePath attributes. The label sets the section heading, while pagePath links the heading to a sub-page. If pagePath is undefined, the label is displayed without a link.

properties: {
  label: "My Plugin",
  pagePath: '#/myPage'
}

You can find examples of OrqueIO Admin dashboard plugins here.


3.4. Welcome

Entry point web application with user profile

The Welcome application presents links to the applications the user has access to. It features a user profile in which the user can change his name, email address and password. The application can also have configurable custom links, for example for intranet or other useful resources.

orqueio welcome

3.4.1. Plugins

Besides configurable custom links, plugins can be used to enhance the Welcome application with additional functionality.
Keep in mind that the Welcome application only supports frontend plugins.

Plugin Point
  • Name: welcome.dashboard

welcome dashboard
  • Name: welcome.profile

welcome profile

4. User Guide

This document is intended for developers who want to integrate the OrqueIO Process Engine into their applications.

4.1. Process Engine

4.1.1. Process Engine Bootstrapping

OrqueIO provides several options for configuring and creating a process engine, depending on whether you are using an application-managed engine or a shared, container-managed engine.

Application Managed Process Engine

When you manage the OrqueIO process engine within your application, it can be configured using the following methods:

  • Programmatically – Using the Java API

  • Spring Integration – Configure the engine via Spring


Shared, Container Managed Process Engine

In a container-managed setup, a container of your choice (e.g., Tomcat or Wildfly) handles the OrqueIO process engine. Configuration is performed using container-specific methods. For more details, see Runtime Container Integration.

  • ProcessEngineConfiguration Bean
    The OrqueIO engine uses the ProcessEngineConfiguration class to configure and build a standalone process engine. Several subclasses are available to define the engine configuration for different environments, each providing sensible defaults. It is recommended to choose the class that best matches your environment to reduce the number of properties you need to configure manually.

The following classes are currently available:

org.orqueio.engine.impl.cfg.StandaloneProcessEngineConfiguration : Use this class for a standalone engine setup. The engine manages transactions internally. By default, the database schema is checked only at engine startup, and an exception is thrown if the schema is missing or its version is incorrect.

org.orqueio.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration : A convenience class for unit testing. The engine manages transactions internally and uses an H2 in-memory database by default. The database is created at engine startup and dropped at shutdown. Typically, no additional configuration is required, except for optional features like the job executor or mail capabilities.

org.orqueio.engine.spring.SpringProcessEngineConfiguration : Use this class when running the engine in a Spring environment. See the Spring Integration section for details.

org.orqueio.engine.impl.cfg.JtaProcessEngineConfiguration : Use this class when running the engine in standalone mode with JTA-managed transactions.


  • Bootstrap a Process Engine Using the Java API
    You can configure the OrqueIO process engine programmatically by creating an appropriate ProcessEngineConfiguration object or by using one of the pre-defined configurations:

ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration();
ProcessEngineConfiguration.createStandaloneInMemProcessEngineConfiguration();

Once the configuration is set up, call the buildProcessEngine() method to create the process engine:

ProcessEngine processEngine = ProcessEngineConfiguration
  .createStandaloneInMemProcessEngineConfiguration()
  .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_FALSE)
  .setJdbcUrl("jdbc:h2:mem:my-own-db;DB_CLOSE_DELAY=1000")
  .setJobExecutorActivate(true)
  .buildProcessEngine();

4.1.2. Process Engine API

Services API

The Java API is the most common way to interact with the OrqueIO engine. The central entry point is the ProcessEngine, which can be created in several ways as described in the configuration section.

From the ProcessEngine, you can access the different services that provide workflow and BPM functionality. Both the ProcessEngine and its service objects are thread-safe, so a single reference can be reused across the entire server.

ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine();
RepositoryService repositoryService = processEngine.getRepositoryService();
RuntimeService runtimeService = processEngine.getRuntimeService();
TaskService taskService = processEngine.getTaskService();
IdentityService identityService = processEngine.getIdentityService();
FormService formService = processEngine.getFormService();
HistoryService historyService = processEngine.getHistoryService();
ManagementService managementService = processEngine.getManagementService();
FilterService filterService = processEngine.getFilterService();
ExternalTaskService externalTaskService = processEngine.getExternalTaskService();
CaseService caseService = processEngine.getCaseService();
DecisionService decisionService = processEngine.getDecisionService();

The method ProcessEngines.getDefaultProcessEngine() initializes and builds the process engine on its first call, and then always returns the same instance. Proper lifecycle management of process engines can be done with:

  • ProcessEngines.init() – initializes and creates all configured process engines

  • ProcessEngines.destroy() – closes and cleans up all process engines

All OrqueIO services are stateless. This design allows you to run OrqueIO on multiple nodes within a cluster, all connected to the same database, without worrying about which node executed a previous call. Every call to a service is idempotent, meaning the outcome is the same regardless of where it is executed.

The RepositoryService is typically the first service developers interact with when working with the OrqueIO engine. It provides essential operations for managing and manipulating deployments and process definitions.

  • A process definition is the executable representation of a BPMN 2.0 process within OrqueIO. It describes the structure and behavior of each step in a process.

  • A deployment is the packaging unit in OrqueIO. A deployment may include one or several BPMN 2.0 XML files along with any other resources. Developers decide the scope of a deployment: it can be a single BPMN XML file or a complete package of processes and related resources. For example, a deployment named hr-processes might contain everything related to HR workflows.

Deploying means uploading these packages to the OrqueIO engine. During deployment, processes are inspected, parsed, and persisted in the database. Once deployed, the system recognizes the processes, making them available for execution.

The RepositoryService enables you to:

  • Deploy new process definitions and related resources.

  • Query available deployments and process definitions in the engine.

  • Suspend or activate process definitions.

    • Suspend: prevents any further operations on a process definition.

    • Activate: re-enables its execution.

  • Retrieve deployment resources, such as files included in a package or automatically generated process diagrams.

While the RepositoryService manages static information (such as deployments and process definitions), the RuntimeService handles dynamic execution.

It is responsible for starting and managing process instances derived from process definitions.

  • A process definition describes the structure and flow of a process.

  • A process instance represents a single execution of that process definition. In practice, multiple instances of the same definition often run concurrently.

The RuntimeService also manages process variables, which are data values specific to a process instance. These variables can influence process behavior, for example, when an exclusive gateway evaluates conditions to determine which path to follow.

In addition, the RuntimeService allows developers to:

  • Start new process instances.

  • Query active process instances and executions.

  • Manage executions, which represent the BPMN 2.0 “token” concept — i.e., the current position of the process instance.

  • Handle wait states by signaling process instances when external triggers occur, allowing the process to continue.


Tasks assigned to human users are a core part of OrqueIO’s process engine. All functionality related to human tasks is grouped in the TaskService.

With the TaskService, you can:

  • Query tasks assigned to specific users or groups.

  • Create standalone tasks that are not bound to any process instance.

  • Reassign tasks or manage task involvement by different users.

  • Claim and complete tasks:

    • Claim: a user takes responsibility for a task by becoming its assignee.

    • Complete: the user performs the work, typically by submitting a form or providing input required by the process.

This separation between RuntimeService (for process execution) and TaskService (for human interaction) ensures a clear distinction between automated flows and user-driven activities.

The IdentityService is responsible for managing users and groups. It provides operations to create, update, delete, and query identity data.

Important: the OrqueIO engine itself does not enforce user validation at runtime. For example, a task may be assigned to any username, even if it does not exist in the system. This flexibility allows seamless integration with external identity providers such as LDAP, Active Directory, or custom IAM solutions.


he FormService is an optional service. OrqueIO runs fully without it, without any loss of process execution functionality.

The service introduces two concepts:

  • Start Form → a form shown before a process instance begins.

  • Task Form → a form shown when a user interacts with or completes a task.

Forms can be defined directly in the BPMN 2.0 process model. The FormService simply exposes this form data for easy consumption. However, embedding forms in process definitions remains optional.


The HistoryService provides access to all historical data recorded by the engine. Depending on configuration, OrqueIO can store information such as:

  • When process instances started and ended.

  • Which users performed which tasks.

  • How long tasks and processes took to complete.

  • Which execution paths were taken during a process.

The service primarily offers query operations to retrieve and analyze this historical data.


The ManagementService is rarely required in custom application development. It provides low-level administrative operations, such as:

  • Retrieving database table metadata.

  • Querying and managing jobs.

Jobs are used internally by the engine for timers, asynchronous continuations, scheduled suspensions/activations, and more. Advanced usage of jobs is covered in later sections.


The FilterService allows creation and management of stored queries. A filter is essentially a saved query that can be reused, such as task filters in the Tasklist. This enables personalized task views for users and groups.


The ExternalTaskService manages external tasks, which represent work items handled outside the process engine. This approach decouples the execution of certain activities, allowing external workers to fetch, lock, and complete tasks independently.


The CaseService is similar to the RuntimeService but dedicated to case management.

It allows you to:

  • Start and manage case instances based on case definitions.

  • Control the lifecycle of case executions.

  • Retrieve and update case-specific variables.

This service is key when working with CMMN (Case Management Model and Notation).


The DecisionService enables the evaluation of decision tables and DMN models deployed in the engine.

It can be used in two ways:

  • Direct evaluation of decisions through the API.

  • Indirect evaluation when a decision is invoked via a BPMN business rule task.

This makes decision logic reusable and independent from process models.


Query API

OrqueIO provides several ways to query data from the engine, depending on your needs:

  • Java Query API → A fluent, type-safe Java API to query engine entities (e.g., ProcessInstances, Tasks, …).

  • REST Query API → REST endpoints for querying engine entities over HTTP.

  • Native Queries → Write custom SQL-based queries when the Query API is not sufficient (for example, OR conditions).

  • Custom Queries → Define fully customized queries using MyBatis mappings, enabling joins between engine data and domain-specific data.

  • Direct SQL Queries → Access the database directly for use cases such as reporting or analytics.


The Java Query API allows developers to build type-safe queries with a fluent API. You can combine multiple conditions (all combined with a logical AND) and specify exactly one ordering.

For example, the following query retrieves all tasks assigned to user "kermit", where the process variable orderId equals "0815", ordered by due date in ascending order:

List<Task> tasks = taskService.createTaskQuery()
  .taskAssignee("kermit")
  .processVariableValueEquals("orderId", "0815")
  .orderByDueDate().asc()
  .list();
  • Query Maximum Results Limit
    When running queries in OrqueIO, it is important to avoid fetching an unbounded number of results. Unrestricted queries can cause high memory consumption or even lead to OutOfMemoryExceptions.

    To prevent this, OrqueIO provides a Query Maximum Results Limit, which restricts the number of results returned.


The restriction applies in the following scenarios:

  • An authenticated user executes a query.

  • A query is executed directly via the Query API (e.g., REST API calls).

  • It is not enforced inside process execution logic (such as delegation code).


  • Forbidden Operations
    The following operations are blocked when they exceed the configured maximum results limit:

    • Performing a query with an unbounded number of results using the #list() method.

    • Performing a paginated query that exceeds the maximum results limit.

    • Running a query-based synchronous operation that affects more instances than the maximum results limit.


  • Allowed Operations
    The following are always allowed:

    • Performing a query using Query#unlimitedList.

    • Performing a paginated query with a number of results ≤ maximum limit.

    • Executing native queries, since they are not accessible via REST API or Webapps, and are less prone to exploitation.


  • Limitations
    The maximum results restriction is not enforced in the following cases:

    • Statistics queries via REST API.

    • Called instance queries via Webapps (private API).


  • Custom Identity Service Queries
    When implementing a custom identity integration in OrqueIO, you may provide:

    • A custom identity provider by implementing the ReadOnlyIdentityProvider or WritableIdentityProvider interface.

    • A dedicated implementation of Identity Service Queries (e.g., GroupQuery, TenantQuery, UserQuery).

      In such cases, it is crucial to ensure that Query#unlimitedList always returns all results without restriction.

      This behavior is required because some OrqueIO REST API endpoints depend on retrieving unlimited results. Failing to support this could cause inconsistencies or missing data in endpoints that rely on unrestricted identity queries.


  • Paginated Queries
    Pagination in OrqueIO queries allows you to define:

    • the maximum number of results to retrieve, and

    • the index of the first result to return.

This makes it possible to efficiently work with large datasets by fetching results in smaller, controlled batches.

Example
List<Task> tasks = taskService.createTaskQuery()
  .taskAssignee("kermit")
  .processVariableValueEquals("orderId", "0815")
  .orderByDueDate().asc()
  .listPage(20, 50);

In this example, the query retrieves 50 results, starting from the result at index 20.


  • OR Queries
    By default, the OrqueIO Query API combines filter criteria using a logical AND expression. With OR queries, you can build queries where filter criteria are combined using a logical OR.

    • OR queries are only supported for task queries and process instance queries** (runtime & history).

    • The following methods are not supported** in OR queries: orderBy…​(), initializeFormKeys(), withCandidateGroups(), withoutCandidateGroups(), withCandidateUsers(), withoutCandidateUsers(), incidentIdIn().

After invoking or(), you can chain multiple filter criteria, each of which will be combined with OR. The invocation of endOr() marks the end of the OR block.

This mechanism works like grouping conditions with brackets in a SQL query.

List<Task> tasks = taskService.createTaskQuery()
  .taskAssignee("John Munda")
  .or()
    .taskName("Approve Invoice")
    .taskPriority(5)
  .endOr()
  .list();

The query above retrieves all tasks that are assigned to "John Munda" and either:

  • Named "Approve Invoice" or

  • Have a priority of 5

In logical terms: (assignee = "John Munda" AND (name = "Approve Invoice" OR priority = 5) (Conjunctive Normal Form)

Internally, OrqueIO translates this query to a SQL statement (simplified):

SELECT DISTINCT *
FROM   act_ru_task RES
WHERE  RES.assignee_ = 'John Munda'
       AND ( Upper(RES.name_) = Upper('Approve Invoice')
             OR RES.priority_ = 5 );

OrqueIO allows you to use multiple OR blocks within a single query.
When a query contains both OR blocks and other filter criteria linked via AND, each OR block is automatically appended to the existing criteria chain with a leading AND.
This ensures that the logical grouping of conditions is preserved, producing the correct results while combining AND and OR expressions.

In OrqueIO, variable-related filter criteria can be applied multiple times within the same OR block.

List<Task> tasks = taskService.createTaskQuery()
  .or()
    .processVariableValueEquals("orderId", "0815")
    .processVariableValueEquals("orderId", "4711")
    .processVariableValueEquals("orderId", "4712")
  .endOr()
  .list();

For non-variable filter criteria, the behavior differs from variable-related criteria. If the same non-variable filter criterion is applied multiple times within an OR query, only the last value provided is used.
This ensures that the query considers a single effective value per non-variable criterion.

List<Task> tasks = taskService.createTaskQuery()
  .or()
    .taskCandidateGroup("sales")
    .taskCandidateGroup("controlling")
  .endOr()
  .list();

In the previous example, the value "sales" for the filter criterion taskCandidateGroup is replaced by "controlling".

To retain multiple values for a single criterion, use the …In variants of filter methods, such as:

  • taskCandidateGroupIn()

  • tenantIdIn()

  • processDefinitionKeyIn()

These methods allow specifying multiple values for a single filter criterion in a query.

  • REST Query API
    The OrqueIO Java Query API is also exposed via REST. For detailed information on the available endpoints and usage, refer to the OrqueIO REST API documentation.


  • Native Queries
    For more advanced query requirements, such as using OR operators or other restrictions not supported by the standard Query API, OrqueIO provides native queries.

    Native queries allow you to write custom SQL queries directly against the database. The results are mapped into the appropriate objects, such as Task, ProcessInstance, Execution, etc., based on the Query object used.

    Since native queries access the database directly, you must use the actual table and column names as defined in the database schema.

    Using native queries requires some understanding of OrqueIO’s internal data structure. It is recommended to use them carefully.

    + Table names and schema details can be retrieved via the OrqueIO API to minimize direct dependency on the database structure.

    List<Task> tasks = taskService.createNativeTaskQuery()
      .sql("SELECT * FROM " + managementService.getTableName(Task.class) + " T WHERE T.NAME_ = #{taskName}")
      .parameter("taskName", "aOpenTask")
      .list();
    
    long count = taskService.createNativeTaskQuery()
      .sql("SELECT count(*) FROM " + managementService.getTableName(Task.class) + " T1, "
             + managementService.getTableName(VariableInstanceEntity.class) + " V1 WHERE V1.TASK_ID_ = T1.ID_")
      .count();
  • Custom Queries
    For performance optimization, it can be useful to query custom value objects or DTOs instead of the standard OrqueIO engine entities.

    This approach allows you to collect data from multiple tables, and even include your own domain classes, reducing the overhead of fetching full engine objects when only specific data is needed.

  • SQL Queries
    The database schema in OrqueIO is designed to be straightforward and easy to understand.
    It is perfectly fine to run SQL queries directly for use cases such as reporting.

    However, be very careful not to modify engine tables unless you are fully aware of the internal structure and implications. Direct updates to engine tables without proper knowledge can corrupt the system data.

5. Examples

Finished the Getting Started Guides? Discover what you can create with OrqueIO.

This page gathers links to practical, hands-on examples:

  • Examples (on GitHub) – A collection of OrqueIO example projects on GitHub