ISPF-Dokumentation

1. Funktionale Merkmale

Who This Product Is For

What ISPF Solves

A typical SCADA/MES stack grows as separate modules: OPC server, historian, HMI, workflow, reports. ISPF unifies them around one object tree with a single API and UI.

Diagram (Mermaid) — see full docs on GitHub.

Core principle

Business logic lives on the platform — in models, variables, events, functions, and workflows of the object tree. The platform supplies generic engines (CEL, bindings, BPMN, script runtime, drivers); the solution configures them declaratively. Bundle deploy packages configuration, not a separate runtime. Summary for developers and agents: application-principles. Details: architecture. Backlog: roadmap.

Key capabilities

• - Unified model — device, dashboard, workflow, and alert rule are tree nodes; logic uses variables, events, functions, and BPMN.
• - Bundles, not core forks — industry solutions deploy as configuration into platform mechanisms (applications).
• - Stack — Spring Boot 4, Java 25, PostgreSQL/TimescaleDB, React 19, REST + WebSocket; optional NATS/MQTT/Keycloak.
• - ~60 driver packs (not inside ispf-server.jar; maturity varies — see drivers).
• - AGPL v3 platform — optional Enterprise dual-license; driver packs and application bundles may use separate terms (license, plugins).

Product Capabilities

1. Object tree

The central platform abstraction. Each node has a path (root.platform.devices.pump-01), type, variables, events, and functions.

Details: object-model, glossary.

2. Models (templates)

BlueprintDefinition describes a set of variables, events, functions, and CEL bindings. MIXINs auto-apply only when a non-empty Applicability condition (CEL) is set. The demo blueprint mqtt-sensor-v1 is a fixture applied via templateId.

Details: blueprints, 0018-fixture-models-and-cel-applicability.

3. Device drivers

The DeviceDriver SPI connects protocols to object variables. The administrator configures driverId, configuration, and point mapping; the runtime polls the device and writes values into the tree.

Demo after first startup:

Details: drivers.

4. Dashboards and HMI

Dashboard Builder (admin) and Operator HMI (read-only) use the same widgets:

Widgets bind to data via objectPath (static) or selectionKey (dynamic row selection from a table).

Details: dashboards, scada, widget reference: widgets.

5. Workflow (BPMN)

Visual BPMN editor in the Web Console. Supports service tasks (including application function calls), user tasks (operator queue), gateways with CEL conditions, parallel branches, signals, and NATS.

Details: workflows.

2. Installation

Try ISPF (≈15 minutes)

Option A — all-in-one JAR (fastest)

Download ispf-*-portable.zip from GitHub Releases (JDK 25). Unzip, then:

# Windows: double-click start.bat
# Linux / macOS:
./start.sh

No PostgreSQL needed — the portable build uses embedded H2 (data/ispf-local.mv.db after first start).

Open http://localhost:8080 — login admin / admin. Then continue from §2 Sign in (use port 8080 instead of 5173).

Option B — from source

Requirements

1. Start API + console

# Terminal 1 — local profile (H2 file DB; syncs a small set of dev driver packs)
./gradlew :packages:ispf-server:bootRun --args="--spring.profiles.active=local"

# Terminal 2 — Web Console
cd apps/web-console && npm install && npm run dev

bootRun uses syncDevDriverPacks by default (≈8 packs). Full catalog: -Dispf.driver.packs=all.

2. Sign in (local profile)

Default empty DB seeds: admin / admin (also developer / developer, operator / operator). Use the Web Console login screen.

API (Bearer token — required for most calls):

TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r .token)

curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/objects

X-ISPF-Role header auth is off by default (ispf.security.local-role-header-enabled=false). Do not rely on a Role selector in the header for normal local use. Details: security.

3. First steps in the UI

