Skip to content

Monitor App

The Monitor App is a built-in web interface for interacting with the workflow engine during development. It provides a real-time view of workflow definitions, executions, jobs, and registered workers.

Integration roadmap

The Monitor App is currently a standalone development tool. Its functionality will be integrated into the neops Web Client in a future release. For now, it is the primary UI for workflow management and execution monitoring.

What You Can Do

  • Browse workflow definitions -- See all registered workflows with their versions, steps, and schemas
  • Trigger executions -- Execute workflows with custom parameters and entity scopes
  • Monitor executions -- Watch execution state transitions in real time (NEW → RUNNING → COMPLETED)
  • Inspect jobs -- See which jobs are pending, polled, or completed, and which worker handled each job
  • View workers -- See online workers and their registered function blocks

Quick Start

=== "Docker Compose (recommended)"

Follow the [Quick Start](../getting-started/10-setup.md#quick-start-with-docker-compose) to
start PostgreSQL, the Monitor App, and the engine. Then open
[http://localhost:5173](http://localhost:5173) in your browser.

=== "Local development"

1. Ensure the workflow engine is running (see [Setup](../getting-started/10-setup.md))
2. Start the Monitor App:

    ```bash
    make run-monitor
    ```

    Or directly:

    ```bash
    cd rest/monitor-app && npm run dev
    ```

3. Open [http://localhost:5173](http://localhost:5173) in your browser

Key Screens

Workflow Definitions

Lists all registered workflow definitions. From here you can:

  • View the full YAML definition of each workflow
  • See the version history
  • Deploy new workflow definitions
  • Trigger an execution directly

Executions

The execution view shows all workflow executions with their current state. Click an execution to see:

  • The current state in the lifecycle (with color coding)
  • Individual jobs and their status per device
  • Step-by-step progress
  • Error details for failed steps
  • DB updates that will be applied

Workers

Shows all registered workers with their status (online, unreachable, offline) and which function blocks each worker provides. Useful for debugging when jobs are not being picked up.

Importing Workflows

The Monitor App accepts workflow definitions in JSON format. Since we recommend authoring workflows in YAML for readability, convert before importing:

yq -o=json my-workflow.workflow.yaml > my-workflow.workflow.json

Paste the raw workflow JSON into the Monitor App's definition editor — the app handles the API wrapping automatically.

Quick conversion alternatives

  • yq (recommended): yq -o=json < workflow.yaml -- install via brew install yq or see github.com/mikefarah/yq
  • Online: json2yaml.com converts both directions
  • Python: python -c "import yaml, json, sys; json.dump(yaml.safe_load(sys.stdin), sys.stdout, indent=2)" < workflow.yaml
Technology

The Monitor App is built with Svelte and communicates with the engine via browser-side HTTP requests to the REST API (defaulting to http://localhost:3030, configurable in the app's Settings page). When started via Docker Compose, it runs as a static production build served by nginx. For local development (make run-monitor), it runs as a Vite dev server with hot-reload.

Next: Your First Workflow -- deploy and execute a workflow end to end.