> ## Documentation Index
> Fetch the complete documentation index at: https://docs.a7manager.se/llms.txt
> Use this file to discover all available pages before exploring further.

# maintenance_records

> Maintenance work that was performed.

Maintenance work that was actually carried out. Delivered daily.

**Update key:** `external_system_id`

## Columns

| Column                    | Type        | Required | Notes                                                                                   |
| ------------------------- | ----------- | :------: | --------------------------------------------------------------------------------------- |
| `external_system_id`      | text(100)   |     ●    | Update key                                                                              |
| `vehicle_number`          | text(100)   |     ○    | Required *unless* `component_serial_number` is set                                      |
| `component_serial_number` | text(100)   |     ○    | Both may be set — component work done while mounted                                     |
| `task_external_system_id` | text(100)   |     ○    | Task identifier from the maintenance plan. Must resolve if given                        |
| `completed_at`            | timestamptz |     ●    |                                                                                         |
| `depot`                   | text(100)   |     ○    |                                                                                         |
| `performance_km`          | integer     |     ●    | Reading at the time of work. Send `0` if unknown, never empty                           |
| `operating_hours`         | integer     |     ○    |                                                                                         |
| `deviation`               | integer     |     ●    | Signed deviation from the task's primary interval — negative is early, positive is late |
| `secondary_deviation`     | integer     |     ○    | The same, for the secondary interval when the task has one                              |
| `notes`                   | text        |     ○    |                                                                                         |
| `last_updated`            | timestamptz |     ●    | Staleness key                                                                           |

## Rules

* Every row needs **at least one** of `vehicle_number` / `component_serial_number`. Both may
  be set, which is the normal shape for work on a component while it was mounted.
* `task_external_system_id` is optional, but if present it must resolve to a task within the
  project.

<Warning>
  **`performance_km` and `deviation` are required and reject the file when empty**, even
  though both default to `0` in the database. That default only applies to records created in
  the application — it never rescues an import. If the value is genuinely unknown, send `0`
  explicitly.
</Warning>

<Note>
  Maintenance type, title and description are **not** on the record. They come from the linked
  task, so send `task_external_system_id` whenever the work was scheduled work. Without it the
  record exists but cannot be related to a maintenance plan, and it will not count towards
  compliance figures.
</Note>

## Example

The two rows below show the vehicle-only and component-only shapes, both with positive
(late) deviations:

```csv theme={null}
external_system_id,vehicle_number,component_serial_number,task_external_system_id,completed_at,depot,performance_km,operating_hours,deviation,secondary_deviation,notes,last_updated
MR-095,X61001,,MT-X61-OVS-200K,2026-07-28T14:00:00Z,Raus,228800,,28800,,Översyn 200 000 km — utförd under avställning tillsammans med hjulparsbyte,2026-08-01T10:08:04Z
MR-096,,0789-D-1,MT-WHL-REV-200K,2026-07-28T09:00:00Z,Raus,212800,,12800,,Revision 200 000 km — hjulpar avmonterat från X61001 och omsvarvat direkt,2026-08-01T10:08:04Z
```

## Why a file gets rejected

Required fields are checked first and abort before reference resolution runs:

```
Row 3: missing or empty external_system_id
Row 4: missing or empty last_updated
Row 5: missing or empty performance_km
Row 6: missing or empty deviation
Row 7: missing or empty completed_at
Row 8: missing or empty vehicle_number or component_serial_number (at least one required)
```

Then the three reference lookups together:

```
Row 12: vehicle_number 'X61099' not found in project
Row 14: component_serial_number '0123-9' not found in project
Row 16: task_external_system_id 'MT-X61-OVS-999K' not found in project
```