Route Planner

Overview

The Route Planner lets dispatchers build daily routes for technicians, assign unscheduled jobs to each route, optimize stop order for travel efficiency, and dispatch the plan to create calendar events. Each day has one route planner that contains one or more routes (one per technician or crew). When you open the Route Planner for a date that has no planner yet, Forz creates one automatically and copies your route templates into it.

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 template is configured (Route Planner > Settings > Route Templates) so routes are created automatically.

4. Jobs you want to dispatch have a Service Address with latitude/longitude coordinates.

Opening the Route Planner

1. Click Route Planner in the sidebar navigation.

2. Forz opens the planner for today's date. Use the controls at the top to navigate: Today jumps to the current date, the date picker opens a calendar, and the arrow buttons step forward or backward one day at a time.

3. The planner uses a two-column layout. The left panel shows pending jobs (before optimization) or tabbed route details (after optimization). The right panel shows a routes table (before optimization) or the map and timeline stacked vertically (after optimization).

Expected result: The route planner loads with routes copied from your route templates. Pending jobs that match the selected date appear in the left panel.

Note: Each date has exactly one route planner. Forz creates it automatically the first time you navigate to that date, using your route templates as the starting configuration.

Understanding Pending Jobs

Pending jobs appear in the left panel grouped into collapsible sections. A job appears as pending when it meets all of these conditions:

• Status is Unscheduled

• The Routable toggle is enabled on the job

• The job is not already assigned to a route planner

• The job's weekday restrictions (if any) include the planner's day of the week

• The job's schedule date is on or before the planner date, or has no schedule date

Pending jobs are organized into three accordion sections:

• Featured — jobs scheduled specifically for the planner's date. These are the highest priority and appear first.

• Defined Schedule Date — jobs with a schedule date on or before the planner's date.

• Any Schedule Date — jobs with no schedule date but whose weekday restrictions include the planner's day. These are flexible and can be routed on any matching day.

Tip: Use these groupings to prioritize which jobs to route first. Featured jobs are date-specific and should typically be assigned before flexible jobs.

Assigning Jobs to Routes

Search and assign (before optimization)

Before the first optimization, a search field appears at the top of the jobs panel in the left column.

1. Type a job number, job title, organization, street, or city in the search field.

2. Locate the job in the search results.

3. Click the Assign button next to the job.

4. Select the target route from the dropdown. Each route shows its color dot and name.

Expected result: The job is assigned to the selected route. Forz recalculates ETAs for that route.

Tip: After optimization, pending jobs are available in the Jobs tab of the left panel. You can browse the accordion sections to find and review pending jobs, then use Reoptimize to include them in the plan.

Warning: A job must have a Service Address with valid coordinates (latitude and longitude). Jobs without geocoded addresses show an Invalid Address label and cannot be assigned to routes.

Moving Jobs Between Routes

You can move a job from one route to another in two ways:

Using the move-to dropdown

1. Open the Details tab in the left panel and select the route that contains the job.

2. Click the move button (arrow icon) below the job you want to move.

3. Select the target route from the dropdown.

Dragging on the timeline

1. In the route timeline, locate the job block you want to move.

2. Drag the job block from the current route lane to a different route lane.

Expected result: The job appears in the target route and is removed from the source route. Travel times update for both routes.

Reordering Jobs on a Route

1. Open the Details tab in the left panel and select the route you want to reorder.

2. Grab the drag handle (vertical dots icon) on the left side of any job card.

3. Drag the job to the new position within the list.

Expected result: Jobs on the route appear in the new order. ETAs and travel times update to reflect the changed sequence.

Removing Jobs from a Route

1. Open the Details tab in the left panel and select the route that contains the job.

2. Click the remove button (trash icon) below the job you want to remove.

Expected result: The job is removed from the route and returns to the pending jobs panel. ETAs for the remaining jobs on the route update automatically.

Optimizing Routes

Optimization sends your routes and jobs to a routing API that calculates the most efficient stop order across all unlocked routes.

1. Verify all routes and jobs are configured correctly.

2. Click the Optimize button in the header.

3. Forz sends the route data to the optimization API and shows a processing indicator.

