Driver Report Documentation¶

Menu Location: Reports > Delivery > Driver Report

Access Level: Manager / Administrator

Last Updated: 2026-03-01

Overview¶

The Driver Report provides weekly performance metrics for delivery drivers and routes. It tracks order counts, tips, mileage, and estimated vs actual delivery times to help manage driver efficiency and customer satisfaction.

Primary Functions:

View driver performance by route and week
Track total tips and average tips per order
Monitor route mileage
Compare actual delivery times vs estimates
Identify route timing issues and efficiency opportunities

Page Layout¶

Header Section¶

Page Title: Driver Report
Driver Time Stats Button: Links to detailed driver timing analysis
Week Navigation: Previous/Next arrows and week selector dropdown

Filter Controls¶

Week Selector: Dropdown showing weekly_cycle dates
Submit Button: Loads data for selected week
Navigation Arrows: Quick previous/next week buttons

Main Content Area¶

Info Callout: Explains "Time Difference" calculation methodology
Results Table: One row per route showing driver metrics
Sortable/Filterable: DataTables integration for sorting and searching
Export Button: CSV export for data analysis

Report Data & Columns¶

Column	Description	Calculation/Source
(Actions)	View Stop Times button	Links to route-specific stop timing details
Day	Day of week for route	Sunday through Saturday from routes.day
Route	Route name	Links to route editing page
Driver	Driver name assigned	From drivers table via routes_data
Orders	Count of deliveries	COUNT of non-cancelled orders on route
Tips	Total driver tips collected	SUM of driver_tip from orders
Tips Avg	Average tip per order	Total Tips ÷ Orders
Mileage	Route distance in miles	From routes_data.distance converted from meters
Time Difference	Deviation from estimated time	See calculation section below

Time Difference Calculation¶

Purpose: Measures how actual delivery timing compares to estimates

Methodology:

Gets estimated arrival time for last stop on route
Gets actual delivery time for last stop on route
Calculates difference between estimated and actual for first stop
Normalizes last stop difference by first stop difference

Why Normalize:

If driver starts late, we don't penalize them
Focuses on route execution, not start time delays
Measures driver efficiency independent of dispatch timing

Example:

First Stop:

- Estimated: 10:00 AM
- Actual: 10:15 AM
- Difference: +15 minutes late start

Last Stop:

- Estimated: 2:00 PM
- Actual: 2:30 PM
- Raw Difference: +30 minutes

Normalized Time Difference:
+30 minutes (actual) - 15 minutes (late start) = +15 minutes
Driver is 15 minutes behind schedule independent of late start

Display Format:

Shown in minutes (converted from seconds)
Positive number = driver running late
Negative number = driver ahead of schedule
Empty if no data available

Filters & Search Options¶

Week Selection¶

Week Dropdown:

Shows all weekly_cycle dates
Default: Current week (getWeekId())
Stores week_id in URL parameter
Persists across page reloads

Navigation Arrows:

Left Arrow: Go to previous week
Right Arrow: Go to next week
Updates URL with week_id parameter
Instantly reloads page with new week

Week ID System:

Sequential numbering of delivery weeks
Links to weekly_cycle table
Used throughout system for scheduling

DataTables Features¶

Sorting:

Click any column header to sort
Default: No sorting (displays as queried - by day then route name)
Multi-column sorting available

Filtering:

Search box filters all columns
Live filtering as you type
Case-insensitive search

Display Length:

Default: 200 rows per page
Prevents pagination for most route counts
Dropdown to change rows per page

Export:

CSV button in toolbar
Exports currently filtered/sorted data
Includes all visible columns

Common Use Cases¶

Use Case 1: Weekly Driver Performance Review¶

Goal: Assess driver efficiency for the week

Steps:

Select current or previous week from dropdown
Click Submit
Review Time Difference column for each driver
Note drivers with consistent positive times (running late)
Review tips average for customer satisfaction indicator
Click "View Stop Times" for problem routes

Example: Driver shows +25 minutes on Monday, +30 on Wednesday, +15 on Friday. Investigate route planning or driver efficiency.

Tips:

Negative time differences are good (ahead of schedule)
Tips average correlates with customer satisfaction
Check mileage vs time for route efficiency

Use Case 2: Route Optimization Opportunities¶

Goal: Identify routes that need better planning

Steps:

Select week to analyze
Sort by "Time Difference" column (click header)
Identify routes with highest positive differences
Click route name to review route configuration
Click "View Stop Times" to see specific problem stops
Adjust route order or timing estimates

