05 — User Guide

Step-by-step instructions for the planner. The rules behind them are in 01 — Quick Reference and 04 — How It Works.

1. Set up a plan

A plan says what is required for a group of units, how often, and which Work template does the job. Do these in order.

  1. Plans → Maintenance Plan → New. Give it a code and name, a status of active, and:
  2. Asset group: the maintenance group the plan covers. It also covers the child groups. A plan with no group applies to no units, so it does nothing until a group is chosen.
  3. SMCS (optional): the plan then applies only to units that have that SMCS fitted. Leave it empty for the whole unit.
  4. Maintenance template: pick the Work template (found by lookup). The template carries the work type and the tasks.
  5. Lead days: raise the work this many days before it is due.
  6. Tolerance days: days of grace past the due point before the item is overdue.
  7. Fixed cycle: leave it off to count the next due from the date the work was actually finished; switch it on to count from the scheduled date.
  8. Plans → Plan Trigger → New (or the Triggers tab on the plan). Add one trigger for each way the plan can fall due. The earliest governs ("250 hours or 3 months, whichever comes first"):
  9. Meter: the meter and the interval (for example hours, 250).
  10. Calendar: the interval in days.
  11. Fixed date: the day and month (for example 15 March).
  12. Life: no interval; it follows Lifecycle's forecast for the SMCS on the unit.
  13. Plans → Plan Inclusion → New (only for service tiers). Pick the larger plan and the lesser plan it covers. For example: 1000 h covers 500 h, 1000 h covers 250 h, and 500 h covers 250 h.
  14. Run the recalculation (section 4: Schedule → Recalculate). Items are created for the units the plan applies to.

To change an interval or template later, edit the plan or its trigger, then run the recalculation. To stop a plan, set it inactive (its items close) or clear its group.

2. Read the item list

Schedule → Schedule Item lists one item per unit and plan. Filter on status to find what needs attention.

Status What it means What to do
Not due Due date is further away than the plan's lead days Nothing
Due soon Inside the lead window Work has been asked for an order. Check the order (section 5)
Due At the due point As above; the order should exist already
Overdue Past the due point plus the plan's tolerance Find out why the order is not done. Defer it if there is a reason
In work An order exists and is open Nothing until the order closes
Deferred Put off until the deferral date Watch the date; see section 3
Incorporated Carried by a larger service inside its lead window Nothing; it completes with the larger item (the larger item's Incorporated Items tab lists it)
Closed A finished one-off, or the plan no longer applies Nothing

The forecast confidence says how far to trust the date. Low means the meter has gone quiet (older than the stale-reading setting) or its rate is unknown. The date is still shown from the last known reading and no usage is invented.

3. Defer a service

Deferral is a command, schedule.defer_item, not an edit on the item. It takes the item, the date to defer to and a note.

  • The item shows deferred until that date, and then goes back to its normal status.
  • A deferral that goes beyond the plan's tolerance past the due point also publishes schedule.item_deferred, so Assurance can decide whether it is material. A shorter deferral is recorded quietly.
  • Always give a note. It is the explanation that appears on the item.

4. Run the recalculation

You usually do not need to. A new meter reading from Lifecycle recalculates that unit's items at once, and Work is asked for an order when an item enters its lead window.

Run the batch when: - you have added or changed a plan, a trigger, an inclusion or a template; - you want calendar, fixed-date or life triggers brought up to date (nothing announces these); or - every few days as a routine, for anything stale.

On screen: Schedule → Recalculate. Choose All units or one unit, then Recalculate. The page shows how many items were created, closed and recalculated, and how many orders were requested from Work or cleared. If the Asset Register, Lifecycle or Work is not running it says the recalculation did not run, and nothing is changed. Running it needs edit access to Schedule Item. While it runs the button is disabled and an hourglass message shows. If another process is writing to the database, it waits and tries again a few times; if the database is still busy it says so and changes nothing, and you can press Recalculate again.

From a terminal (the same command, for a routine job), with the network running:

python apps/maintenance_schedule/scripts/recalculate.py              # every unit
python apps/maintenance_schedule/scripts/recalculate.py ASSET_CID    # one unit

or send the command schedule.recalculate. Nothing inside the application runs it on a timer; use the operating system's scheduler for a routine.

5. Check whether Work has been asked for an order

Open the item.

  • Work order and its reference show the order once Work has raised it. Click the reference to see it in a window (the reference opens that order in a modal; Ctrl or Cmd click for a new tab).
  • Maintenance template shows which template the order was or will be raised from.
  • The trigger detail shows, for each trigger, last done, next due and the current value, so you can see which trigger governs.
  • Status in work with a work order reference means the request was made and Work answered.
  • Status due soon or due with no order reference means Work has not answered yet, or the plan has no template (items without a template are left for a person), or the order was cancelled and the next recalculation will ask again. Run the recalculation, and check that the Work application is running.
  • The Network section at the bottom of the item (collapsed) holds the ids for tracing the request across applications, including the Message Flow ID. Open it when you need to match the item to a message or to the orchestrator.

6. Settings, with an example

Tuning values are in files, not in the schema. After a change, run the recalculation.

Setting File Default Meaning
tolerance_days maintenance_schedule/schema/schedule_settings.yaml 7 Grace before overdue, for items without a plan (a plan's own value wins)
stale_reading_days same 7 A meter older than this lowers the forecast confidence
condition_due_days same 14 A one-off item from a condition finding is due this many days out
one_off_lead_days same 14 Raise the work for a one-off this many days before it is due
life_template same PM-HT-1000 Template for a life item whose event names none
recent_task_skip_days work_management/schema/work_settings.yaml 14 A template task flagged Skip If Recent is not repeated if done on the same asset this recently

Example: truck meters are read weekly, so a quiet meter should not count as low confidence until 10 days. Change stale_reading_days: 7 to 10 in schedule_settings.yaml, then run the recalculation. Items whose last reading is 8 or 9 days old move from low to a normal confidence.

Example: repeat the oil change only if the last one was more than a month ago. In work_settings.yaml change recent_task_skip_days: 14 to 30. It applies to orders created after the change; existing orders keep what they were given. To make one task never skip, untick Skip If Recent on that template task.