4. When optimization completes, the map and timeline appear in the right panel with the suggested stop order.

Expected result: Jobs are assigned and reordered across unlocked routes for travel efficiency. The optimization summary bar shows total jobs, distance, service time, travel time, and any unassigned jobs or time window issues.

Tip: Lock routes you do not want the optimizer to change before running optimization. Locked routes keep their current job assignments and order.

Optimizing a single route

1. Open the Details tab in the left panel and select the route you want to optimize.

2. Click the optimize button (bolt icon) at the top of the route detail view.

3. Forz optimizes only that route without changing other routes.

Expected result: Jobs on the selected route are reordered for efficiency. Other routes remain unchanged.

Note: The per-route optimize button is hidden on locked routes. Unlock the route first to enable it.

Reoptimizing after manual changes

When you make manual changes (assigning, moving, or removing jobs) after optimization, a yellow warning badge appears and the Dispatch button is disabled. Click Reoptimize to re-run optimization with the updated assignments before dispatching.

Reviewing Optimization Results

After optimization, review the results before dispatching.

Optimization summary

A summary bar appears at the top of the routes panel showing:

• Jobs — total number of assigned jobs

• Distance — total route distance in miles

• Service time — total time spent at job sites

• Travel time — total driving time between stops

• Unassigned — jobs the optimizer could not fit (shown in red only when present)

• Time window issues — jobs whose scheduled time exceeds their time window (shown in yellow only when present)

Route comparison table

The Details tab in the left panel displays a comparison table showing each route's job count, time, distance, and load. Click a route row to see its full job list, members, skills, and utilization bar. Routes loaded above 90% show a red utilization bar, above 75% shows yellow, and below shows green.

Unassigned jobs

If the optimizer could not assign some jobs, a collapsible Unassigned Jobs panel appears below the summary bar. Each unassigned job shows its address, skills, and a button to focus on it on the map.

Warning: If the optimization reports unassigned jobs, check the job's time window, required skills, and duration. A job with a narrow time window or specialized skill requirement may not fit into the available routes.

Time window violations

Jobs whose estimated completion time exceeds their time window are highlighted on the timeline with a red border and striped pattern. In the route details, a red warning icon appears next to the time window field. Review these jobs and consider adjusting time windows, moving jobs to different routes, or adding more route capacity.

Dispatching Routes

Dispatching converts the planned routes into calendar events and marks jobs as Scheduled.

Dispatching the plan

1. Review the route timeline and optimization summary to confirm all assignments are correct.

2. Click the Dispatch button. A confirmation dialog shows the number of jobs and routes being dispatched.

3. Forz creates calendar events for each job on each route and sets job statuses to Scheduled.

Expected result: Each job on each route gets a calendar event with the calculated start and end time. The assigned technicians appear on each event. A green Dispatched badge replaces the Dispatch button.

Note: The Dispatch button is disabled when there are pending changes that need reoptimization, or when new pending jobs have been added since the last optimization. Click Reoptimize first.

Canceling a dispatch

1. Click the Cancel Routes button on a dispatched planner.

2. Confirm the cancellation in the dialog.

3. Forz deletes all calendar events created by the dispatch and sets job statuses back to Unscheduled.

Expected result: Calendar events are removed. Jobs return to Unscheduled status and reappear in the pending jobs panel.

Warning: Canceling a dispatch deletes all events created by that dispatch. Any manual changes technicians made to those events (notes, status updates) are lost.

Locking and Unlocking Routes

Locking a route prevents the optimizer from changing its job assignments or order.

1. In the route timeline, click the lock icon on the route label row.

2. The icon changes to a closed lock and the route row shows a subtle shaded background.

3. To unlock, click the lock icon again.

Expected result: Locked routes are excluded from optimization. You can still manually assign, move, reorder, and remove jobs on locked routes. The Reoptimize button tooltip shows how many routes will be reoptimized and how many are locked. If all routes are locked, the Reoptimize button is disabled.

Managing Routes

Route properties

Each route has these configurable properties:

• Display Name (required) — the route label (e.g., "North Route", "Team A")

• Start Time — when the route begins (e.g., 7:00 AM)

