{"id":16489854,"url":"https://github.com/aarkue/ocpq","last_synced_at":"2025-06-29T04:38:09.992Z","repository":{"id":254311898,"uuid":"717758289","full_name":"aarkue/OCPQ","owner":"aarkue","description":"OCPQ - Object-Centric Process Querying","archived":false,"fork":false,"pushed_at":"2025-01-23T16:27:41.000Z","size":4687,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-23T17:30:01.895Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ocpq.aarkue.eu/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aarkue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-12T13:58:26.000Z","updated_at":"2025-01-23T16:27:44.000Z","dependencies_parsed_at":"2024-09-11T22:54:33.386Z","dependency_job_id":"8c7abb6c-3f63-47ef-b088-3ee1acb3a502","html_url":"https://github.com/aarkue/OCPQ","commit_stats":null,"previous_names":["aarkue/ocedeclare","aarkue/ocpq"],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarkue%2FOCPQ","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarkue%2FOCPQ/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarkue%2FOCPQ/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarkue%2FOCPQ/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aarkue","download_url":"https://codeload.github.com/aarkue/OCPQ/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241316389,"owners_count":19943060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T13:45:38.410Z","updated_at":"2025-06-29T04:38:09.985Z","avatar_url":"https://github.com/aarkue.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OCPQ (Object-Centric Process Querying)\n[__Download__](https://github.com/aarkue/ocpq/releases/latest)\n\n\n## Installation\nYou can download the automatically cross-compiled installers for the latest release from [__github.com/aarkue/ocpq/releases/latest__](https://github.com/aarkue/ocpq/releases/latest).\n\nThe following installer formats are available:\n- `[...].AppImage` for Linux (__Recommended for Linux__)\n- `[...]-setup.exe` for Windows (__Recommended for Windows__)\n- `[...].dmg` for macOS (__Recommended for macOS__)\n- `[...].deb` for Linux (Debian)\n- `[...].msi` for Windows\n- `[...].app.tar.gz` for macOS\n\nNote, that sometimes Windows Defender might erroneously detect a (false-positive) thread in the installers.\nSee also https://github.com/tauri-apps/tauri/issues/2486.\nIn this case, please either try a different installer variant (e.g., `.exe` instead of `.msi`) or use the alternative use Docker as described below. \n\n### Docker\n\nAlternatively, you can also easily build and run the project locally using Docker.\nThis will start a local web server for the backend and the frontend.\nOnce the container is running, you can open [http://localhost:4567/](http://localhost:4567/) in your browser for the tool frontend.\n\n#### Docker Compose\nRun `docker compose up --build` in the project root.\n\nAlternatively, the docker files can of the frontend and backend can also be used separately:\n\n#### Docker Files\n\n- __backend__:\n  1. First build using `sudo docker build ./backend -t ocpq-backend`\n  2. Then run with `docker run --init -p 3000:3000 ocpq-backend`\n- __frontend__:\n  1. First build using `sudo docker build ./frontend -t ocpq-frontend`\n  2. Then run with `sudo docker run --init -p 4567:4567 ocpq-backend`\n\n\n## Usage\n\n### Loading OCELs\n![image](https://github.com/user-attachments/assets/98210a69-cd3d-4c75-a2c5-0ee5f2e44d94)\n\nIn the following examples, we use the order management OCEL from https://zenodo.org/records/8428112.\nJSON, XML, and SQLite OCEL 2.0 files are supported.\n\n### Constraint Overview\n![image](https://github.com/user-attachments/assets/1604911e-e06e-4099-bcb8-628d89b2a4bd)\n\n### Constraint Editor\n#### Adding Nodes\nA new node can be added using the button on the top right of the editor.\n![image](https://github.com/user-attachments/assets/a1d19f6a-2bf0-4a9d-85aa-f65db7e35f8c)\n\n### Adding object and event variables\nInside the newly created node, object and event variables, as well as filter predicates can be added using the corresponding `+`-buttons inside the node.\nIn this example, we first create an object variable `o1` with the object type `orders`.\nThe variable name (1) and type (2) can be selected from a list of available values and the new variable added using the button (3).\n\n![image](https://github.com/user-attachments/assets/05106376-8094-44d3-bc1a-0dc5dbd4c152)\n![image](https://github.com/user-attachments/assets/336d7bd3-c986-4f4e-a714-c2af0696b3fe)\n\nSimilarly, we also add an event variable `e1` of type `confirm order`.\n\n![image](https://github.com/user-attachments/assets/b7b5286e-3b65-4318-827b-91204964b4eb)\n![image](https://github.com/user-attachments/assets/6f46c0f5-c9a4-4904-aadc-52c0afa32ea4)\n\nThe updated node then looks as shown below, indicating the added variables and their types.\n\n![image](https://github.com/user-attachments/assets/268fefb5-1a55-4e43-9ac3-7c47e7317557)\n\n### Adding Filter Predicates\n\nNext, we want to add a predicate statement linking `o1` and `e1`.\nFor that, we add a new filter predicate using the `+`-button shown besides the filters.\nThen, the filter type (_E2O: Event-To-Object Relationship_) can be selected (1), and the corresponding parameters (2), (3) and (4) can be configured.\nParameter (4) can optionally be used to only consider a specific relationship qualifier, but can also be left unspecified.\n\n![image](https://github.com/user-attachments/assets/298c732c-8076-40a6-b872-1ce5c4d25fef)\n\nFinally, using the _Add_ button (5) the filter predicate is added to the node, which then looks as shown below.\n\n![image](https://github.com/user-attachments/assets/9ca87d3c-2bb9-47c7-b628-3352bba0fa71)\n\n### Evaluating Queries and Constraints\n\nConstructed constraints and queries can be evaluated using the play button at the top right (1).\nAfter the evaluation finishes, the evaluation results are shown directly inside the editor at the corresponding nodes (2).\nFor instance, the query constructed so far yields 2000 results (i.e., 2000 output bindings).\nAs there are no constraint predicates for the node, no violation percentage is shown.\n\n\n![image](https://github.com/user-attachments/assets/9f311c29-a872-4860-80a8-90df679372df)\n\n### Adding Child Nodes\n\nNext, 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).\n\n![image](https://github.com/user-attachments/assets/14a714f5-920a-4e6a-aab1-147c2c7ebf92)\n\nClicking on the `-` button of the connection edge allows assigning a name to this edge. In this example, we name the edge `A`.\nAdditionally, we add an event variable and a filter predicate to this newly created node, such that it looks like shown below.\n\n![image](https://github.com/user-attachments/assets/74070713-259c-4c69-b03f-3b582108a2c6)\n\n### Adding Constraints\n\nUsing 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`).\nThis 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).\n\n![image](https://github.com/user-attachments/assets/3d4687a8-0285-4770-9822-1a009ab9a532)\n\n\n\nAfter 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).\n\n![image](https://github.com/user-attachments/assets/c615ea0f-9227-436d-95d6-cb0c2e2c3ecc)\n\n\nFinally, we want to make this constraint a little more interesting.\nIn particular, we want to specify that the `pay order` event should occur within 2 weeks after the `confirm order` event.\nFor this, we add a filter predicate to the child node, such that it only queries `pay order` events within this timeframe.\n\n![image](https://github.com/user-attachments/assets/6c392c92-6a80-46ef-8363-69ff1a2f2433)\n\nEvaluating this updated constraint again yields a violation percentage of 29.3%.\n\n![image](https://github.com/user-attachments/assets/21e46af5-676c-4fc3-8b02-8f0a98ef9035)\n\n\nAn 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.\nNote, that this constraint might be slightly different in general, as it simply requires that _all `pay order`_ events fulfill this constraint. \nIn this case the constraint can also be modeled using just one node, as shown below.\n\n![image](https://github.com/user-attachments/assets/d3753c87-a95f-4538-a001-b91fe791705b)\n\n### Organizing and Saving Constraints\nEach constraint can have a name and description, which can be modified using the inputs (1) and (2) when the constraint is selected.\nMultiple constraints can be added an accessed using the list on the top right.\nNote, that __by default constraint are not saved__ and will not be there after reloading or reopening the tool.\nThe constraints however can easily be saved locally by clicking on the save button on the top right of the tool.\nThus, __make sure to press the save button__ whenever you created or updated a constraint and want to save it.\n\n![image](https://github.com/user-attachments/assets/62b0f291-2236-41f4-bddb-8089a342c5ab)\n\n\n### Automatically Discovering Constraints\nConstraints can also automatically be discovered using the `Auto-Discovery` button.\nYou can configure the different types of constraints to discover, as well as the object types for which to discover constraints.\n\nThe discovered Constraints are automatically added to the list of constraints and can be manually edited or deleted.\n\n## Development\n\nWe use `cargo` and `npm`, so please ensure they are available by installing them (i.e., Rust and Node).\nThen, install all dependencies (e.g., using `npm i` inside the `frontend` folder)\n\nFor the full-stack web application navigate to the `backend/web-server` 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. \nBy default, the backend server is available at `http://localhost:3000` while the frontend is available at `http://localhost:5173/`.\n\n\nFor the desktop application, tauri (https://tauri.app/) is used.\nTo run the desktop application, simply run `npm run tauri dev -- --release` inside the `tauri` folder.\n\n\nCurrently, there are few unnecessary warning messages in the output when running or building the frontend with vite.\nThese are because we include an offline version of the monaco editor for easily writing CEL scripts.\nOptionally, 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.\n\n\n### Backend Context\n\nAs the tool supports multiple different backends (i.e., web server and tauri application), the exposed backend functionality is abstracted as a `BackendProvider`.\nThe typescript type `BackendProvider` in `frontend/src/BackendProviderContext.ts` specifies which functionality is available, and which parameters and return types are expected.\nThere are two implementations of that type: One for the web server backend (see `getAPIServerBackendProvider` in `frontend/src/BackendProviderContext.ts`), which makes fetch calls to the appropriate routes defined in `backend/web-server/src/main.rs` and another one for the tauri application backend (see `tauriBackend` in `tauri/src/main.tsx`), which calls the appropriate functions defined in `tauri/src-tauri/src/main.rs` via the invoke-method.\nThroughout the frontend, the backend can be used via an backend context instance (which can be acquired using `const backend = useContext(BackendProviderContext);`) and then be used for calling functionality (e.g., `backend['function_name'](parameters,...)`).\n\nTo add new functionality, first define a new backend call fields in the `BackendProvider` type. Next, create the actual, shared implementation of the feature in the shared backend files (e.g., in `backend/shared/src/lib.rs`). Next, define the appropriate functions to call this shared functionality in the two backends (web server and tauri), and finally add the new backend call field to the two `BackendProvider` implementations (see above for where they are located.)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faarkue%2Focpq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faarkue%2Focpq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faarkue%2Focpq/lists"}