Maintenance windows
A maintenance window is a declared block of planned work on an asset: the monthly fire-alarm test, a pool resurfacing week, an elevator modernization weekend. Declaring windows matters for two reasons:
- Fairness in the numbers. Downtime that overlaps a maintenance window does not count against the asset’s uptime. Without a window, a planned 8-hour elevator inspection looks identical to an 8-hour failure in the 90-day record.
- Communication. Upcoming windows appear on the home status page (“Scheduled maintenance” section), on asset pages, in the mobile app, on the lobby kiosk’s maintenance strip, and in the weekly digest. Residents who know the pool closes Tuesday don’t file incident reports about it.
Creating a window
Section titled “Creating a window”Go to /admin → Maintenance. Each window has:
| Field | Notes |
|---|---|
| Asset | The asset the work applies to (one asset per window) |
| Title | Resident-facing - “Monthly fire alarm test”, “Pool filter replacement” |
| Starts / ends | The planned interval. Be realistic; you can edit later |
| Recurrence | none (one-off), weekly, or monthly |
| Notes | Optional internal/resident detail |
Windows can be edited and deleted from the same tab. There’s also a JSON API
for automation -
GET/POST/PATCH/DELETE /api/admin/maintenance[/:id] (staff-authenticated;
see Admin & ops).
Recurrence
Section titled “Recurrence”A weekly or monthly window repeats from its start date: the system
expands occurrences automatically inside whatever window it’s computing over
(the 90-day bars, the upcoming-maintenance lists). The classic example -
monthly fire-alarm test, first Tuesday 10:00–11:00, recurrence monthly -
is entered once and then paints one blue slat on the Fire Alarm System’s bar
every month, forever, with no further bookkeeping.
Use none for genuine one-offs (next week’s pool maintenance), and prefer a
recurring window over re-entering the same test every month - recurring
windows are also what make the pattern legible in the 90-day bar.
How uptime treats windows
Section titled “How uptime treats windows”The uptime engine applies two rules:
1. Downtime exclusion. When computing an asset’s 30/90-day uptime percentage, any downtime-incident interval that overlaps a maintenance window on that asset has the overlapping portion excluded. The percentage only reflects unplanned downtime. (Incidents still exist and are visible - the exclusion is purely in the uptime math.)
2. Day-slat precedence. On the 90-day bar, each day takes the worst applicable status:
down > degraded > maintenance > operational- A day touched by a planned window and nothing else paints blue
(
maintenance). - A day with real, unplanned downtime paints red even if a window also touched it - an outage is an outage in the visual record; the percentage is where the planned portion is forgiven.
- Recurring windows expand into their individual occurrences within the 90-day range, so the monthly test shows as one blue slat per month.
What this means in practice: declare windows before the work, sized honestly. If the elevator work runs long past the declared window, the overrun counts as downtime - which is the correct incentive.
Where residents see windows
Section titled “Where residents see windows”- Home page (
/) - a “Scheduled maintenance” section appears whenever windows are upcoming or active. GET /api/status- each asset carriesmaintenanceUpcoming(next 30 days): title, start, end. The mobile app renders this as the upcoming strip on Status and asset detail.- Kiosk (
/kiosk) - the upcoming-maintenance strip on the lobby TV. - Weekly digest - upcoming maintenance is one of the digest’s standing sections, so the board sees the week ahead.
- The bars - blue slats, with hover showing date and status.
During the window
Section titled “During the window”The window itself doesn’t change the asset’s live status - set the asset to
maintenance (blue) in /admin → Assets when work actually begins, and back
to operational when it’s done, so the summary banner and kiosk reflect
reality. (Asset status changes fire the asset.status_changed webhook event
and are audited, like everything else.)
If something goes wrong during planned work - the elevator modernization bricks the car - file a real downtime incident. The day will paint red, and time beyond the declared window counts against uptime, which is exactly the record you want.
Good practice
Section titled “Good practice”- Enter the standing windows on day one: fire-alarm tests, generator tests, scheduled inspections. These are the recurring blue slats that make your bars honest.
- Window the work, not the day - a 10:00–14:00 window is better than 00:00–23:59. Over-broad windows erode trust in the uptime numbers (and the audit log shows who created them).
- Announce through the window, not a comment - a window reaches the home page, the kiosk, mobile, and the digest. A comment on an old incident reaches almost no one.