1. 1. Open the object tree — branch root.platform.
2. 2. Expand devices → demo-sensor-01 — temperature, threshold, alarm variables.
3. 3. Double-click dashboards.demo-sensor — Dashboard Builder.
4. 4. Expand alert-rules → temperature-threshold-exceeded — CEL alert.
5. 5. Double-click workflows.demo-alarm-handler — BPMN demo.
6. 6. Open operator mode: http://localhost:8080?mode=operator (all-in-one JAR) or http://localhost:5173?mode=operator (Vite), or log in as operator.

Language: use the console language selector (English recommended for screenshots / OSS).

4. Start the demo sensor driver

curl -X POST "http://localhost:8080/api/v1/drivers/runtime/start?devicePath=root.platform.devices.demo-sensor-01" \
  -H "Authorization: Bearer $TOKEN"

Temperature is a sine wave; when the threshold is exceeded, alarmActive and the alert rule may fire.

Next after the demo

• - Product overview · Object model · Dashboards · Automation
• - Solution developer guide — build a real bundle
• - Architecture · API

3. Betrieb

Operator Guide

Guide for users with the operator role — equipment monitoring, work queue tasks, events, and reports.

Product overview: product. UI technical details: web-console.

Sign In

1. 1. Open the Web Console: http://<host>:8080 (all-in-one JAR) or http://<host>:5173 (Vite dev)
2. 2. Sign in with an operator account (demo: operator / operator).
3. 3. After sign-in, Operator HMI opens — full-screen mode without the object tree or editors.

If you have the admin role but need operator mode:

http://<host>:8080?mode=operator
http://<host>:5173?mode=operator

For a specific application:

http://<host>:8080?mode=operator&app=platform
http://<host>:5173?mode=operator&app=platform

Application auto-start

An administrator can configure auto-start for your account: after sign-in, the configured operator app opens immediately (for example, platform or an industry application).

Operator HMI

Left: dashboard (widgets, charts, tables). Right: Work Queue / event journal sidebar. Bottom-right: shift AI assistant (read-only).

What operators can do

Working with Dashboards

Navigating between screens

If the application has multiple dashboards, they appear as tabs at the top of the screen. Switch tabs to move between screens (for example, “Overview”, “Details”, “Reports”).

A dashboard-link widget on a screen can open another dashboard — in the current tab or in a modal.

On-screen widgets

Full reference for all widgets (what each setting does, examples): widgets.

On screens with a device table (object-table widget with selectionKey), clicking a row updates linked widgets — charts and indicators show data for the selected device.

Spreadsheet widget

The spreadsheet widget is a table with Excel-style cell addressing (A1, B2, …). Values and formulas recalculate on screen without server round-trips (except live binding cells).

Detailed instructions: spreadsheet-widget.

Summary:

Selection and input (free mode):

1. 1. Click a cell — select it; contents appear in the formula bar.
2. 2. Double-click or F2 — edit directly in the cell.
3. 3. Formula bar — enter a number (10), text, or formula (=A1+B2); Enter — save.
4. 4. Tab / Shift+Tab — next / previous cell; arrow keys — move in the grid.

Keyboard shortcuts (free mode, when focus is on the grid):

Persistence: entered values and formulas are saved automatically (dashboard session or object variable — as configured by the developer). After F5, data remains if the widget is bound to a variable (persistMode: variable).

Lab example: dashboard root.platform.dashboards.lab-calculator — template calculator (configured mode): only cells A2 and B2 are editable; sums recalculate automatically.

Dynamic object selection

On screens with a device table (object-table widget with selectionKey), clicking a row updates linked widgets — charts and indicators show data for the selected device.

Work Queue

The Work Queue holds BPMN user tasks assigned to operators.

Typical flow

1. 1. A workflow starts (manually by an administrator or triggered by an event).
2. 2. The process reaches a user task → the task appears in the Work Queue.
3. 3. Operator clicks Claim — the task is assigned to them.
4. 4. Operator performs the action (for example, confirms on the dashboard).
5. 5. Clicks Complete — the workflow continues.

Where to look

• - Sidebar on the right in Operator HMI — Work Queue panel.
• - work-queue widget on a dashboard — embedded queue on the screen.

If a task is unavailable

