Filters and URL State Reference
Complete reference for all scheduler filter parameters, URL state management, focus tabs, and mutual-clearing behaviour.
Before you start
- You are familiar with the scheduler layout and filter bar from the views guide.
Expected outcome
You understand every filter parameter, how they interact, and how URL state enables bookmarking and sharing of scheduler views.
Filter parameters
All filters are applied server-side in getSchedulerData() and reflected in the URL query string.
| 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, 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,scaffoldmatches 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.
Search filter
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 view and panel state in the URL:
| Parameter | Purpose | Values |
|---|---|---|
view | Active planner view | board, day, week, map |
list | Planner list visibility | true, false |
listMode | List display mode | full, compact |
filters | Filter panel visibility | true, false |
guidance | Guidance rail visibility | true, false |
guide | Active guidance section | capacity, routes, deployment, changes |
panel | Active detail panel | Various panel identifiers |
selected | Selected job keys | CSV of entityType:id keys |
focus | Active focus tab | all, blocked, flagged, unassigned, unscheduled, draft, ready, deployed, awaiting, acknowledged |
timelineDate | Timeline date | ISO date |
timelineMode | Timeline mode | day, week |
localStorage persistence
These preferences persist across sessions in the browser:
| Key | What it stores |
|---|---|
| Active view | Last-used planner view (board, day, week, map) |
| Timeline mode | Day or week |
| Panel states | Guidance rail open/closed, list visible/hidden |
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.severity === "blocking") |
| Flagged | job.validationWarnings.length > 0 |
| Unassigned | job.engineerIds.length === 0 |
| Unscheduled | job.scheduledDate === null && job.targetMonth === null |
| Draft | job.deploymentState === "draft" |
| Ready | job.deployReady === true |
| Deployed | job.deploymentState === "deployed" |
| Awaiting | job.deploymentState === "deployed" && !job.engineerAcknowledgedAt |
| Acknowledged | job.deploymentState === "deployed" && Boolean(job.engineerAcknowledgedAt) |
Sort order
Results from the server are sorted by:
scheduledDateascending (scheduled jobs first)titleA-Z (alphabetical within the same date)
Unscheduled jobs (null date and null target month) appear after all scheduled jobs.
Planner Interface Reference
Route-level reference for the scheduler planner — regions, views, action bar, selection bar, and layout controls.
Dialogs and Workflows Reference
Reference for every scheduler dialog — Quick View, Bulk Update, Task, Day Run, Batch Inspections, Recurring Import, Deploy, Warnings, and Engineer Rules.