Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Maintenance Plans

A maintenance plan is a recurring instruction to perform a specific intervention on a specific asset, on a specific trigger. Every 250 hours on the forklift. Every 6 months on the HVAC. When the press’s vibration exceeds 8 mm/s. Plans are how Beelocity distinguishes itself from a reactive ticket system — without plans, all maintenance is breakdown maintenance, and the module is mostly post-mortem.

The plan header

A plan carries:

  • Code and name — stable identifier and human label.
  • Flavour — PREVENTIVE, INSPECTION, CALIBRATION, or CONDITION_BASED. Drives default remedy filtering and KPI bucketing.
  • Scope — either a single asset (this specific press) or an asset class with an optional criticality filter (every CNC mill, or every A-critical HVAC unit).
  • Default team — the crew that picks up generated WOs by default.
  • Default priority — written onto each generated WO (lower = more urgent).
  • Lead time (days) — how far ahead of the due date the scheduler materializes the WO. One value (default 14 days) applies to every trigger type. This is the planner’s review window, not a parts lead time.
  • Slack % — tolerance around the nominal trigger. A 250-hour plan with 10% slack generates anywhere between 225 and 275 hours. Prevents drift accumulation.
  • Suspended until — optional pause date when the asset is mothballed or a plan is on hold.

Triggers

A plan has one or more triggers. Each says “fire when this condition is met.”

  • Time triggers — every N days / weeks / months / years, counted from either a fixed base date, the previous due date, or the previous work-order close (each cycle starts after the last one).
  • Meter triggers — every N units of a counter, relative to either the previous WO’s at-close meter (every N hours of usage since last service) or zero (a milestone service at the 1000-hour mark).
  • Condition triggers — when a windowed statistic of condition readings crosses a threshold. Examples: replace the bearing when vibration RMS exceeds 8 mm/s across the last 5 readings; escalate when oil acidity crosses 0.5 pH delta sustained over 7 days.

Multi-trigger plans (e.g., service every 500 hours or every 6 months, whichever first) fire on whichever trigger crosses first; the at-close meter and date become the new baseline for both.

Task templates

The plan detail page has a Tasks tab listing the ordered template the technician must perform on each generated WO. Each task has:

  • A sequence number (10, 20, 30 — leaves room for insertions).
  • A name and free-form instructions.
  • An estimated duration in seconds — used for the duration rollup and downtime previews.
  • An optional skill code — the team picker warns if the assigned crew lacks the skill.
  • A requires_lockout_tagout flag — surfaces a safety-checklist confirmation on the WO step.

Tasks are copied onto each generated WO, so a plan edit doesn’t retroactively change in-flight WOs.

Parts templates

The plan detail page also has a Parts tab listing the spare parts the plan typically consumes — engine oil, filter, grease. These rows are copied onto generated WOs as expected parts so storeroom can pre-pick; the technician confirms actual issuance at WO close. Optional parts are flagged separately so the technician knows they might not be needed.

The scheduler

The scheduler is a background job that runs hourly. It is also called synchronously after each meter reading, so meter-based plans fire within milliseconds of the reading that crosses the threshold.

Four principles:

  • Idempotent — re-running the scheduler doesn’t generate duplicates. The plan is only re-eligible when the previously generated WO closes or is cancelled.
  • Resilient to missed ticks — the next-fire computation is a function of the asset’s current state and the plan configuration, not of when the scheduler last ran. A scheduler that misses six hours of ticks catches up on the next run without losing or duplicating triggers.
  • Synchronous on meter reading — meter-based plans fire within milliseconds of the reading.
  • Multi-trigger first-wins — whichever trigger crosses first generates the WO and resets the others.

Generated WOs land in PLANNED status. The planner reviews, possibly bundles adjacent WOs on the same asset (one downtime window covers all three), and explicitly releases them to SCHEDULED.

Plan governance

Plans drift. A plan written for a forklift that’s since been replaced may still be triggering services based on stale assumptions. Two governance hooks keep the catalog honest:

  • Reviewed-at watchdog — when a plan has not been opened, edited or marked reviewed for more than 12 months it’s flagged Stale. The list page shows an amber chip on the Reviewed column and the Show stale only toggle in the toolbar filters the grid down to just those rows so the planning team can sweep through them at audit time.
  • Drift watchdog — when the last five work orders generated by a plan all overshot their labor estimate by more than two times, the plan picks up a Drift detected chip on the list and on the detail header. The task durations are out of date — open the plan, tighten each task’s estimated duration on the Tasks tab, and the flag clears on the next edit.

Neither hook auto-mutates a plan — every change is human-driven.

Marking a plan reviewed

When you open a plan, confirm the triggers, tasks, parts, lead time and slack still match how the asset is actually maintained, and either edit the plan or — if nothing needs changing — click More actions → Mark reviewed in the header. The action stamps today’s date as the new last-reviewed timestamp, clears the Stale chip, and silences the watchdog for another 12 months.

Preview and manual run

Two helper actions live in the header of the plan detail page:

  • Preview — opens a side drawer listing the next firings for each active trigger across a horizon you control (1 to 365 days, default 30). Time-based triggers project a date; meter-based and condition-based triggers can’t be projected without live usage or sensor readings, so they appear in the list with no date and an explanatory note. Opening the drawer is strictly read-only — no work orders are created.
  • Run scheduler — bypass the hourly tick and run the scheduler for one specific plan now. Useful after editing a trigger configuration, or to shorten the loop while debugging a new plan.

Running the scheduler manually

Open the plan detail page and click Run scheduler in the header. A confirmation dialog warns that the action is non-reversible — any triggers inside their lead-time window will materialise PLANNED work orders against every in-scope asset, and you’ll have to cancel them manually if you didn’t want them. Confirming runs the scheduler immediately; a toast at the bottom of the screen reports how many work orders were materialised (zero if no trigger crossed since the last run).

The action is gated by the MAINTENANCE_SCHEDULER_RUN permission. Planners typically have it; technicians don’t. If the button isn’t visible on your plan detail page, ask an admin to grant the permission to your role.

The scheduler is idempotent — running it twice in a row won’t generate duplicates. The second run only picks up triggers that crossed between the two calls.