Dispatch
Assign drivers, track deliveries on a live map, and optimize routes.
What This Module Does
The Dispatch module provides a real-time operational map showing driver positions via GPS, manifest management for grouping shipments into delivery runs, shipment-to-driver assignment (manual or automated), and route optimization using a Genetic Algorithm engine. It bridges the gap between a shipment being created in the system and that shipment physically moving through your delivery network.
Who Uses It
| Role | Access Level |
|---|---|
| Admin | Full access — view map, assign drivers, create manifests, run auto-optimize |
| Employee | Full access — same capabilities as Admin within their branch |
| Driver | No access to the Dispatch board. Drivers see only their own assigned shipments and pickups on the Driver Dashboard. |
Where to Find It
Navigate to Logistics → Dispatch in the left sidebar menu.
Screen Walkthrough
The Dispatch page is organized around a central map with flanking panels:
Center: Live Map
The main area displays a live map showing driver positions and delivery routes. Three map providers are supported — configure your preferred provider in Settings → Integrations → Maps:
| Provider | Requirements |
|---|---|
| Google Maps | Valid Google Maps API key with Maps JavaScript API enabled |
| Mapbox | Mapbox access token |
| OpenStreetMap / Leaflet | No API key required (free, open-source tiles) |
Map Elements
| Element | Visual | Description |
|---|---|---|
| Driver markers | Arrow icon with direction indicator | Show each driver's current GPS position. Arrow points in the direction of travel. |
| Status colors | Green / Yellow / Gray | Green = online (location updated within 5 min), Yellow = idle (5-15 min since last update), Gray = offline (over 15 min) |
| Driver trails | Blue polyline | Shows the last 30 minutes of movement history for each driver |
| Manifest stops | Colored circles | Pickup stops (blue circles) and delivery stops (green circles) from the active manifest |
| Route geometry | Purple polyline | The planned route connecting manifest stops in optimized order |
| Info window | Popup on click | Click a driver marker to see: driver name, current status, GPS coordinates, and active manifest ID |
Left Panel: Active Drivers
A scrollable list of all drivers who have GPS tracking enabled. Each entry shows the driver's name, status indicator (online/idle/offline), and number of assigned shipments. Click a driver in this list to center the map on their current position.
Right Panel: Unassigned Shipments
A list of shipments that are ready for dispatch but have not yet been assigned to a driver. Each entry shows the tracking number, destination city, and service type. Drag a shipment onto a driver on the map or in the drivers list to assign it, or use the auto-optimize button to assign all unassigned shipments at once.
Step-by-Step: Assigning Shipments to Drivers
Manual Assignment
-
1
Select Shipments
In the right panel (Unassigned Shipments), check the shipments you want to assign. You can use filters to narrow by destination city or service type first.
-
2
Choose a Driver
Click the "Assign To" dropdown and select a driver from the list. Only drivers who are active and assigned to the current branch appear.
-
3
Confirm Assignment
Click Assign. The shipments move from the Unassigned panel to the driver's manifest. The driver receives an in-app notification with the assigned shipments.
Drag-and-Drop Assignment
Alternatively, drag a shipment from the right panel directly onto a driver's name in the left panel or onto their marker on the map. The assignment is confirmed immediately.
Auto-Optimize
The auto-optimize engine distributes unassigned shipments across available drivers using a Genetic Algorithm (GA) to balance workload and minimize travel distance.
How It Works
- Groups all unassigned shipments by destination city
- Identifies all available drivers for the current branch
- Runs a Genetic Algorithm to find the optimal assignment that minimizes total distance while balancing the number of shipments per driver
- Creates manifests automatically — one manifest per driver
- Displays a preview modal showing the proposed assignments, optimization score, and workload variance
Optimization Preview
Before applying, the system shows:
| Metric | Description |
|---|---|
| Optimization Score | A percentage indicating how well-balanced the workload distribution is (100% = perfectly balanced) |
| Variance | The difference between the most-loaded and least-loaded driver in terms of shipment count |
| Driver Assignments | Each driver's name with their proposed shipment count and destination cities |
| Unassignable | Any shipments that could not be assigned (e.g., no driver covers that area) |
Click Confirm and Apply to execute the plan, or Cancel to make manual adjustments.
Manifests
A manifest is a delivery run document that groups multiple shipments for one driver. Manifests can be created manually from the Dispatch or Warehouse module, or automatically via the auto-optimize engine.
Manifest Fields
| Field | Description |
|---|---|
| Manifest ID | Auto-generated unique identifier |
| Driver | The assigned driver for this manifest |
| Shipments | List of shipments included (N shipments per manifest) |
| Status | Current state of the manifest |
| Created At | Timestamp when the manifest was created |
Manifest Statuses
| Status | Description | Next Status |
|---|---|---|
| Open | Manifest is being assembled; shipments can be added or removed | Closed |
| Closed | Manifest is finalized; no more changes allowed | Dispatched |
| Dispatched | Driver has departed with the manifest (terminal state) | None |
Manifest PDF Export
Click Export PDF on any manifest to generate a printable document containing all shipment details: tracking numbers, sender/receiver addresses, package weights, and service types. Drivers can print this for physical reference during their route.
Dispatch Workflow
The dispatch process follows this workflow from shipment creation through delivery:
| Step | Action | Resulting Shipment Status | Performed By |
|---|---|---|---|
| 1 | Shipment created | Pending | Admin / Employee |
| 2 | Shipment assigned to driver (manual or auto-optimize) | Processed | Admin / Employee |
| 3 | Driver picks up package | Picked Up | Driver |
| 4 | Package in transit between hubs | In Transit | Driver / Employee |
| 5 | Driver begins final delivery | Out for Delivery | Driver |
| 6 | Successful delivery | Delivered | Driver |
| 7 | Delivery problem encountered | Exception | Driver (with reason code) |
Tips and Best Practices
- Enable GPS tracking: The driver dashboard sends the driver's location every 30 seconds when GPS is enabled in the browser. Ensure drivers allow location access for real-time tracking to work.
- Morning dispatch routine: Run auto-optimize at the start of each day, review the proposed plan, adjust if needed, then confirm. This handles 90% of daily assignments in under a minute.
- Use the map for mid-day re-routing: If exceptions arise during the day, check driver positions on the map to find the closest available driver and reassign the shipment.
- Monitor driver trail colors: A gray (offline) driver marker means the driver has not sent a location update in over 15 minutes. Contact them to verify GPS is still active.
- Close manifests before dispatch: Always close a manifest before the driver departs. This locks the shipment list and prevents accidental modifications during delivery.
- Use the drivers panel for quick focus: Click any driver in the left panel to instantly center the map on their position. This is faster than manually panning and zooming.
- OpenStreetMap for cost savings: If you do not need Google Maps or Mapbox-specific features, use the OpenStreetMap/Leaflet provider — it requires no API key and has no usage costs.
Troubleshooting
| Problem | Possible Cause | Solution |
|---|---|---|
| Map shows no driver markers | No drivers have GPS enabled, or no drivers are assigned to the current branch | Verify that drivers have allowed location access in their browser. Check that drivers are assigned to the correct branch in user settings. |
| Driver marker is gray (offline) | The driver's browser has not sent a location update in over 15 minutes | Contact the driver. They may have closed their browser, lost connectivity, or revoked location permissions. |
| Map does not load at all | Map provider API key is missing or invalid | Go to Settings → Integrations → Maps and verify the API key. Or switch to OpenStreetMap/Leaflet which requires no key. |
| Auto-optimize returns empty results | No unassigned shipments exist, or no active drivers are available for the branch | Verify there are shipments in "pending" or "processed" status. Ensure at least one driver is active and assigned to the branch. |
| Cannot drag shipments to drivers | Browser drag-and-drop may be blocked by extensions or touch mode | Try disabling browser extensions. On touch devices, use the "Assign To" dropdown instead of drag-and-drop. |
| Manifest cannot be edited after closing | Closed manifests are locked by design to prevent accidental changes | If changes are needed, create a new manifest with the correct shipments. Only "Open" manifests can be modified. |
| Driver trails not visible | The driver has been stationary or only recently came online | Trails require at least 2 location data points over time. Wait for the driver to move, and the trail will appear within a few minutes. |