maintenance_plans

Maintenance programmes and the tasks they contain. Not part of the daily set — delivered only when a plan revision changes. Update key: the plan’s external_system_id plus task_external_system_id, within the project

This file deletes. Any task that exists in the platform but is absent from a delivered file is hard-deleted, for every plan the file mentions. A plan file must therefore always carry the complete task list for each plan it names. Read what gets deleted before producing this file — the failure modes are destructive and not recoverable from the import itself.

Layout

Plan and task columns sit on the same row, one row per task. Plan columns are repeated identically across every row belonging to the same plan. When a plan’s rows disagree on the plan-level columns, the first row in the file wins and the rest are ignored.

Plan columns

Column	Type	Required	Notes
`external_system_id`	text(100)	●	The plan’s identifier
`revision`	text(50)	○
`name`	text(200)	●
`description`	text	○	Empty becomes an empty string
`vehicle_type_code`	text(50)	◐	Exactly one of this or `component_type_code`
`component_type_code`	text(50)	◐	Exactly one of this or `vehicle_type_code`
`plan_external_updated_at`	timestamptz	○	Staleness key for the plan row

A plan targets a vehicle type or a component type, never both and never neither.

Task columns

Column	Type	Required	Notes
`task_external_system_id`	text(100)	●	The task’s identifier within the plan
`task_name`	text(200)	●
`task_description`	text	○	Empty becomes an empty string
`task_type`	enum	○	`RECURRING` (default), `ONE_TIME`, `SEASONAL`
`task_group`	text(100)	○	Free grouping label, e.g. `A-service`
`interval_type`	enum	●	`KILOMETERS`, `DAYS`, `HOURS`, `CYCLES`
`interval_value`	integer	●
`tolerance_before`	integer	○	Defaults to `0`
`tolerance_after`	integer	○	Defaults to `0`
`secondary_interval_type`	enum	◐	Same set. All-or-nothing with the next column
`secondary_interval_value`	integer	◐	All-or-nothing with the previous column
`secondary_tolerance_before`	integer	○	Defaults to `0`
`secondary_tolerance_after`	integer	○	Defaults to `0`
`season_start_month`	smallint	◐	`SEASONAL` tasks only
`season_start_day`	smallint	◐	`SEASONAL` tasks only
`season_end_month`	smallint	◐	`SEASONAL` tasks only
`season_end_day`	smallint	◐	`SEASONAL` tasks only
`safety`	boolean	○	Defaults to `false`
`location`	text(100)	○
`sort_order`	integer	○	Defaults to `0`
`task_external_updated_at`	timestamptz	○	Staleness key for the task row
`project_external_id`	text(100)	○	Inert — present in the header but never read

The tolerances are what decide whether work shows as due soon, due, or overdue, so they are worth getting right even though they default to zero.

Rules

Exactly one of vehicle_type_code / component_type_code, and the code must resolve within the project.
secondary_interval_type and secondary_interval_value must both be set or both be empty.
A SEASONAL task requires all four season fields; a non-seasonal task must have none of them. Months are 1–12 and days 1–31.

What gets deleted

After inserting and updating, the import deletes tasks. The scope is precise, and both of its sharp edges are worth understanding. What is safe: the delete only touches plans whose external_system_id appears in the file you just delivered, and never crosses projects. Plans the file does not mention are untouched. What is deleted: within each plan the file does mention, every task in the platform whose identifier is absent from that plan’s rows in the file. This is a hard delete, not an archive flag.

The delete is not protected by the staleness check. If you re-deliver an old plan file, its plan and task rows will be skipped as stale — but the delete still runs, and removes every task added since. Re-sending an old file is destructive even though it appears to change nothing.Splitting one plan across two files is also destructive. Whichever file lands second deletes the tasks contributed by the first. One plan’s complete task list must arrive in one file.

estimated_manhours and estimated_cost are maintained in the application by the Planner role. They are not in this file and are never overwritten by an import — so ordinary re-imports preserve them.The exception follows from the delete above: if a task disappears from a delivered revision, its row is removed and those locally maintained estimates go with it. Re-adding the task later creates a fresh row with empty estimates.

Example

Two rows of the same plan carrying two different tasks. Note the repeated plan columns:

external_system_id,revision,name,description,vehicle_type_code,component_type_code,plan_external_updated_at,task_external_system_id,task_name,task_description,task_type,task_group,interval_type,interval_value,tolerance_before,tolerance_after,secondary_interval_type,secondary_interval_value,secondary_tolerance_before,secondary_tolerance_after,season_start_month,season_start_day,season_end_month,season_end_day,safety,location,sort_order,task_external_updated_at,project_external_id
MP-X61-VEH-001,1,X61 Fordonsunderhåll,Underhållsplan för Coradia X61 fordon,X61,,2026-03-09T14:00:00Z,MT-X61-OVS-25K,Översyn 25 000 km,Planerad översyn vid 25 000 km,RECURRING,A-service,KILOMETERS,25000,2500,2500,,,,,,,,,false,,1,2026-03-09T14:00:00Z,X61ST
MP-X61-VEH-001,1,X61 Fordonsunderhåll,Underhållsplan för Coradia X61 fordon,X61,,2026-03-09T14:00:00Z,MT-X61-OVS-50K,Översyn 50 000 km,Planerad översyn vid 50 000 km,RECURRING,B-service,KILOMETERS,50000,5000,5000,,,,,,,,,false,,2,2026-03-09T14:00:00Z,X61ST

Why a file gets rejected

Required fields abort immediately, before anything else is checked:

Row 3: missing or empty external_system_id
Row 4: missing or empty name
Row 5: missing or empty task_external_system_id
Row 6: missing or empty task_name
Row 7: missing or empty interval_type
Row 8: missing or empty interval_value

Then the structural rules together:

Row 10: must have vehicle_type_code or component_type_code
Row 11: must have exactly one of vehicle_type_code or component_type_code, not both
Row 12: invalid task_type 'PERIODIC'
Row 13: invalid interval_type 'KM'
Row 14: invalid secondary_interval_type 'MONTHS'
Row 15: secondary_interval_type and secondary_interval_value must both be set or both be null
Row 16: SEASONAL task requires all season fields (start/end month/day)
Row 17: season fields out of range (month 1-12, day 1-31)
Row 18: non-SEASONAL task must not have season fields

Then type resolution:

Row 20: vehicle_type_code 'X62' not found in project
Row 21: component_type_code '0789-X' not found in project

Overview

File formats

Tables

Layout

Plan columns

Task columns

Rules

What gets deleted

Example

Why a file gets rejected

​Layout

​Plan columns

​Task columns

​Rules

​What gets deleted

​Example

​Why a file gets rejected

Layout

Plan columns

Task columns

Rules

What gets deleted

Example

Why a file gets rejected