Open Proces Huis (microservices stack)

This repo holds the docker compose and all configuration files necessary to get Open Proces Huis running. It was started using the mu-project template and has since been heavily expanded.

Open Proces Huis is one of many applications developed under the Agentschap Binnenlands Bestuur (ABB), which is part of the Flemish Government. It allows for lokale besturen to create and share processes. Such process is created by uploading a BPMN file, which is subsequently stored by the file-service, as well as processed by the bpmn-service. The latter was developed as part of Open Proces Huis and essentially extracts the BPMN elements from a given BPMN file and stores them as triples in the Virtuoso triplestore. To make all functionalities available as a web application, a frontend was also developed.

In addition to the aforementioned services, a range of others are also essential to the stack. All of them are listed in this overview, and can of course also be found in docker-compose.yml.

Getting started

First run

1. Clone this repository

git clone https://github.com/lblod/app-openproceshuis.git

2. Run the project

cd /path/to/project

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

3. Wait for the op-consumer to finish initial ingest

docker compose logs -f op-consumer

When the logs show delta-sync-queue: Remaining number of tasks 0, you can move on.

4. In your browser, go to localhost:8890/sparql and run the SPARQL query found in manual-query-reasoning-service.sparql.

Usage

• You can access the frontend in your browser by going to localhost.
• You can log in using a mock account by going to localhost/mock-login.
• You can shut everything down by running docker compose down.
• When restarting the project not having emptied the data/ folder, you can ignore steps 3 and 4 under First run.
• You can empty the database and file storage by running sudo rm -rf data/ (restarting the project will require steps 3 and 4 under First run).

Data domain

All data is stored as triples in the Virtuoso triplestore. However, the default way of accessing this data, is by using the REST API provided by the mu-migrations-service. This service acts based on domain.lisp, which stipulates how the API classes should be mapped to the resources from the triplestore. What follows, is a visualization of the domain made up of the different API classes, alonside the underlying RDF triples as can be found in the triplestore.

The prefixes used in the diagram are equivalent to the ones used throughout the project. Their definitions can be found in repository.lisp.

The definition of Group can be found in auth.json, alongside all other classes that are necessary for user management (not visible in the diagram).

The BpmnElement class is in fact only an interface for all true BPMN element classes available. These are mapped onto RDF resources that comply with the BPMN Based Ontology (BBO).

Dispatching

Different services from the stack handle different HTTP requests. The mu-dispatcher service makes sure each request gets dispatched to the correct service. The exact dispatching rules are described in dispatcher.ex.

Overview of services

• frontend-openproceshuis
• mu-identifier
• mu-dispatcher
• mu-authorization
• virtuoso
• mu-migrations-service
• mu-cl-resources
• mu-cache
• delta-notifier
• file-service
• bpmn-service
• account-detail-service
• delta-consumer
• reasoning-service
• acmidm-login-service