04 — How It Works (design notes and answers)

Questions raised while the application was built and reviewed, with the answers as implemented. Use it with 01 — Quick Reference, which has the rules in short form.

Service tiers: 250, 500 and 1,000 hours

What is a tier? A larger service covers the lesser ones. The plans say so with Plan Inclusion records (1000 h covers 500 h and 250 h; 500 h covers 250 h). The Work templates are cumulative: the 1000 h template already contains the 250 h and 500 h tasks, so the application never combines templates.

What does "incorporated" mean? When a lesser item (say the 250 h) falls due inside the lead window of a larger item on the same unit, it does not raise an order of its own. Its status becomes incorporated, it points at the larger item, and it is completed with it. The larger item's Incorporated Items tab lists what it carries.

Can an item be incorporated into more than one larger item? No. An item has one link to the item that covers it. The reverse is not limited: one larger item can carry many lesser ones, so the 1000 h item can hold both the 250 h and the 500 h.

Flat, not chained. In a 1000 h cycle the 250 h and the 500 h both point at the 1000 h. The 250 h is not placed in the 500 h which is then placed in the 1000 h. Larger services are processed first (the one with the most inclusions), and a lesser item joins the first larger item whose lead window covers its due point. If only the 500 h covers it, it joins the 500 h. A chain would add nothing: the 1000 h order already contains all the content, and completion resets everything the 1000 h includes in one step.

Why might a 1000 h item show only one incorporated item? An item is pulled in only if it is due inside the larger item's lead window. Each service resets from its own actual completion, so cycles drift apart. A lesser item that is due too early raises its own order; one due too late stays in its own cycle. An item that is already deferred, or that already has an order of its own, is not pulled in. An item that falls outside the window later is released again.

What happens when the larger service is completed? The plan's included lesser items on the same unit are reset (last done, next cycle), including the items that were incorporated into it. A lesser item that has its own, different order is left alone.

A task already done last week

If a 250 h service was done a week ago, the 1000 h service should not repeat its oil change. This is handled in Work, when the order is created from the template (it is a rule about tasks, not about schedule items):

A template task can be flagged Skip If Recent.
When a new order is created, a flagged task that was completed on the same asset within recent_task_skip_days (14 by default, work_management/schema/work_settings.yaml) is copied as Not applicable, with the note Already done on WO-xxxx (date).
Tools for a skipped task are not requested.
Isolation and test tasks are not flagged, so they are always done.
The planner can switch a skipped task back on in the draft order.

What starts a recalculation

A meter update is the trigger. A new value from Lifecycle (lifecycle.usage_recorded) or a correction (lifecycle.exposure_revised) recalculates that unit's items immediately and asks Work for an order when one enters its lead window.
The batch is for what no event announces: calendar, fixed-date and life triggers, a plan newly added to a group, and anything stale. Run it from Schedule → Recalculate (all units, or one), the command schedule.recalculate or scripts/recalculate.py, every few days or by hand. It covers all the units of every active plan's group, with no unit limit, and it is independent of any picker. Nothing inside the application schedules it.

What does not become a schedule item

An elevated condition reading is a warning in Condition Monitoring only. Two normal results in a row resolve it. A possible or confirmed wear pattern asks Work for a draft order.
A life forecast from Lifecycle gives a one-off life item, unless a life plan already schedules that SMCS.
There is no plan "type". The Work template carries the work type and the tasks; a sample is simply a task in the template.

Deferral

schedule.defer_item sets a date and a note. The item stays deferred while that date is ahead. A deferral beyond the plan's tolerance past the due point also publishes schedule.item_deferred, so Assurance can decide whether it matters; a shorter one is only recorded.

Screens: the Network section and linked records

Network section. The network identifiers (this record's id, the ids of the records it points at in other applications, and the Message Flow ID that traces a message across applications) are not shown among the ordinary fields on the view, edit or create screens. They sit in a collapsed Network section at the bottom, laid out like the other fields: a label above a boxed value, the readable number first and the id under it. The ids are still held and still submitted (as hidden fields on edit).

Message Flow ID. The id shared by every message that belongs to one chain of cause and effect, for example the command that asked Work for an order and the event Work raised in reply. Use it to follow a request across applications and in the orchestrator.

Links to other applications open in a modal window. A link to a record in another application (Work order, asset and so on) opens that record, read-only, in a window over the current page. Ctrl, Cmd or Shift click, or Open in new tab, opens a tab instead. The close button is at the left of the title bar. The environment variable XAPP_LINKS_IN_MODAL=0 switches it off.

Scrolling inside the modal. The linked page is shown without its menu and title bar. Its content scrolls inside the modal, and opening its Network section scrolls that section into view.

List columns

Child lists (a tab under a record) leave out the column that names the parent, because the parent is already on screen: the plan's Triggers tab has no plan column, a template's Tasks and Tools tabs have no template column. The same list opened from the menu keeps it. This is switched on per model in schema/menu_config.yaml under drilldown_hide_parent: (Plan Trigger here; Plan Inclusion keeps both plan columns because they are the "covers" and "covered by" pair). The Work Management template task list shows sequence, task code, instruction (cut at 50 characters, full text on hover), task type and template.

The list screens show a chosen set of columns, not every field: the plan list (code, name, group, template, lead days), the trigger list, the item list (number, unit, plan, status, last done, next due, order) and the inclusion list. Status values are badges. The source and source_ref fields are labelled Source Type and Source Reference.