Maintenance Preferences

Maintenance preferences let you configure per-unit escalation rules, contractor overrides, owner approval thresholds, and access requirements. Once set, these preferences are automatically surfaced on every work order linked to that unit, ensuring the correct procedures are followed by anyone processing a maintenance request.

---

Overview

Each unit in a development can have one set of maintenance preferences. Preferences are optional — units without them continue to follow development-level defaults. When preferences exist, a banner is shown in the maintenance dashboard request detail panel and the full configuration is available on the unit detail page.

---

Setting Up Preferences

1. Navigate to Developments → [Development] → Units → [Unit].
2. Scroll to the Maintenance Preferences section.
3. Click Set Up (if no preferences exist) or Edit (to modify existing ones).
4. Complete the form and click Save.

The section shows a summary in view mode and a smart form in edit mode.

---

Configuration Fields

Contact Escalation

Field	Description
Contact First	Who must be contacted before scheduling any maintenance works. Options: Owner, Letting Agent, Occupant, Director.
Letting Agent Name	Name or company of the letting agent. Shown only when Letting Agent is selected.
Letting Agent Phone	Phone number of the letting agent.
Letting Agent Email	Email address of the letting agent.

Letting agent fields appear automatically in the form when Letting Agent is chosen as the primary contact.

Contractor Selection

Field	Description
Preferred Contractor	Optionally override the development's default contractor for this unit. Leave blank to use the development default.

The contractor dropdown lists all active contractors in the system. Preferred contractors are marked with a star (★).

Owner Approval

Field	Description
Require owner approval	When checked, works on this unit must be approved by the owner before proceeding.
Cost Threshold (€)	If set, owner approval is only required when estimated costs exceed this amount. Leave blank to require approval for all works regardless of cost.

Cost threshold warnings are highlighted in amber on the maintenance dashboard banner for immediate visibility.

Access Requirements

Field	Description
Advance notice required	When checked, the unit requires advance notice before access for maintenance.
Minimum notice (hours)	Minimum number of hours' notice required. Shown only when advance notice is enabled.
Access Instructions	Free-text instructions for gaining access (e.g. key safe location, intercom code).

General Notes

A free-text field displayed on every work order for the unit. Use this for any standing instructions that do not fit the structured fields above.

---

Maintenance Dashboard Banner

When a work order is linked to a unit that has preferences configured, a violet banner appears in the request detail panel on the maintenance dashboard. The banner shows:

• Who to contact first
• Preferred contractor (if set)
• Owner approval requirement and cost threshold (highlighted in amber if applicable)
• Access notice requirements and instructions
• General notes

No additional action is needed — the banner appears automatically.

---

API Reference (tRPC)

maintenance.getPreferences

Fetches maintenance preferences for a unit.

Input:

{ unitId: string }

Returns: The preferences record for the unit, including the preferred contractor name (via join), or null if no preferences are configured.

---

maintenance.savePreferences

Creates or updates maintenance preferences for a unit (upsert).

Input:

{
  unitId: string;
  contactFirst: "owner" | "letting_agent" | "occupant" | "director";
  lettingAgentName: string | null;
  lettingAgentPhone: string | null;
  lettingAgentEmail: string | null;
  preferredContractorId: string | null;
  requireOwnerApproval: boolean;
  approvalThreshold: string | null;   // decimal string, e.g. "500.00"
  accessRequiresNotice: boolean;
  accessNoticeHours: number | null;
  accessInstructions: string | null;
  generalNotes: string | null;
}

Behaviour:

• Creates a new preferences record if none exists for the unit.
• Updates the existing record if one already exists.
• Validates that the unit and (if supplied) preferred contractor belong to the same organisation.
• Emits an audit log entry on every save.

Returns: The saved preferences record.

---

maintenance.getRequest (updated)

The existing getRequest procedure now includes a maintenancePreferences field in its response when the request is linked to a unit that has preferences configured.

---

Audit Log

All preference saves are recorded in the audit log:

Action	Triggered when
maintenance.preferences_created	A new preferences record is created for a unit
maintenance.preferences_updated	An existing preferences record is modified

---

Notes

• Preferences are per-unit — one record per unit, shared across all work orders for that unit.
• Preferences are optional — omitting them has no effect on existing work order behaviour.
• No environment variables are required to use this feature.