• - The task is already claimed by another operator — wait for completion or contact an administrator.
• - Workflow status is STOPPED — no new tasks are created.

Event Journal

The Event Journal sidebar shows recent platform events:

• - Sensor threshold exceeded
• - Alert rule fired
• - Manual event fire
• - System notifications

Levels: DEBUG, INFO, WARNING, ERROR, CRITICAL.

An event-log widget on a dashboard can filter events for a specific object.

4. Deployment (Prod / Docker)

Docker Compose

docker compose up -d

Volume: ispf_pg_data.

Compose profiles are not used — all services start together.

Spring Boot Server

Artifact: :packages:ispf-server:bootRun or JAR from build/libs/.

Environment variables

Profiles

Database

• - Flyway — migrations on startup (ddl-auto: validate); locations per RelationalDialect (see 0037-relational-core-portability)
• - local: H2 ./data/ispf-local (PostgreSQL compatibility mode)
• - prod: PostgreSQL; TimescaleDB extension (docker image timescale/timescaledb) — hypertables variable_samples and event_history, retention 90d (0009-timescaledb-retention, 0015-event-history-timescale)

Storage modes

Single DB is the standard scenario: configuration, objects, event_history, and variable_samples in one PostgreSQL. ClickHouse/Cassandra — only under high time-series load.

Optionally: ISPF_METADATA_DB_KIND (postgresql, h2, mssql, …) — see storage-portability-inventory.

Changing metadata engine (greenfield, before v1.0): new empty DB, Flyway baseline for the chosen dialect, configuration — import bundles. In-place PG→MSSQL migration is not supported.

Platform Data Sources (root.platform.data-sources.*): internal — schema in ISPF_DB; external — JDBC to external DB for reports and SQL bindings (not metadata).

Messaging

Production quick start (BL-127)

One command brings up the lab / localhost stack on a Linux host with Docker (PostgreSQL + Redis + ispf-server + nginx for UI). Not tied to VPS ispf.example.invalid.

Not for internet-facing production without hardening: ports are bound to 127.0.0.1, demo fixtures are disabled, default DB passwords (ispf/ispf) must be changed before exposing to the network. Images use pinned tags from deploy/air-gap-images.env. Full prod checklist: demostands.md § Production.

Requirements: Docker Engine + Compose v2, JDK 25 (for build), Node.js 20+ (for UI).

bash deploy/prod-quickstart.sh

The script:

1. 1. Builds ispf-server JAR (bootJar, no tests).
2. 2. Builds apps/web-console (npm ci && npm run build).
3. 3. Copies JAR to deploy/staging/ispf-server.jar.
4. 4. Starts deploy/docker-compose.prod-stack.yml.
5. 5. Waits for readiness via deploy/health-check.sh.

Stop:

docker compose -f deploy/docker-compose.prod-stack.yml down

PostgreSQL volumes are preserved (ispf_prod_pg). Full cleanup: add -v.

Files:

Prod VPS: for ispf.example.invalid, continue to use deploy/vps-deploy-direct.ps1 (direct SCP + staging), not this quick start.

Kubernetes Helm chart (BL-186)

Chart: deploy/helm/ispf. Installable with Helm 3.14+; lint/template smoke needs no cluster.

# Static smoke (local helm or Docker alpine/helm)
bash deploy/helm/ispf/validate.sh

# Install
helm upgrade --install ispf deploy/helm/ispf \
  --namespace ispf --create-namespace \
  --set secrets.dbPassword='change-me' \
  --set ispf.bootstrap.fixturesEnabled=false

# Runtime smoke
kubectl -n ispf rollout status deploy/ispf --timeout=180s
kubectl -n ispf port-forward svc/ispf 8080:80 &
curl -sf http://127.0.0.1:8080/actuator/health
curl -sf http://127.0.0.1:8080/api/v1/info

ARM edge on K8s: set edge.enabled=true / edge.arm64=true (see edge/arm64). Compose profile for Pi/gateways: BL-187.

5. Vollständige Dokumentation auf GitHub