Preventive maintenance

A maintenance plan generates Draft work orders on a schedule. It does not book a slot, assign a technician, or invoice the customer.

Operations → Preventive Maintenance · /app/w/{workspace}/maintenance-plans · capability preventive_maintenance + plan feature contracts_pm · maintenance_plans.view / create

Queue worker + scheduler (cron) are required. Tabs: Plans and Upcoming. There is no PM calendar in V1.

What this is not

Expectation	V1 truth
Auto-Schedule	Does not exist. No date is chosen for you.
Auto-Assign	Does not run here. Auto-assign needs an already scheduled empty appointment.
Appointment on generate	None. Office Opens the work order, then Add appointment.
Invoice on generate	None.

Create a plan

1. Operations → Preventive Maintenance → Create plan, or from an agreement Add maintenance plan.
2. Customer (required). Optional site, covered assets, work-order type (so Field forms and signatures attach later).
3. Optional Service agreement. A plan without an agreement is valid. An agreement without a plan is also valid.
4. Frequency: Weekly, Every 2 weeks, Monthly, Quarterly, Every 6 months, Yearly, or Custom.
5. Starts on / optional Ends on. Due dates use the tenant timezone, not the site timezone.
6. Generate ahead (days) — 0–365. Empty uses the product default 30.
7. Save (Draft) then Activate.

How generation works

Cron must run php artisan schedule:run every minute. Hourly job fsm:maintenance-generate processes Active plans (caps apply per run). Each generated row is a Draft work order: unassigned, no appointment.

If the plan is linked to an agreement that has an included-visit pack, generation stamps visit intent (Will count as a contract visit on completion). Remaining does not drop yet — see Visit entitlements.

No cron, no Draft jobs

An Active plan still does nothing if the scheduler is down. That is not a Field bug and not a Dispatch bug.

After a Draft appears

1. Office Opens the work order (Field cannot execute Draft).
2. Add appointment.
3. Assign on Dispatch.
4. Technician Closeout is the visit. Office Complete finishes the work order and, if intent is set, consumes the pack.

Generation never picks a person.

Pause, resume, cancel

Pause stops new work orders; already generated jobs stay. Resume catches up inside a limited window (older dues are not infinitely backfilled). Cancel plan cannot be undone; existing work orders stay.

Troubleshooting

• Capability or contracts_pm off.
• Plan still Draft / Paused / Cancelled / Ended.
• Scheduler not running.
• You just saved — wait for the next hourly tick.

Related: Maintenance occurrence report, Queue.