Dispatch

The Dispatch surface helps you assign the right technician to each unassigned appointment. The dispatcher board at /fsm shows the appointment kanban, while /fsm/dispatch redirects to that board where dispatch suggestions are available.

Dispatcher board

The board shows appointments that are still in play:

• scheduled
• en_route
• on_site
• paused
• completed

Each card shows the appointment sequence, parent work order, scheduled time, assigned technician, and status controls. The board subscribes to realtime updates so multiple dispatchers can see changes.

AI dispatch

Click Run dispatch to score unassigned scheduled appointments against active technicians. The scorer is deterministic and greedy: it picks the highest-scoring available technician for each appointment.

The service loads:

• Candidate appointments.
• Work orders for service type and work-order number.
• Active technicians.
• Technician skills.
• Current open appointment workload.
• Resource unavailability for the candidate appointment window.
• Workspace dispatch settings from fsm_workspace_settings.

Unavailable technicians are skipped before scoring.

Scoring formula

Each appointment-technician pair gets a 0-1 score. The default policy is:

Admins can change these weights in FSM Settings. The scorer normalizes the total weight, so a workspace can bias dispatch toward skills, travel distance, workload balance, or truck inventory.

Proximity

Proximity scoring works in this order:

1. If the appointment and technician have the same service area, proximity is strong.
2. If both sides have coordinates, the score decays by distance using the workspace's max-travel-km setting.
3. If distance cannot be calculated, the workspace's unknown-distance score is used.

Service-type skill mapping

Skill matching depends on the workspace-wide service-type skill map in FSM Settings. The map uses work order service_type values as keys and arrays of workspace skill IDs as values.

{
  "hvac": ["skill-refrigerant", "skill-electrical"]
}

If a work order's service type has no mapping, skill matching receives a neutral soft-pass score. This keeps dispatch usable while you are still building your service taxonomy, but it makes recommendations less differentiated.

Reasons and warnings

Each suggestion includes explanations such as:

• Strong skill match.
• Local technician.
• Currently unassigned.

It can also show warnings such as:

• Missing required skills.
• Long travel distance.
• Already on several jobs.
• No truck inventory configured.

Confirming an assignment

The AI suggestion run is read-only. To apply a suggestion, click Apply. That writes the appointment's assigned_user_id; until then, dispatch output is advisory.

You can ignore the recommendation and assign a different technician manually.

API and AI tool access

Workload forecast

The forecast_workload AI tool returns appointment counts for the next N days plus a per-technician breakdown. It is useful for spotting overload before the week is committed.

Setup checklist

1. Add technicians with home coordinates.
2. Define service areas and assign technicians to their home area.
3. Tag technician skills from the workspace skill taxonomy.
4. Configure the service-type skill map in FSM Settings.
5. Configure scoring weights, travel distance, unknown-distance score, and workload capacity.
6. Configure truck inventory locations for technicians who carry stock.

Related

• Appointments - what dispatch assigns
• Technicians - profiles, skills, home base, and truck inventory
• Service Areas - proximity grouping
• Settings - dispatch scoring and service-skill mapping