Dispatch
AI-assisted assignment of unassigned appointments — scored on skill match, geographic proximity, current workload, and truck stock.
The Dispatch surface helps you assign the right technician to each unassigned appointment. Two views work together: the dispatcher board (/fsm) gives you a live kanban of every visit by status, and the AI dispatch panel (/fsm/dispatch) suggests assignments for unassigned scheduled appointments.
Dispatcher board (/fsm)
A kanban with five columns — one per appointment status that's still "in play":
┌──────────┬──────────┬─────────┬────────┬───────────┐
│ Scheduled│ En route │ On site │ Paused │ Completed │
└──────────┴──────────┴─────────┴────────┴───────────┘Each card shows:
- The appointment's sequence number (
#1,#2for visit 2 of N…) - A link to the parent work order
- Scheduled time
- Assigned technician (or ⚠ unassigned)
- Status-advance buttons (e.g. "→ en_route" from a scheduled card)
The board subscribes to realtime updates — two dispatchers see each other's moves immediately.
Drag-and-drop reassignment, calendar view, and live map are queued for the next release. Today you advance appointments by clicking the transition buttons on each card, and reassign by opening the appointment detail page.
AI dispatch panel (/fsm/dispatch)
Clicking Run dispatch scores every unassigned scheduled appointment against every active technician and returns a ranked recommendation per appointment.
Scoring formula
Each (appointment, technician) pair gets a 0–1 score, weighted:
| Factor | Weight | What it measures |
|---|---|---|
| Skill match | 0.4 | Does the tech have the skills the service type requires? |
| Proximity | 0.3 | Same service area = 0.9; otherwise distance decay from tech's home base to the appointment location (clamps to 0 past 100 km) |
| Workload | 0.2 | Fewer open appointments = higher score (10 open jobs → 0) |
| Truck stock | 0.1 | Tech has a truck inventory location configured = +0.2 |
The suggestion includes reasons ("Strong skill match · Local technician · Currently unassigned") and warnings ("Missing 2 required skills · Long travel distance · Already on 5 jobs") so you can override with context.
Service-type → skill mapping
Skill matching depends on a workspace-wide map of service_type → required skill IDs. Today this is API-only — configure via the v1 API. UI-driven config is queued alongside Settings UI work.
If a work order's service type has no mapping, skill matching scores a neutral 0.6 (soft pass — every technician is "fine enough").
Skipping unavailable technicians
Before scoring, the dispatcher checks each technician's calendar via the fsm_scheduling bridge (which consults lib/resource). Techs with overlapping unavailability — time off, busy with another appointment, outside their working pattern — are skipped entirely. They never appear in the ranked list.
Confirming an assignment
The AI runs read-only. To apply a suggestion, click Apply on the row — that's the moment the appointment's assigned_user_id is written and the activity log captures who assigned what and when.
You can also override: ignore the AI's top pick, click any other tech from the list, and apply that instead.
When AI dispatch runs
| Trigger | Behavior |
|---|---|
Manual — /fsm/dispatch → Run dispatch | Scores all unassigned scheduled appointments at workspace scope |
API — POST /api/fsm/dispatch | Same as above, scriptable; pass appointment_ids to score a subset |
AI tool — dispatch_optimal_tech | Same engine, callable from the Workestra AI panel |
AI tool — find_available_techs({ window }) | Read-only: returns techs free during a time window without scoring |
Workload forecast
The AI tool forecast_workload({ days: 7 }) returns:
- Appointment count per day for the next N days
- Per-technician breakdown
Useful for spotting Friday crunch or someone overloaded for the week.
Setting up for AI dispatch to be useful
- Add technicians with home coordinates (
home_lat/home_lng) — without these, proximity defaults to 0.3 baseline (useless). - Define service areas and assign techs to them — same service area is the biggest single proximity signal.
- Tag technician skills from the workspace skill taxonomy — required for the 0.4-weight skill match factor.
- Configure service-type → skill mapping (workspace-wide) — without this, all techs score the same on skill.
- (Optional) Configure truck inventory locations on technicians who carry stock — gives them the +0.2 truck-stock bonus.
The more of these you set up, the more useful AI suggestions become. Without them, the AI degrades gracefully — it'll always return a ranked list, but the differentiation will be flat.
Related
- Appointments — what AI dispatch assigns
- Technicians — profiles, skills, home location
- Service Areas — proximity grouping