OCPQ (Object-Centric Process Querying)

Download

Installation

You can download the automatically cross-compiled installers for the latest release from github.com/aarkue/ocedeclare/releases/latest.

The following installer formats are available:

• [...].AppImage for Linux (Recommended for Linux)
• [...]-setup.exe for Windows (Recommended for Windows)
• [...].dmg for macOS (Recommended for macOS)
• [...].deb for Linux (Debian)
• [...].msi for Windows
• [...].app.tar.gz for macOS

Note, that sometimes Windows Defender might erroneously detect a (false-positive) thread in the installers. See also tauri-apps/tauri#2486. In this case, please either try a different installer variant (e.g., .exe instead of .msi) or use the alternative use Docker as described below.

Docker

Alternatively, you can also easily build and run the project locally using Docker. This will start a local web server for the backend and the frontend. Once the container is running, you can open http://localhost:4567/ in your browser for the tool frontend.

Docker Compose

Run docker compose up --build in the project root.

Alternatively, the docker files can of the frontend and backend can also be used separately:

Docker Files

• backend:
  1. First build using sudo docker build ./backend -t ocedeclare-backend
  2. Then run with docker run --init -p 3000:3000 ocedeclare-backend
• frontend:
  1. First build using sudo docker build ./frontend -t ocedeclare-frontend
  2. Then run with sudo docker run --init -p 4567:4567 ocedeclare-backend

Usage

Loading OCELs

In the following examples, we use the order management OCEL from https://zenodo.org/records/8428112. JSON, XML, and SQLite OCEL 2.0 files are supported.

Constraint Overview

Constraint Editor

Adding Nodes

A new node can be added using the button on the top right of the editor.

Adding object and event variables

Inside the newly created node, object and event variables, as well as filter predicates can be added using the corresponding +-buttons inside the node. In this example, we first create an object variable o1 with the object type orders. The variable name (1) and type (2) can be selected from a list of available values and the new variable added using the button (3).

Similarly, we also add an event variable e1 of type confirm order.

The updated node then looks as shown below, indicating the added variables and their types.

Adding Filter Predicates

Next, we want to add a predicate statement linking o1 and e1. For that, we add a new filter predicate using the +-button shown besides the filters. Then, the filter type (E2O: Event-To-Object Relationship) can be selected (1), and the corresponding parameters (2), (3) and (4) can be configured. Parameter (4) can optionally be used to only consider a specific relationship qualifier, but can also be left unspecified.

Finally, using the Add button (5) the filter predicate is added to the node, which then looks as shown below.

Evaluating Queries and Constraints

Constructed constraints and queries can be evaluated using the play button at the top right (1). After the evaluation finishes, the evaluation results are shown directly inside the editor at the corresponding nodes (2). For instance, the query constructed so far yields 2000 results (i.e., 2000 output bindings). As there are no constraint predicates for the node, no violation percentage is shown.

Adding Child Nodes

Next, we add a child node by first creating a new node (using the corresponding button on the top right) and then connect both nodes using the connection handles on the nodes (1) and (2).

Clicking on the - button of the connection edge allows assigning a name to this edge. In this example, we name the edge A. Additionally, we add an event variable and a filter predicate to this newly created node, such that it looks like shown below.

Adding Constraints

Using this added child node, we want to specify a constraint regarding the number of child bindings (i.e., the number of pay order events for the confirmed order o1). This can be done by first clicking the + button next to the constraints of the top / parent node and then selecting the CBS: Child Bindings Set Size constraint type, and configuring the associated parameters (specifying the edge name A as well as the min and max count, both 1 in this example).

After adding this constraint and evaluating it (again using the play button on the top right), we can see that this constraint is satisfied for all bindings (i.e, a violation percentage of 0% is shown, and the node is colored in bright green).

Finally, we want to make this constraint a little more interesting. In particular, we want to specify that the pay order event should occur within 2 weeks after the confirm order event. For this, we add a filter predicate to the child node, such that it only queries pay order events within this timeframe.

Evaluating this updated constraint again yields a violation percentage of 29.3%.

An alternative way to model this constraint in this specific setting would be adding this time between event predicate as a constraint to the child node. Note, that this constraint might be slightly different in general, as it simply requires that all pay order events fulfill this constraint. In this case the constraint can also be modeled using just one node, as shown below.

Organizing and Saving Constraints

Each constraint can have a name and description, which can be modified using the inputs (1) and (2) when the constraint is selected. Multiple constraints can be added an accessed using the list on the top right. Note, that by default constraint are not saved and will not be there after reloading or reopening the tool. The constraints however can easily be saved locally by clicking on the save button on the top right of the tool. Thus, make sure to press the save button whenever you created or updated a constraint and want to save it.

Automatically Discovering Constraints

Constraints can also automatically be discovered using the Auto-Discovery button. You can configure the different types of constraints to discover, as well as the object types for which to discover constraints.

The discovered Constraints are automatically added to the list of constraints and can be manually edited or deleted.

Development

We use cargo and npm, so please ensure they are available by installing them (i.e., Rust and Node). Then, install all dependencies (e.g., using npm i inside the frontend folder)

For the full-stack web application navigate to the backend folder and run cargo run --release to start the backend and navigate to the frontend folder and execute npm run dev to start the frontend. By default, the backend server is available at http://localhost:3000 while the frontend is available at http://localhost:5173/.

For the desktop application, tauri (https://tauri.app/) is used. To run the desktop application, simply run npm run tauri dev -- --release inside the tauri folder.

Currently, there are few unnecessary warning messages in the output when running or building the frontend with vite. These are because we include an offline version of the monaco editor for easily writing CEL scripts. Optionally, an online version of the editor can be used instead (by removing or updating initEditorLoader in editor-loader.ts), however then an internet connection is required for using the editor.