• Duration — route length in hours (1 to 20 hours)

• Break Duration — break time in minutes (0 to 120 minutes)

• Color — route color for map markers and timeline

• Start Location and End Location (required) — where the route begins and ends

• Assigned Users — technicians assigned to this route

Adding a route

1. Click the + button at the top of the routes panel.

2. Fill in the route name, start/end locations, start time, and duration.

3. Assign one or more technicians.

4. Click Save.

Expected result: The new route appears in the routes table or timeline.

Editing a route

After optimization, open the Details tab, select the route, and click the edit button (pencil icon) at the top of the route detail view. Edit and delete buttons are only available on undispatched planners.

Deleting a route

In the route detail view, click the delete button (trash icon). A confirmation dialog appears. You cannot delete a route if it is the only route on the planner. This option is only available on undispatched planners.

Skills matching

Routes inherit skills from their assigned technicians. When pending jobs require skills that no route provides, a yellow skills mismatch warning badge appears in the header. Hover over the badge to see which skills are missing. Assign technicians with the required skills to a route to resolve the mismatch.

Editing Route Planner Properties

Each route planner has two properties that affect optimization:

• Optimization Type — Balanced (default), Minimize Distance, or Minimize Time

• Transport Mode — Car or Truck (default). Affects routing calculations for road types and vehicle restrictions.

To change these, click the more options menu (three dots) in the header and select Edit. A small icon next to the date shows the current optimization type and transport mode on hover.

Note: The more options menu (Edit, Delete) is only available on undispatched planners. Cancel the dispatch first to access these options.

The Map and Timeline

After optimization, the right panel displays a map and a timeline.

Map

The map shows assigned job markers in each route's color and pending job markers for unassigned jobs. Click a job on the timeline or in the details panel and use the focus on map button (crosshairs icon) to center the map on that location.

Timeline

The timeline displays a horizontal grid with one lane per route. Each lane shows:

• Job blocks — colored bars showing the job number. Hover for address, time, and duration details.

• Start and end markers — white blocks with house and flag icons marking route endpoints

• Break blocks — dashed gray bars with a mug icon

• Travel gaps — light gray backgrounds between stops showing driving time

The left column shows route labels with the route color, assigned technician avatar, and a lock toggle. Click a route label to view its details in the left panel.

Click the fullscreen button (expand icon) to hide the map and give the timeline more vertical space.

ETA Calculation

Forz calculates estimated arrival times based on road distance and typical traffic patterns. ETAs update automatically when you:

• Assign a job to a route

• Move a job between routes

• Reorder jobs on a route

• Change a route's start time or location

Route Planner Settings

Navigate to Route Planner > Settings (or click Route Planner in the sidebar and select Settings) to configure route templates and user skills. The settings page has two tabs:

• Route Templates — define reusable routes that auto-populate when a new daily planner is created. Each template specifies a name, assigned members, skills, start time, duration, and start/end locations.

• User Skills — manage the skills assigned to each technician. These skills are used during optimization to match jobs with qualified technicians.

Common Scenarios

Morning dispatch for an HVAC service company

A dispatcher opens the Route Planner for tomorrow, Monday. Three route templates auto-populate: "North Team" (technician Mike), "South Team" (technician Sarah), and "Emergency" (technician Dave). Twelve unscheduled HVAC maintenance jobs appear in the pending panel under the Featured and Defined Schedule Date sections. The dispatcher clicks Optimize to assign and reorder stops across the three routes, reviews the optimization summary and route comparison table, then clicks Dispatch.

Re-routing after a cancellation

A customer cancels their 10:00 AM pool pump repair. The dispatcher opens today's Route Planner, but it is already dispatched. She clicks Cancel Routes, removes the cancelled job from the route using the trash button in the Details tab, adds a replacement job using the search field, clicks Reoptimize on the affected route, and dispatches again.

Handling a skills mismatch

A dispatcher sees a yellow skills mismatch warning badge in the header indicating that two jobs require "backflow testing" certification but no route has a technician with that skill. She edits the "Plumbing Team" route to add certified technician Carlos, then clicks Optimize. The two backflow jobs now appear on his route.

Troubleshooting