ZeeQS - Zeebe Query Service

A Zeebe community extension that provides a GraphQL query API over Zeebe's data. The data is imported from the broker using the Hazelcast exporter and aggregated in the service.

🚀 Install

Docker

The docker image is published to GitHub Packages .

Run the following command to start the application:

docker run -p 9000:9000 ghcr.io/camunda-community-hub/zeeqs:latest

• Ensure that a Zeebe broker is running with a Hazelcast exporter
• Forward the Hazelcast port to the docker container (default: 5701)
• Configure the connection to Hazelcast (default: localhost:5701)
  • ZEEBE_CLIENT_WORKER_HAZELCAST_CONNECTION (environment variable)
  • zeebe.client.worker.hazelcast.connection (application.yaml)

Or, if you run it on your local machine (Linux only):

docker run --network="host" ghcr.io/camunda-community-hub/zeeqs:latest

After the application is started, the GraphQL endpoint is available under http://localhost:9000/graphql.

Go to http://localhost:9000/graphiql and explore the GraphQL API using GraphiQL.

Docker Compose

For a local setup, the repository contains a docker-compose file. It contains multiple profiles for different configurations.

Use an in-memory database (H2):

docker-compose --profile in-memory up

Use a PostgreSQL database:

docker-compose --profile postgres up

After the application is started, the GraphQL endpoint is available under http://localhost:9000/graphql.

Go to http://localhost:9000/graphiql and explore the GraphQL API using GraphiQL.

Configuration

By default, the API endpoint is available under the port 9000. And the database is only in-memory (i.e. not persistent).

To configure the application, look at the application.yml and the docker-compose file. See here on how to configure a Spring Boot application in general.

✨ Usage

The application provides a GraphQL endpoint under /graphql.

You can query the API via HTTP POST request and a JSON body containing the query.

For example:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{ "query": "{ processes { nodes { key } } }" }' \
  http://localhost:9000/graphql

The best way to explore and inspect the GraphQL API is to use the integrated web-based tool GraphiQL. It is available under http://localhost:9000/graphiql.

Queries

The GraphQL API provides the following queries:

• processes
• processInstances
• jobs
• userTasks
• messages
• incidents
• decisions
• decisionEvaluations
• errors

Example query

Query all processes including their number of process instances:

{
    processes {
        totalCount
        nodes {
            key
            bpmnProcessId
            version
            processInstances {
                totalCount
            }
        }
    }
}

Response:

{
  "data": {
    "processes": {
      "totalCount": 3,
      "nodes": [
        {
          "key": "2251799813685249",
          "bpmnProcessId": "demo-process",
          "version": 1,
          "processInstances": {
            "totalCount": 3
          }
        },
        {
          "key": "2251799813685251",
          "bpmnProcessId": "demo-2",
          "version": 1,
          "processInstances": {
            "totalCount": 2
          }
        },
        {
          "key": "2251799813685269",
          "bpmnProcessId": "demo-3",
          "version": 1,
          "processInstances": {
            "totalCount": 1
          }
        }
      ]
    }
  }
}

Pagination

In order to limit the response size and the query processing, each list query uses pagination to return only a subset of the data. By default, it returns the first 10 items of the list.

In addition to the items, the query result contains also the total count of the items.

{
    processes(perPage: 10, page: 0) {
        totalCount
        nodes {
            key
        }
    }
}

Filters

Some queries allow to filter the result by passing arguments in the query.

{
    processInstances(stateIn: [ACTIVATED]) {
        nodes {
            key
        }
    }
}

Subscriptions

The GraphQL API provides the following subscriptions:

• processUpdates
• processInstanceUpdates
• decisionUpdates
• decisionEvaluationUpdates

The subscriptions are exposed via WebSockets over the same endpoint /graphql.

Example subscription

Subscribe to any updates of process instances:

subscription {
    processInstanceUpdates {
        processInstance {
            key
            state
        }
        updateType
    }
}

Response:

{
  "data": {
    "processInstanceUpdates": {
      "processInstance": {
        "key": "2251799813685251",
        "state": "ACTIVATED"
      },
      "updateType": "ELEMENT_INSTANCE"
    }
  }
}

Build from Source

Build with Maven

mvn clean install

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Read more about the Camunda Community Code of Conduct and how to report unacceptable behavior.

License

Apache License, Version 2.0