Example: Route shows +45 minute time difference. Review shows traffic patterns not accounted for in estimates. Adjust departure time or reorder stops.

Tips:

Consistent delays suggest systematic route issues
Variable delays suggest driver performance issues
Check mileage to ensure route is optimal distance

Use Case 3: Driver Tips Analysis¶

Goal: Understand driver compensation and customer satisfaction

Steps:

Select week to review
Sort by "Tips Avg" column
Compare drivers on similar routes
Identify drivers with very low averages
Investigate potential customer service issues
Recognize high performers

Example: Driver A averages $4.50/order, Driver B averages $2.10/order on similar routes. Review Driver B's service quality and timing.

Tips:

Average tip reflects customer satisfaction
Compare within same route types (urban vs rural)
Very low tips may indicate service problems
Zero tips might indicate tip tracking issues

Use Case 4: Mileage Verification for Reimbursement¶

Goal: Validate driver mileage claims against route data

Steps:

Select week for reimbursement period
Review Mileage column for each driver's routes
Sum total miles per driver across week
Compare to driver-submitted mileage claims
Investigate significant discrepancies

Example: Driver claims 150 miles but route data shows 127 miles. Review for additional stops or incorrect route tracking.

Tips:

Mileage is calculated from route planning data
May not include deviations or detours
Account for drive to/from depot
Update route data if actual distance differs

Use Case 5: Capacity Planning for High-Volume Days¶

Goal: Ensure adequate driver coverage for busy periods

Steps:

Select week with high order volume
Review Orders column per route
Note any routes with very high counts
Check Time Difference for overloaded routes
Plan to split high-volume routes in future

Example: Tuesday route shows 45 orders with +50 minute delay. Split into two routes or add helper driver.

Tips:

More than 30-35 orders per route may cause delays
Consider customer service quality vs efficiency
Plan splits before problem occurs
Monitor order growth trends

Actions & Operations¶

View Stop Times¶

Purpose: See detailed timing for each delivery stop on route

Steps:

Click "View Stop Times" button for desired route
Opens driver-report-route-details.php page
Review stop-by-stop timing data
Identify specific problem stops
Use for detailed route optimization

What It Shows:

Individual stop addresses
Estimated vs actual arrival times
Stop duration (time at location)
Sequence of deliveries

Navigate to Driver Time Stats¶

Purpose: Access driver-specific performance analysis

Steps:

Click "Driver Time Stats" button in header
Opens driver-report-driver-details.php
View aggregated driver performance across routes
Compare drivers to each other

What It Shows:

Total time metrics per driver
Average performance statistics
Driver comparison data

Export to CSV¶

Purpose: Download data for external analysis

Steps:

Configure week selection
Optionally filter or sort table
Click "csv" button in table toolbar
File downloads automatically
Open in Excel or Google Sheets

CSV Contents:

All visible columns
Currently filtered/sorted data
Formatted for spreadsheet import

Troubleshooting¶

Driver Name Not Showing¶

Symptoms: Driver column is empty for a route

Check:

Verify driver was assigned in routes_data for this week
Check if route has latest routes_data entry
Confirm driver exists in drivers table

Solutions:

Assign driver in route management for this week
Update routes_data with driver assignment
Verify weekly_cycle_id matches selected week

Common Causes:

Driver not assigned to route for selected week
Missing routes_data entry for week
Driver deleted from system after assignment

Time Difference Shows Empty¶

Symptoms: Time Difference column is blank for some routes

Check:

Verify route has est_deviation calculated in routes_data
Check if all orders on route have delivery timestamps
Confirm route was actually run (not planned only)

Solutions:

Ensure delivery confirmations were recorded
Run updateDriverReportStats() if admin access
Verify tracking data was properly recorded

Common Causes:

Route not yet completed
Missing delivery confirmation timestamps
Data not calculated yet for recent deliveries

Mileage Shows Zero or Missing¶

Symptoms: Mileage column is empty or shows 0

Check:

Verify routes_data has distance value
Check if route planning was completed
Confirm route_id matches between tables

Solutions:

Complete route planning in route management
Ensure distance is calculated and saved
Update routes_data with current week's data

No Data for Selected Week¶

Symptoms: Table is empty after selecting week

Check:

Verify week has scheduled routes
Check if orders exist for this week
Confirm weekly_cycle_id is correct

Solutions:

Select different week with known activity
Verify routes are configured for this week
Check if week is in future (no deliveries yet)

