Smart Dispatch

Overview

Smart Dispatch is the optimization engine behind the Route Planner. When you click Optimize, Forz sends your routes and jobs to a routing API that calculates the most efficient assignment and stop order. The optimizer considers travel distance, job time windows, technician skills, job duration, and route capacity to build a plan that minimizes drive time while respecting all constraints.

Before You Begin

Prerequisites:

1. The Route Planner module is enabled (Settings > Modules).

2. You have the Route Planner: Show permission on your role.

3. At least one route exists on the planner with assigned technicians.

4. Jobs have a Service Address with valid coordinates (latitude and longitude).

How Optimization Works

What Forz sends to the API

When you click Optimize, Forz builds a payload containing:

• Routes (agents) — each unlocked route's start/end locations, time window (start time + duration), and skill capabilities.

• Jobs — each job's location, estimated duration, required skills, time window preferences, and priority.

• Transport mode — the vehicle type (Truck or Car), which affects routing calculations

• Optimization type — set to "balanced" to optimize for both travel time and schedule compactness.

What the API returns

The routing API returns an optimized plan that includes:

• Job assignments — which jobs go to which routes

• Stop order — the sequence of stops on each route

• Estimated arrival times — calculated start time for each stop

• Travel durations — drive time between each stop

• Unassigned jobs — jobs that could not be fit into any route

• Unassigned agents — routes with no jobs after optimization

Skills Matching

Routes inherit skills from their assigned technicians. Jobs can require specific skills through the dispatch info configuration.

1. Each technician has a list of skills set on their user profile (e.g., "HVAC", "electrical", "backflow testing").

2. A route's available skills are the combined unique skills of all assigned technicians.

3. When optimizing, the API only assigns a job to a route whose skill set includes all of the job's required skills.

Tip: Check the skills mismatch warning at the top of the Route Planner. If pending jobs require skills that no route provides, add a technician with those skills to a route before optimizing.

Time Windows

Time windows control when a job can be scheduled. They come from the job's dispatch info configuration.

• Job time windows — the time range during which the technician can arrive (e.g., Monday 8:00 AM - 12:00 PM).

• Route time windows — calculated from the route's start time and duration (e.g., 7:00 AM start with 8-hour duration = 7:00 AM - 3:00 PM).

• If a job has no custom time window, Forz uses a default window of 6:00 AM to 6:00 PM.

The optimizer only places a job on a route when the job's time window overlaps with the route's time window and there is enough time to complete the work.

Processing State

While optimization runs, the Route Planner enters a processing state:

1. A loading indicator appears on the planner.

2. Route assignments and the timeline are temporarily unavailable.

3. You cannot dispatch, assign jobs, or modify routes during processing.

4. Processing completes when the routing API returns results, typically within 10 to 60 seconds.

Warning: Do not close the browser tab during optimization. If you navigate away and return, the planner will show the results once processing completes.

Locked Routes and Optimization

Locked routes are excluded from full optimization:

• Jobs assigned to locked routes stay on those routes and keep their order.

• The optimizer only rearranges jobs on unlocked routes.

• You can optimize a single unlocked route without affecting other routes.

Reviewing Results

After optimization completes, review the results in the Route Planner.

Expected result: Routes display optimized job sequences with ETAs. Any jobs or agents that could not be matched appear in the unassigned sections.

Check for unassigned jobs

1. Look for the unassigned jobs section in the optimization summary.

2. Each unassigned job could not be placed due to time window conflicts, skill mismatches, or route capacity limits.

3. Manually assign these jobs to routes, or adjust constraints and re-optimize.

Check for unassigned agents

1. Routes with no jobs after optimization appear in the unassigned agents section.

2. This means no pending jobs fit that route's time window, location, or skill set.

3. Consider adjusting the route's start time, duration, or assigned technicians.

Changes count

Every modification you make after optimization (assigning, moving, reordering jobs) increments a changes count badge. This helps you track how much the plan has diverged from the optimized result before you dispatch.

Common Scenarios

Optimizing a full day for a plumbing company

A dispatcher has 15 unscheduled plumbing jobs spread across a metro area and three routes (North, Central, South). She clicks Optimize. The API assigns five jobs per route, ordered to minimize backtracking. Two jobs with narrow time windows (8:00 - 10:00 AM) are placed first on their respective routes. The dispatcher reviews the plan and dispatches.

Partial re-optimization after adding a rush job

After dispatching the morning plan, a priority water heater replacement comes in. The dispatcher cancels the dispatch, adds the new job to the pending list, locks the two routes that are already in progress, and optimizes only the third route. The rush job is inserted with minimal disruption to the existing plan.

Troubleshooting