Downtime Reason
A Downtime Reason categorizes why a Machine or Station was not producing. Downtime reasons follow the group-reason hierarchy described in Reason Taxonomy, with the additional dimension of downtime type on the group level.
For sites that treat handheld tools as downtime causes, the downtime reason can represent the affected tool name while the planned/unplanned classification still comes from the selected downtime group.
Downtime reasons can be available at every station at a site or limited to selected stations. Operators logging downtime at a station only see globally available reasons plus reasons enabled for that station. The My Shifts downtime panel separates station downtime from site/system downtime before opening the logging modal. Station downtime starts by selecting one station, then choosing a reason code. Site/system downtime starts by showing reason codes that affect more than one station, with each row showing the affected station count and station preview before the modal opens. A reason with no station availability rows is treated as a sitewide reason in that flow and selects all stations at the site. When a station has matching planned and unplanned versions of the same reason code and name, the logging modal shows the reason once and lets the operator choose the downtime type with a planned/unplanned toggle.
Database Tables
oee_downtime_groups
| Column | Type | Description |
|---|---|---|
id | UUID (PK) | Auto-generated |
site_id | UUID (FK) | References Site |
name | VARCHAR(100) | Group name (e.g., “MECHANICAL”) |
type | VARCHAR(20) | 'unplanned', 'planned', or 'idle' |
sort_order | INTEGER | Display ordering |
The type field is unique to downtime groups and affects OEE calculations:
unplanned— Breakdowns, unexpected failures. Reduces Availability.planned— Scheduled maintenance, changeovers. May or may not affect Availability depending on Siteavailability_mode.idle— No work scheduled. Affects TEEP but not standard OEE.
oee_downtime_reasons
| Column | Type | Description |
|---|---|---|
id | UUID (PK) | Auto-generated |
group_id | UUID (FK) | References oee_downtime_groups |
code | VARCHAR(50) | Reason code (e.g., “E042”), unique per group |
name | VARCHAR(255) | Reason name (e.g., “Conveyor Jam”) |
description | TEXT | Optional details |
is_active | BOOLEAN | Whether reason is selectable |
sort_order | INTEGER | Display ordering |
Note: The type field was removed from reasons — it is inherited from the parent group.
oee_downtime_reason_stations
| Column | Type | Description |
|---|---|---|
reason_id | UUID (FK) | References oee_downtime_reasons |
station_id | UUID (FK) | References the station row in oee_equipment |
created_at | TIMESTAMPTZ | Creation timestamp |
This table is an optional station availability list. A downtime reason with no rows in this table is available at every station on the site. A reason with rows in this table is available only at those stations.
Usage
- Referenced by
oee_machine_events.downtime_reason_idwhenevent_type = 'downtime' - Downtime type (from parent group) determines how the time is classified in OEE calculations
- The OEE Settings downtime tab uses a Products-style editor: the left rail selects reason groups, the main body filters and sorts reason codes, and clicking a code opens an editor view with a back button for the selected reason’s site, system, and station availability.
- Administrators can make a reason available at every station, limit it to individual stations, select all stations, or use Select by system to enable all stations assigned to a system.
- The My Shifts downtime panel filters the reason list by the selected station and folds matching planned/unplanned versions into one displayed option with a downtime-type toggle.
- The My Shifts downtime panel has two entry paths: Station Downtime for one station at a time and Site/System Downtime for reason codes that affect multiple stations. Single-station-only reasons remain in the station path.
Codebase Paths
- Tables:
database/sql_scripts/tables/oee_downtime_groups.sql,database/sql_scripts/tables/oee_downtime_reasons.sql,database/sql_scripts/tables/oee_downtime_reason_stations.sql