Driver Time Stats (driver-report-driver-details.php) - Driver-specific timing analysis
Route Stop Times (driver-report-route-details.php) - Detailed stop-by-stop timing
Route Management (admin-edit.php?table=routes) - Configure delivery routes
Driver Management (admin-edit.php?table=drivers) - Manage driver records
Weekly Schedule (week.php) - View/edit weekly delivery schedule

Typical Workflow:

Driver Report → Identify problem route → View Stop Times → Adjust route order
Driver Report → Low tips → Driver Management → Performance review
Weekly Schedule → Driver Report → Verify completion and timing

Permissions & Access¶

Required Access Level: View access (implied from code - no explicit permission check)

Access Level Capabilities:

Customer Service: View delivery status for customer inquiries
Manager: Analyze driver performance and route efficiency
Administrator: Full access to all weeks and export features
Kiva Admin: All features plus database access and update functions

Best Practices¶

Regular Monitoring¶

Review driver report every Monday for previous week
Track time difference trends week-over-week
Monitor tip averages as customer satisfaction indicator
Export monthly for performance documentation

Driver Management¶

Discuss time differences in weekly driver meetings
Recognize drivers with negative time differences (ahead of schedule)
Provide training for consistent late drivers
Compare tips across drivers for service quality

Route Optimization¶

Investigate routes with >20 minute time differences
Review stop times for routes with timing issues
Adjust estimated times based on actual performance
Split routes showing 40+ orders regularly

Things to Avoid¶

❌ Don't penalize drivers for positive time differences without investigation
❌ Don't ignore consistent patterns in favor of single-week data
❌ Don't compare drivers on very different route types (urban vs rural)
❌ Don't forget to update route data after making changes

Quick Reference Card¶

Task	Action/Location
View current week	Select current week, click Submit
Go to previous week	Click left arrow
Check driver timing	Review Time Difference column
See stop details	Click "View Stop Times"
Export week data	Click CSV button
Compare drivers	Sort by Tips Avg or Time Difference
Find problem routes	Sort Time Difference high to low
Calculate weekly miles	Sum Mileage column for driver
Check route capacity	Review Orders column
Driver performance trend	Use navigation to review multiple weeks

FAQs¶

What does a negative Time Difference mean?¶

Negative time difference means the driver finished the route ahead of the estimated time. This is generally good, indicating efficient route execution.

Why is Time Difference normalized by first stop?¶

This accounts for late starts. If a driver starts 15 minutes late but still finishes only 10 minutes behind, they actually made up 5 minutes during the route. Normalization shows true route efficiency independent of start time.

How is mileage calculated?¶

Mileage comes from the route planning system's distance calculation, converted from meters to miles. It represents the planned optimal route distance, which may differ from actual GPS tracking.

Why don't all routes show tips?¶

If Tips column is empty or zero, either no tips were collected on that route, or tip tracking wasn't enabled/recorded for those orders.

Can I see historical data for a specific driver?¶

Use the week navigation to review past weeks. For aggregated driver history across weeks, use the "Driver Time Stats" page linked in the header.

Change Log¶

2026-03-01¶

Initial documentation created
All sections completed based on driver-report.php code review
Documented Time Difference calculation methodology
Added DataTables integration details
Included week navigation features

End of Documentation

For additional help, contact your system administrator or Kiva Logic support.

Driver Report Documentation¶

Overview¶

Page Layout¶

Header Section¶

Filter Controls¶

Main Content Area¶

Report Data & Columns¶

Time Difference Calculation¶

Filters & Search Options¶

Week Selection¶

DataTables Features¶

Common Use Cases¶

Use Case 1: Weekly Driver Performance Review¶

Use Case 2: Route Optimization Opportunities¶

Use Case 3: Driver Tips Analysis¶

Use Case 4: Mileage Verification for Reimbursement¶

Use Case 5: Capacity Planning for High-Volume Days¶

Actions & Operations¶

View Stop Times¶

Navigate to Driver Time Stats¶

Export to CSV¶

Troubleshooting¶

Driver Name Not Showing¶

Time Difference Shows Empty¶

Mileage Shows Zero or Missing¶

No Data for Selected Week¶

Related Pages¶

Permissions & Access¶

Best Practices¶

Regular Monitoring¶

Driver Management¶

Route Optimization¶

Things to Avoid¶

Quick Reference Card¶

FAQs¶

What does a negative Time Difference mean?¶

Why is Time Difference normalized by first stop?¶

How is mileage calculated?¶

Why don't all routes show tips?¶

Can I see historical data for a specific driver?¶

Change Log¶

2026-03-01¶