Filters and URL State Reference

Filter parameters

Board, Timeline, and Map filters are applied to the scheduler overview request and reflected in the URL query string. Forecast deliberately ignores start, end, and every planner filter in this table so it can show the full 12-month workload across accessible sites.

Parameter	Format	Example	Behaviour
`start`	ISO 8601 date	`2026-04-14`	Window start; defaults to current week
`end`	ISO 8601 date	`2026-04-20`	Window end; defaults to current week
`engineerId`	UUID	`abc-123-def`	Exact match on assigned engineer
`siteId`	String	`site-456`	Exact match on site
`jobType`	String	`inspection`	`inspection`, `work_order`, or `task`
`status`	String	`pending`	`pending`, `in_progress`, `on_hold`, `completed`, `cancelled`
`q`	String	`smoke vent`	Case-insensitive search across multiple fields
`region`	CSV	`London,Scotland`	Expanded to constituent postcode areas
`postcodeArea`	CSV	`SW,E,M`	Exact match on extracted postcode area (uppercase)
`equipment`	CSV	`mewp,scaffold`	Normalised to lowercase; OR semantics
`ooh`	Boolean string	`true`	Strict boolean comparison on `outOfHours`

Geographic filter details

Postcode area

Postcode areas are extracted from site postcodes using the pattern ^([A-Z]{1,2}) — the first 1-2 letters of a UK postcode. For example, SW1A 1AA yields area SW.

The 67 Royal Mail postcode areas are mapped to 11 UK regions:

Region	Postcode areas
Scotland	AB, DD, DG, EH, FK, G, HS, IV, KA, KW, KY, ML, PA, PH, TD, ZE
Northern Ireland	BT
North East	DH, DL, NE, SR, TS
North West	BB, BL, CA, CH, CW, FY, L, LA, M, OL, PR, SK, WA, WN
Yorkshire & Humber	BD, DN, HD, HG, HU, HX, LS, S, WF, YO
East Midlands	DE, LE, LN, NG, NN, PE
West Midlands	B, CV, DY, HR, ST, SY, TF, WR, WS, WV
East of England	AL, CB, CM, CO, EN, HA, HP, IG, IP, LU, MK, NR, RM, SG, SS, UB, WD
London	BR, CR, DA, E, EC, KT, N, NW, SE, SM, SW, TW, W, WC
South East	BN, CT, GU, ME, OX, PO, RG, RH, SL, SO, TN
South West	BA, BH, BS, DT, EX, GL, PL, SN, SP, TA, TQ, TR
Wales	CF, LD, LL, NP, SA

Mutual-clearing behaviour

Region and postcode area filters are mutually clearing:

Selecting a region clears any active postcode area selection
Selecting a postcode area clears any active region selection

This prevents contradictory filters (e.g. "London" region with "AB" postcode area).

Equipment filter

Equipment values are normalised to lowercase and matched with OR semantics:

?equipment=mewp,scaffold matches jobs that require MEWP or scaffold (or both)
Query values are trimmed and lowercased before comparison

The 7 canonical equipment values: mewp, scaffold, tower_scaffold, ladder, cherry_picker, rope_access, harness.

The search field (q parameter) performs case-insensitive substring matching against a concatenated haystack:

Searched field	Source
Job title	`job.title`
Job subtitle	`job.subtitle`
Site name	`job.siteName`
System name	`job.systemName`
Engineer names	`job.engineerNames` (space-joined)
Postcode	`job.postcode`

URL state parameters

Beyond filters, the scheduler stores shareable planner state in the URL:

Parameter	Purpose	Values
`view`	Active planner mode	`board`, `timeline`, `map`, `forecast`
`selected`	Selected job keys	CSV of up to 25 `entityType:id` keys; additional in-memory selections are not written to a shareable URL.
`proposeSlots`	Slot-proposal dialog state	`1`
`focus`	Active focus tab	`all`, `blocked`, `flagged`, `unassigned`, `unscheduled`, `draft`, `ready`, `deployed`, `awaiting`, `acknowledged`, `provisional`, `date_offered`, `confirmed`, `locked`
`timelineDate`	Timeline date	ISO date
`timelineMode`	Timeline mode	`day`, `week`

Retired filters, list, listMode, guidance, guide, and panel parameters are not read. Old bookmarks do not migrate their retired filter or panel state; the next supported state change rewrites the URL without those parameters.

localStorage persistence

These preferences persist across sessions in the browser via deucalion:scheduler-layout:

Key	What it stores
Active view	Last-used planner mode (board, timeline, map, forecast), used when the URL does not include `view`
Timeline mode	Day or week, used when the URL does not include `timelineMode`
Navigation mode	Full nav, rail, or focus shell
Density	Comfortable or compact dispatch layout

Focus tabs

Focus tabs apply an additional client-side filter on top of the server-side filtered job set:

Tab	Filter logic
All	No additional filter
Blocked	`job.validationWarnings.some(w => w.blocking)`
Flagged	`job.validationWarnings.length > 0`
Unassigned	`job.engineerIds.length === 0`
Unscheduled	`job.scheduledDate === null`, including target-month demand
Draft	`job.deploymentState === "draft"`
Ready	`job.deployReady === true`
Deployed	`job.deploymentState === "deployed"`
Awaiting	Deployed work without `engineerAcknowledgedAt`
Acknowledged	Deployed work with `engineerAcknowledgedAt`
Provisional	`job.bookingStatus === "provisional"`
Date offered	`job.bookingStatus === "date_offered"`
Confirmed	`job.bookingStatus === "confirmed"`
Locked	`job.bookingStatus === "do_not_move"`

Sort order

Results from the server are sorted by:

Unscheduled jobs first, ordered by title A-Z.
Scheduled jobs next, ordered by scheduledDate ascending and then title A-Z.

This server sort applies to the Board, Timeline, and Map job set. Forecast uses its own month, service-line, region, and site summaries.