Service Areas
Geographic zones used as a soft constraint by AI dispatch and as a filter in work-order lists.
A service area is a named geographic zone — a city, a region, a postal-code cluster — that your techs cover. Service areas are workspace-wide and lightweight: a few fields per zone, no PostGIS required.
Why service areas matter
Two places:
- AI dispatch scoring — if a work order's
service_area_idmatches a technician'shome_service_area_id, that pair scores 0.9 on proximity (the highest signal in the 0.3-weighted proximity factor). Same-area-as-home is the single most useful proximity cue today. - List filtering — appointment lists, dispatcher board, work-order list all filter by service area.
You can run FSM without service areas — proximity scoring falls back to coordinate distance decay, which works fine if every WO + tech has coordinates set. But for SMB workflows where "the Boston team handles Boston" is the model, service areas are simpler.
Creating a service area
Go to /fsm/service-areas → New service area.
| Field | Notes |
|---|---|
| Name | "Brussels Metro", "Greater London", "Northern California", whatever your dispatcher recognizes |
| Description | Free text — e.g. exclusions, special instructions |
| Bounding box (min/max lat + min/max lng) | Rough rectangle for the zone — used by future map view; not enforced today |
| Cities | Array of city names — useful for cities @> '{Brussels}' style filters |
| Postal codes | Array of postal codes the zone covers |
| Active | Inactive areas don't appear in pickers but historical assignments remain valid |
| Color | UI hint for the dispatcher board (any CSS color value) |
The bounding box, cities, and postal codes are metadata today — the dispatcher uses the service_area_id link directly. When the map dispatch view ships, the bounding box and city/postal lists will drive auto-fit and visual zone overlays.
Assigning a service area
| To | How |
|---|---|
| A technician | On the tech detail page, set Home service area |
| A work order | On the WO detail page, set Service area (or inherit from the customer's address) |
| An appointment | Inherits from the work order by default; override on the appointment for visits that happen in a different zone (e.g. tech meets the customer at their second office) |
Updating zones
Service-area edits apply going forward — past appointments and work orders keep their service_area_id pointer regardless of subsequent edits to the area itself. To rename or rescope a zone, edit it in place; to "split" or "merge" zones, create the new zone(s), update technicians + open work orders, deactivate the old zone.
Deactivating vs deleting
| Action | Effect |
|---|---|
| Deactivate | Hide from pickers; historical references preserved |
| Delete | Hard delete the row; FK on fsm_work_orders.service_area_id and fsm_service_appointments.service_area_id is set to NULL via ON DELETE SET NULL |
Deactivate by default — deletion is fine pre-launch but losing the labeled history later can hurt analytics.
Service-type → required-skills mapping
A related (but distinct) workspace-wide configuration is the service-type → required-skill map — e.g. "hvac" → ["skill-refrigerant", "skill-electrical"]. This drives the skill-match factor of AI dispatch. Today it's API-only; UI in Phase 4.8 alongside the rest of the Settings work.
Related
- Technicians — set a home service area per tech
- Dispatch — how
service_area_idmatching feeds scoring - Settings — where the rest of dispatch config lives (Phase 4.8 UI)