Runtime Status

Runtime status is the live operational state of an asset — RUNNING, SETUP, IDLE, DOWN, MAINTENANCE. It's the single most-checked datapoint in the whole EMS suite: the Equipment Hub status board, work-center rollup, capacity calculation, and KPI all read from it.

This page covers how the value moves (operator entry, work-order operations, cron rollup), how it propagates (asset → WC → dashboard), and the permission tier designed specifically for floor operators.

The five states

The ordering matters because of the worst-of rollup. RUNTIME_STATUS_RANK in the codebase defines the severity:

DOWN(5) > MAINTENANCE(4) > SETUP(3) > IDLE(2) > RUNNING(1)

When a parent asset or work center rolls up the status of its critical descendants, it takes the highest rank — so a single DOWN child floors the whole rollup, while a SETUP-state child won't.

How status gets set

1. Operator action (Runtime Status Quick Menu)

The fastest path. Available wherever the asset chip appears:

• Equipment Hub status board — kebab menu on each chip
• Equipment Detail header — top-right action

The menu shows all five states. Picking DOWN opens an inline reason prompt — the text gets recorded as a BREAKDOWN event automatically (so you don't lose the context in the chip-flip).

Permission: equipmentstatus_write — separate from asset_write. A floor operator can have equipmentstatus_write without being able to edit the asset's accounting fields.

Backend: calls UpdateAssetRuntimeStatus RPC. Persists the new status, fires asset_status_changed SSE, and (if DOWN with a reason) auto-creates a BREAKDOWN MaintenanceEvent.

2. Maintenance event lifecycle

This is why you don't need to manually flip the chip when starting planned maintenance — start the event, and the asset moves to MAINTENANCE for you.

3. Work-order operation integration

When a routing operation starts on an asset's WC (StartRoutingOperation), the system flips the asset to RUNNING (or SETUP for the setup phase) if it was previously IDLE. Completing the op flips it back to IDLE.

This integration is opt-in per tenant — for shops that don't want automatic state changes on every op start/end, leave it off and use the Quick Menu.

4. Cron rollup

Two cron jobs run regularly:

These don't change leaf assets — they only recompute the derived/rollup values on parents and WCs. The leaf state is set by operator action / maintenance event / WO operation.

How status propagates

Leaf asset (RUNNING)
   │
   │ (set by operator / cron / WO op)
   ▼
Sub-assembly (rollup = worst of children)
   │
   │ (5-min cron)
   ▼
Machine (critical_asset=true) — has work_center
   │
   │ (5-min WC rollup)
   ▼
Work Center current_runtime_status
   │
   │ (broadcast via SSE: workcenter_status_changed)
   ▼
Equipment Hub status board + Capacity Planner card

A non-critical asset's downtime stops at the asset level — it doesn't bubble to the WC. This is the lever that decides which assets are line-stopping and which are bypass-able.

Quick Menu UI patterns

• Click to open — kebab icon on the chip.
• Highlighted current state — the menu shows which state the asset is currently in.
• Reason prompt — appears only for DOWN. Optional but recommended; it auto-creates the breakdown event.
• Confirmation toast — "Heidelberg Press 1 → DOWN" appears as a brief notification.
• Pulse animation — the chip pulses for 2 seconds in the new status color after the SSE broadcast — visible across the floor.

Permission tiers

The split matters because:

• An operator needs equipmentstatus_write to do their job (mark things DOWN) but should not have asset_write (would let them change acquisition cost or dispose the asset).
• A maintenance lead might have maintenance_write (to log events) plus equipmentstatus_write but no accounting access.
• Only finance / admin gets asset_write.

The Equipment Detail page surfaces all three actions but disables them based on the user's actual grants.

SSE: what flows when status changes

A single status change emits one or more events:

The Equipment Hub subscribes to all three and updates the affected widgets in place — no full page refresh.

Recipes

"Tablet operator workflow when a press jams"

1. Operator hits the kebab on the Heidelberg Press 1 chip.
2. Picks DOWN → "feeder jam".
3. Asset flips to DOWN, chip pulses red. WC rolls up to DOWN. Status board card on the hub updates instantly for everyone.
4. A BREAKDOWN MaintenanceEvent is auto-created with started_at = now and root_cause = "feeder jam". Status IN_PROGRESS.
5. Maintenance lead sees the alert, walks over.
6. After fixing: opens the event from the Maintenance Hub → fills ended_at, adds parts used → Complete.
7. Asset auto-flips back to its prior status (RUNNING). Chip pulses green. WC rolls up. maintenance_completed SSE fires.

"Take a press down for planned PM"

Don't manually flip to MAINTENANCE first. Instead:

1. Open the PM event (auto-created by the cron, or create it manually).
2. Press Start on the event.
3. Asset flips to MAINTENANCE automatically. WC rolls up.
4. On Complete, asset restores to the prior status.

This way the downtime is captured in downtime_minutes on the event, not just in an audit log.

Troubleshooting

Related

• Asset Management — where runtime_status lives
• Work Centers for CAPA — what critical_for_capa and the rollup do
• Maintenance Events — how planned and unplanned events change state
• Permissions — the three-tier write model