bunker-admin 7895ce683e Tonne of debugging - getting ready for the production builds

2026-02-16 10:44:18 -07:00

35 KiB

Raw Blame History

Map Organizer Guide

Overview

As a Map Organizer, you're responsible for managing territories, coordinating volunteers, and organizing door-to-door canvassing using Changemaker Lite's Map module. This guide will help you:

Import and manage locations: Build your canvassing database from CSV or NAR data
Create territorial cuts: Divide your area into manageable canvassing zones
Organize volunteer shifts: Schedule and coordinate door-to-door canvassing
Monitor canvass progress: Track coverage, outcomes, and volunteer performance
Ensure data quality: Review geocoding accuracy and fix issues
Generate walk sheets: Create printable canvassing materials

Whether you're organizing a local ward campaign or a city-wide canvass, this guide provides strategies for effective territory management.

Understanding Map Roles

You may have one of two roles for map management:

SUPER_ADMIN

Access: Full platform access
Capabilities: All map functions plus user management, campaigns, site settings
Use case: Primary administrator

MAP_ADMIN

Access: Map module only
Capabilities:
- Import and manage locations
- Create cuts
- Organize shifts
- Monitor canvassing
- Generate walk sheets
Restrictions: Cannot manage users (except shift assignments), campaigns, or site settings
Use case: Dedicated field organizer without full admin access

!!! tip "Role Specialization" If you only manage field operations (not campaigns), ask for MAP_ADMIN role. This keeps the interface focused on your work.

Understanding Location Data

What is a Location?

A location is a physical address where canvassing occurs. Each location represents:

A single-family home, OR
An apartment/condo building (multi-unit), OR
A business address (if canvassing businesses)

Location data includes:

Address: Full civic address (street, city, province, postal code)
Coordinates: Latitude and longitude (from geocoding)
Building type: RESIDENTIAL, APARTMENT, BUSINESS
Unit count: Number of dwelling units (1 for houses, 10+ for apartments)
Cut assignment: Which territorial cut the location belongs to
Canvass history: Past visits, outcomes, support levels

Building vs Unit Level

Building-level data (recommended):

One location record per building
unitCount field indicates multi-unit buildings
Example: "123 Main St" with unitCount: 24 (apartment building)

Unit-level data (alternative):

One location record per unit
Example: "123 Main St, Unit 1", "123 Main St, Unit 2", etc.
More granular but creates more records

!!! tip "Recommended Approach" Use building-level data for apartments (one record with unitCount). This reduces database size and simplifies canvassing (volunteers visit building once, not once per unit).

Data Sources

1. CSV Import — Your own data

Volunteer sign-up forms
Voter registration data
Membership lists
Custom databases

2. NAR Import — Canadian electoral data

Elections Canada National Address Register
All residential addresses in Canada
Pre-geocoded coordinates
Federal electoral districts

3. Manual Entry — Individual addresses

Add one location at a time via admin interface
Click-to-add on map

Importing Locations from CSV

Preparing Your CSV File

Required columns:

address — Full street address (e.g., "123 Main St")
city — City name (e.g., "Ottawa")
province — Province/state code (e.g., "ON", "BC")
postalCode — Postal code (e.g., "K1A 0B1")

Optional columns:

latitude — Pre-geocoded latitude (decimal degrees)
longitude — Pre-geocoded longitude (decimal degrees)
buildingType — RESIDENTIAL, APARTMENT, or BUSINESS
unitCount — Number of units (integer, default: 1)
federalDistrict — Electoral district name
notes — Internal notes

CSV example:

address,city,province,postalCode,buildingType,unitCount
"123 Main St","Ottawa","ON","K1A 0B1","RESIDENTIAL",1
"456 Queen St E, Unit 5","Toronto","ON","M5A 1T1","APARTMENT",36
"789 Granville St","Vancouver","BC","V6Z 1K3","RESIDENTIAL",1

CSV formatting tips:

Use quotes around addresses with commas
Remove special characters (emoji, unusual symbols)
Use UTF-8 encoding (not Windows-1252 or ASCII)
One header row (first row = column names)
No blank rows (delete empty rows at end)
Consistent province codes (use 2-letter abbreviations)

Excel to CSV:

Open your Excel file
File > Save As
Format: "CSV UTF-8 (Comma delimited) (*.csv)"
Save

Importing the CSV

To import locations:

Navigate to Map > Locations
Click "Import CSV" button (top-right)
Upload your CSV file (drag-drop or browse)
Map CSV columns to location fields
Preview imported data (first 10 rows shown)
Click "Import"

Screenshot placeholder: CSV import dialog showing file upload area and column mapping interface

Column mapping:

The system tries to auto-detect columns, but verify:

CSV "address" → Location "address"
CSV "city" → Location "city"
CSV "province" → Location "province"
CSV "postalCode" → Location "postalCode"

If your CSV uses different column names (e.g., "Street Address" instead of "address"), map manually using the dropdowns.

What happens during import:

System validates each row (checks required fields)
Skips invalid rows (logs errors)
Creates location records
Geocodes addresses (if lat/lng not provided)
Shows summary: X imported, Y skipped

Import limits:

Maximum 10,000 rows per import
For larger datasets, split into multiple files

Troubleshooting Import Issues

Issue: "Invalid CSV format"

Causes:

File is not actually CSV (e.g., Excel .xlsx)
Missing header row
Inconsistent column count (some rows have more/fewer columns)

Solutions:

Save as CSV UTF-8 from Excel
Ensure first row is headers
Remove blank rows and columns

Issue: "Missing required field"

Causes:

CSV missing required column (address, city, province, or postalCode)
Column name doesn't match (e.g., "Street" instead of "address")

Solutions:

Add missing column to CSV
Use column mapping to map "Street" → "address"

Issue: "Geocoding failed for X addresses"

Causes:

Addresses are invalid (typos, wrong format)
Addresses are too vague ("Main Street" without number)
Geocoding service is down

Solutions:

Review failed addresses in Data Quality dashboard
Fix typos and re-import those rows
Manually place locations on map (see below)

NAR Import (Canadian Electoral Data)

What is NAR Data?

NAR (National Address Register) is Elections Canada's official database of all residential addresses in Canada. It includes:

Precise civic addresses (from Address files)
Geocoded coordinates (from Location files)
Federal electoral districts
Building use classification (residential, commercial, institutional)

Advantages:

✅ Comprehensive (all Canadian addresses)
✅ Pre-geocoded (high accuracy)
✅ Includes federal district data
✅ Updated regularly by Elections Canada

Disadvantages:

❌ Canada only (not available for other countries)
❌ Requires server access to install data files
❌ Large file size (multi-GB for provinces like Ontario)

Obtaining NAR Data

NAR data must be obtained from Elections Canada:

Contact Elections Canada Open Data team
Request latest NAR dataset (e.g., "NAR 2025 Server")
Download Address and Location files
Provide files to your system administrator

Files needed:

Address_[province]_part_[X].csv — Civic addresses
Location_[province].csv — Geocoded coordinates

System administrator places files in /data directory on server.

Importing NAR Data

To import NAR data:

Navigate to Map > Locations
Click "NAR Import" button
Select province (e.g., Ontario)
Choose dataset (if multiple years available)
Apply filters (see below)
Click "Start Import"

Screenshot placeholder: NAR Import modal showing province selector, dataset picker, and filter options

Import filters:

Province filter (required):

Select province to import (ON, BC, AB, etc.)
Each province has separate Address/Location files

City filter (optional):

Import only specific cities
Example: "Toronto,Ottawa,Mississauga" (comma-separated)
Leave blank to import entire province

Postal code filter (optional):

Import only specific postal code prefixes
Example: "K1A,K1B,K1C" (forward sortation areas)
Useful for targeting specific neighborhoods

Cut filter (optional):

Assign imported locations to a specific cut
If left blank, locations are imported without cut assignment
You can assign to cuts later

Residential only (toggle):

ON: Import only residential buildings (exclude commercial, institutional)
OFF: Import all buildings
Recommended: ON (unless you're canvassing businesses)

What happens during NAR import:

System scans NAR files for selected province
Joins Address and Location files on LOC_GUID (internal Elections Canada ID)
Filters by city, postal code (if specified)
Converts coordinates from EPSG:3347 (Lambert projection) to WGS84 (lat/lng)
Creates location records
Shows progress (can take several minutes for large provinces)

Import performance:

Small municipality (10k addresses): ~30 seconds
Large city (500k addresses): ~5 minutes
Full province (3M addresses): ~20 minutes

!!! warning "Server-Side Processing" NAR import runs on the server (not in your browser). Do not close the modal during import—wait for completion message.

NAR Data Fields

NAR import populates these location fields:

address — From Address file: CIVIC_NO + OFFICIAL_STREET_NAME + STREET_TYPE + STREET_DIRECTION
city — From Address file: MUNICIPALITY_NAME
province — From province code
postalCode — From Address file: POSTAL_CODE
latitude — From Location file: BG_LATITUDE (converted to WGS84)
longitude — From Location file: BG_LONGITUDE (converted to WGS84)
federalDistrict — From Location file: FED_NUM (district number) + name lookup
buildingUse — From Address file: BUILDING_USE (RESIDENTIAL, COMMERCIAL, INSTITUTIONAL)

Creating and Managing Cuts

What is a Cut?

A cut is a geographic area used to organize canvassing. Cuts are polygons drawn on a map.

Common cut types:

WARD: Municipal electoral ward
NEIGHBORHOOD: Informal neighborhood (e.g., "Downtown", "Riverside")
DISTRICT: Federal or provincial electoral district
CUSTOM: Any other boundary (e.g., "North of Highway", "Priority Zone")

Why use cuts?

✅ Assign territories to volunteers: "You canvass Ward 5"
✅ Track progress by area: "Ward 5 is 75% complete"
✅ Generate walk sheets: Print addresses for Ward 5 only
✅ Prevent duplication: Volunteers know their boundaries

Cut Best Practices

Size:

Recommended: 200-500 locations per cut
Too small (< 100): Inefficient (volunteers finish too quickly)
Too large (> 1000): Overwhelming (takes many sessions to complete)

Boundaries:

Use natural boundaries: Roads, rivers, parks, rail lines
Avoid cutting through neighborhoods arbitrarily
Use official boundaries when available (ward maps, district maps)

Naming:

Use official names when available ("Ward 5", "Riverdale")
Be consistent (don't mix "Ward 5" and "Fifth Ward")
Avoid abbreviations unless universally understood

Colors:

Use distinct colors for adjacent cuts
Use color coding meaningfully (e.g., priority cuts in red)
Ensure colors are visible on both light and dark backgrounds

Creating a Cut (Drawing on Map)

To create a cut:

Navigate to Map > Cuts
Click the "Map Drawing" tab
Click "Start Drawing"
Click on the map to add polygon vertices
Close the polygon (click near first vertex)
Fill in cut details (see form below)
Click "Save Cut"

Screenshot placeholder: Cut drawing interface showing map with polygon being drawn

Drawing tips:

Start at a corner: Begin at a distinct landmark (intersection, park corner)
Follow roads: Click along roads and boundaries
Use zoom: Zoom in for precision, out for overview
Closing detection: System detects when you're near the first point and offers to close
Undo: Click "Undo Last Point" if you make a mistake

Cut form fields:

Name (required):

Cut identifier (e.g., "Ward 5", "Downtown")
Displayed on map, walk sheets, volunteer portal

Category (required):

WARD, NEIGHBORHOOD, DISTRICT, or CUSTOM
Used for filtering and organizing

Color (required):

Display color on map
Use color picker or enter hex code (#FF5733)

Description (optional):

Internal notes about the cut
Example: "Priority area, high support expected"

Screenshot placeholder: Cut creation form showing name, category, color picker, and description

Automatic Location Assignment

When you save a cut, the system automatically:

Checks which locations fall inside the polygon (point-in-polygon algorithm)
Assigns those locations to the cut
Shows count: "X locations assigned"

Re-assignment:

Locations can only belong to one cut
If you draw overlapping cuts, later cuts override earlier assignments
Review location table to verify assignments

Editing Cuts

To edit a cut:

Navigate to Map > Cuts
Click "Edit" in Actions column
Modify name, category, color, or description
Click "Save"

Note: You cannot edit the polygon shape after creation. To change boundaries, delete the cut and redraw.

To delete a cut:

Click "Delete" in Actions column
Confirm deletion

What happens to locations?

Cut assignment is removed (locations become unassigned)
Locations are NOT deleted
Historical canvass data is preserved (visits remain linked to coordinates)

Managing Locations

Viewing and Filtering Locations

To view all locations:

Navigate to Map > Locations

The locations table shows:

Address: Full civic address
City: City name
Cut: Assigned cut (if any)
Geocoded: ✅ (has coordinates) or ❌ (needs geocoding)
Last Visit: Date of most recent canvass visit
Actions: Edit, delete

Filters:

Search: Search by address or postal code
Cut: Filter to specific cut
Geocoded: Show only geocoded or ungeocoded
Building Type: Filter by RESIDENTIAL, APARTMENT, BUSINESS
Date Added: Filter by import/creation date

Screenshot placeholder: Locations table with search bar, cut filter, and geocoded status column

Editing a Location

To edit a location:

Click "Edit" in Actions column
Modify fields (see below)
Click "Save"

Editable fields:

Address details:

Street address
City
Province
Postal code

Coordinates:

Latitude (decimal degrees, e.g., 45.4215)
Longitude (decimal degrees, e.g., -75.6972)
Drag map pin to adjust visually

Metadata:

Building type (RESIDENTIAL, APARTMENT, BUSINESS)
Unit count (integer)
Federal district (text)
Notes (internal notes)

Cut assignment:

Select cut from dropdown
Or leave blank (unassigned)

Screenshot placeholder: Edit Location modal showing address fields, map with draggable pin, and metadata fields

Manually Placing Locations on Map

If geocoding fails, you can manually place a location:

Edit the location
Use the map at the bottom of the form
Drag the red pin to the correct position
Latitude and longitude fields update automatically
Click "Save"

Tip: Use satellite view or street view to identify exact building location.

Bulk Operations

To perform bulk actions:

Select locations (checkboxes in table)
Choose action from "Bulk Actions" dropdown:
- Assign to Cut: Assign selected locations to a cut
- Geocode: Re-geocode selected locations
- Delete: Delete selected locations
Confirm action

Screenshot placeholder: Bulk actions dropdown with selected locations and action buttons

Deleting Locations

To delete locations:

Select locations in table (or filter and select all)
Choose "Delete" from bulk actions
Confirm deletion

!!! warning "Canvass History Preserved" Deleting a location removes the address record but preserves canvass visit data (visits are linked to coordinates, not location IDs). Historical data remains for reporting.

Geocoding and Data Quality

Understanding Geocoding

Geocoding converts addresses to latitude/longitude coordinates for map display.

Why geocoding matters:

Locations without coordinates cannot appear on map
Inaccurate coordinates place locations in wrong areas
Poor geocoding affects canvassing efficiency (volunteers can't find addresses)

Geocoding Providers

Changemaker Lite tries multiple geocoding providers in order:

Nominatim (OpenStreetMap) — Free, no API key, global coverage
ArcGIS — Free tier, accurate for North America
Photon — Free, Europe-focused
Mapbox — Requires API key, very accurate
Google Geocoding — Requires API key, most accurate
LocationIQ — Requires API key, Nominatim-based

How it works:

System tries Nominatim first
If confidence < 0.5, tries next provider
If all fail, location remains ungeocoded

API keys (optional, configured by admin):

Mapbox: MAPBOX_API_KEY
Google: GOOGLE_MAPS_API_KEY
LocationIQ: LOCATIONIQ_API_KEY

Without API keys, only free providers (Nominatim, ArcGIS, Photon) are used.

Geocode Confidence Levels

Each geocoded location has a confidence score (0.0 to 1.0):

0.9-1.0: High confidence (exact address match)
0.7-0.9: Medium-high confidence (likely correct)
0.5-0.7: Medium confidence (street or area match)
0.3-0.5: Low confidence (approximate)
0.0-0.3: Very low confidence (city or region only)

Confidence affects accuracy:

High confidence → Pin is at exact building
Low confidence → Pin may be at street midpoint or city center

Data Quality Dashboard

To review geocoding quality:

Navigate to Map > Data Quality

The dashboard shows:

Statistics cards:

Total locations: All location records
Geocoded: Locations with coordinates
Ungeocoded: Locations without coordinates
Low confidence: Confidence < 0.5
Medium confidence: Confidence 0.5-0.8
High confidence: Confidence > 0.8

Geocoding provider breakdown:

Chart showing which providers geocoded how many locations
Example: 60% Nominatim, 30% ArcGIS, 10% Mapbox

Confidence distribution:

Histogram showing confidence score distribution
Identify patterns (many low-confidence addresses?)

Action items:

Re-geocode low confidence: Button to retry with different provider
Export ungeocoded: CSV of failed addresses
Manual review: Link to locations table filtered for low confidence

Screenshot placeholder: Data Quality Dashboard showing statistics cards, provider pie chart, and confidence histogram

Improving Geocoding Quality

Strategy 1: Fix Address Typos

Export ungeocoded locations (CSV)
Review addresses in Excel
Fix typos, formatting errors
Re-import corrected CSV

Common issues:

Missing civic number ("Main Street" → "123 Main Street")
Misspelled street name ("Mane St" → "Main St")
Wrong province ("ON" → "BC")

Strategy 2: Re-geocode with Better Provider

Configure API keys for Mapbox or Google (ask admin)
Select low-confidence locations
Click "Geocode Selected" (bulk action)
System retries with all available providers

Strategy 3: Manually Place Locations

Filter locations with confidence < 0.5
Edit each location
Find correct position on map (use satellite view)
Drag pin to correct location
Save

Strategy 4: Use NAR Data (Canada Only)

NAR data includes pre-geocoded coordinates with very high accuracy. If you imported from CSV and have poor geocoding, consider switching to NAR import.

Organizing Volunteer Shifts

What is a Shift?

A shift is a scheduled volunteer canvassing session. Shifts have:

Title: Name of the canvass (e.g., "Saturday Morning Canvass - Ward 5")
Start/End Time: When volunteers should arrive and finish
Cut Assignment: Which area to canvass (optional but recommended)
Max Signups: Capacity limit (0 = unlimited)
Meeting Location: Where volunteers meet before canvassing

Why shifts matter:

✅ Coordinate volunteers: Everyone knows when and where to show up
✅ Track assignments: Volunteers see "their" shifts in portal
✅ Enable canvassing: Volunteers can only start canvass sessions if they have a shift
✅ Measure progress: See which shifts generated most visits

Creating a Shift

To create a shift:

Navigate to Map > Shifts
Click "Create Shift"
Fill in shift details (see below)
Click "Create"

Shift fields:

Title (required):

Descriptive name
Include date, time, and area
Example: "Saturday Morning Canvass - Ward 5"

Description (optional):

Additional details for volunteers
Example: "Bring water, comfortable shoes. We'll provide clipboards and walk sheets."

Start Time (required):

Date and time picker
When volunteers should arrive

End Time (required):

Expected end time
Helps volunteers plan their day

Cut (optional but recommended):

Select which cut to canvass
Volunteers assigned to this shift will see this cut in their portal
Shifts without cuts cannot be canvassed

!!! warning "Cut Assignment Required for Canvassing" Volunteers can only start canvass sessions for shifts assigned to a cut. Always assign a cut unless the shift is for training or other non-canvassing purposes.

Max Signups (optional):

Capacity limit (e.g., 10 volunteers)
Set to 0 for unlimited
Useful for managing group size

Meeting Location (optional):

Address or description of meeting point
Example: "Community Centre, 123 Main St" or "Corner of Main & Oak"

Screenshot placeholder: Create Shift form showing date/time picker, cut dropdown, capacity field, and meeting location

Managing Shift Signups

To view shift signups:

Navigate to Map > Shifts
Click "Signups" in Actions column for a shift

The signups drawer shows:

Capacity gauge:

Current signups / Max signups
Example: "8 / 10 signups (80% full)"

Signup list:

Volunteer name
Email
Role (USER or TEMP)
Signup date
Actions: Remove signup, upgrade TEMP to USER

Signup sources:

Public signup form (/shifts page):
- Anyone can sign up
- Creates TEMP user account automatically
- Sends confirmation email
Admin-added:
- You manually add volunteers
- Select existing users or create new
Volunteer portal:
- USER-role volunteers sign up themselves
- See My Shifts page in their portal

Screenshot placeholder: Shift Signups drawer showing capacity gauge and signup list

Adding Volunteers to a Shift

To manually add a volunteer:

Click "Signups" for the shift
Click "Add Volunteer"
Select existing user from dropdown (or click "Create New User")
Click "Add"

Upgrading TEMP users to USER:

After a TEMP user attends their first shift:

Open shift signups
Find the TEMP user
Click "Upgrade to USER"
Confirm

This gives them full canvassing access for future shifts.

Emailing Shift Volunteers

To email all volunteers in a shift:

Click "Signups" for the shift
Click "Email All"
Compose email:
- Subject
- Body (HTML supported)
- Variables: {{NAME}}, {{SHIFT_TITLE}}, {{SHIFT_START}}, {{MEETING_LOCATION}}
Click "Send"

Common email scenarios:

Reminder (day before shift):

Subject: Reminder: Tomorrow's Canvass - {{SHIFT_TITLE}}

Hi {{NAME}},

This is a reminder about tomorrow's canvass:

Shift: {{SHIFT_TITLE}}
Time: {{SHIFT_START}}
Meeting Point: {{MEETING_LOCATION}}

Please arrive 10 minutes early. We'll provide walk sheets and materials.

Looking forward to seeing you there!

Cancellation (weather, etc.):

Subject: CANCELLED: {{SHIFT_TITLE}}

Hi {{NAME}},

Unfortunately, we need to cancel tomorrow's canvass due to severe weather.

We'll reschedule and send you a new date soon. Thank you for your understanding.

Follow-up (after shift):

Subject: Thank you for canvassing!

Hi {{NAME}},

Thank you for participating in {{SHIFT_TITLE}}! Your efforts made a real difference.

Together, we knocked on [X] doors and spoke with [Y] residents.

See you at the next shift!

Screenshot placeholder: Email Shift Volunteers modal showing subject, body editor, and variable buttons

Generating Walk Sheets

What is a Walk Sheet?

A walk sheet is a printed list of addresses for door-to-door canvassing. It includes:

Cut name and statistics
QR code (volunteers scan to start canvass session)
List of addresses in walking order
Fields for volunteers to record outcomes

Walk Sheet Settings

To configure walk sheet defaults:

Navigate to Map > Map Settings
Scroll to "Walk Sheet Configuration"
Set:
- Header Text: Organization name, campaign info
- Footer Text: Contact info, instructions
- Include QR Code: Toggle ON/OFF
- QR Code Size: Small, medium, large
- Instructions: How to use the walk sheet

Example header:

Community Action Network
Fall 2024 Canvass
Contact: organizer@example.com | (555) 123-4567

Example footer:

Record outcomes: NH (Not Home), R (Refused), SW (Spoke With), S1-S4 (Support Level)
Return completed walk sheets to the office by end of week.

Screenshot placeholder: Map Settings page showing walk sheet configuration section

Generating a Walk Sheet

To generate a walk sheet for a cut:

Navigate to Canvass > Walk Sheet
Select cut from dropdown
Click "Generate"
Review PDF preview
Click "Print" or "Download PDF"

OR:

Navigate to Map > Locations
Filter to specific cut
Click "Walk Sheet" button (top-right)

Walk sheet contents:

Page 1:

Header (from settings)
Cut name and statistics:
- Total locations
- Last visit summary
- Completion percentage
QR code (links to /volunteer/canvass/[cutId])
Instructions (from settings)
Cut map (small overview map)

Subsequent pages:

Address table:
- Street address
- Unit count (if apartment building)
- Last visit date (if previously canvassed)
- Last outcome (if previously canvassed)
- Blank fields for volunteers to fill:
  - Date visited
  - Outcome
  - Support level
  - Notes

Screenshot placeholder: Walk sheet PDF showing header, QR code, map, and address table

Walking Order Optimization

Walk sheets sort addresses in walking order to minimize backtracking.

Algorithm:

Start at center of cut
Find nearest unvisited address
Move to that address
Repeat until all addresses covered

This creates an efficient route similar to the GPS route in the volunteer portal.

Using Walk Sheets in the Field

Distribute to volunteers:

Print one walk sheet per volunteer (or per pair, if canvassing in pairs)
Bring clipboards and pens
Brief volunteers on how to record outcomes

Volunteers record:

Date visited
Outcome code (NH, R, SW, etc.)
Support level (S1-S4 if spoke with)
Notes (brief comments)

After the canvass:

Collect completed walk sheets
Enter data into system (or scan QR code during canvass for automatic recording)

Monitoring Canvass Progress

Canvass Dashboard

To view overall canvass progress:

Navigate to Canvass > Dashboard

The dashboard shows:

Statistics cards:

Active sessions: Volunteers currently canvassing
Total visits today: Doors knocked today
Completed sessions: Finished sessions today
Average session duration: Time spent canvassing

Activity feed:

Real-time stream of visits
Shows: Volunteer name, address, outcome, timestamp
Updates every 30 seconds

Cut progress table:

Progress by cut (% of locations visited)
Session count per cut
Visit count per cut
Click cut name to view details

Leaderboard:

Top volunteers by visit count
Session count
Success rate (% SPOKE_WITH outcomes)

Screenshot placeholder: Canvass Dashboard showing stats cards, activity feed, cut progress table, and leaderboard

Cut-Level Progress

To view progress for a specific cut:

Navigate to Canvass > Dashboard
Click cut name in cut progress table

Cut detail view shows:

Completion gauge: % of locations visited
Outcome breakdown: Pie chart of outcomes (NOT_HOME, REFUSED, SPOKE_WITH, etc.)
Support levels: Count of LEVEL_1 through LEVEL_4
Visit history: Recent visits in this cut
Active sessions: Volunteers currently canvassing this cut

Export cut data:

Click "Export CSV" to download all visits for this cut
Use for analysis, reporting, follow-up planning

Session Monitoring

To view active canvass sessions:

Navigate to Canvass > Dashboard
Scroll to "Active Sessions" section

Each active session shows:

Volunteer name
Cut being canvassed
Start time
Visit count
Last activity (how long since last visit)

Warning signs:

⚠️ No activity for > 30 minutes (volunteer may be stuck or abandoned session)
⚠️ Very low visit rate (volunteer may need help)

Actions:

Contact volunteer to check in
Manually end session if abandoned

Data Analysis and Reporting

Outcome Analysis

To understand canvassing results:

Navigate to Canvass > Dashboard
View Outcome Breakdown chart

Outcome categories:

NOT_HOME: Nobody answered (typical: 40-60% of visits)
REFUSED: Refused to talk (typical: 5-15%)
SPOKE_WITH: Had a conversation (typical: 20-40%)
MOVED_AWAY: Resident moved (typical: 2-5%)
WRONG_ADDRESS: Address doesn't exist (typical: 1-3%)
DO_NOT_CONTACT: Requested no contact (typical: < 1%)
OTHER: Other situation (typical: < 5%)

Interpreting outcomes:

High NOT_HOME rate (> 60%):

Canvassing at wrong time (try evenings or weekends)
Multi-unit buildings (hard to access)

High REFUSED rate (> 20%):

Issue is unpopular or controversial
Volunteers may need better training on approach
Consider different messaging

Low SPOKE_WITH rate (< 20%):

See above (related to NOT_HOME and REFUSED)
Canvassing at wrong time
Poor volunteer approach

High WRONG_ADDRESS (> 5%):

Data quality issues
Need to clean location database

Support Level Analysis

To understand voter sentiment:

View Support Levels on Canvass Dashboard

Support level breakdown:

LEVEL_1 (Strong support): Target for GOTV (Get Out The Vote)
LEVEL_2 (Leaning support): Persuasion targets
LEVEL_3 (Undecided): Persuasion targets
LEVEL_4 (Opposition): Deprioritize future contact

Targeting strategy:

For GOTV:

Focus on LEVEL_1 (strong support)
Ensure they vote (door knock day before election, offer rides)

For persuasion:

Focus on LEVEL_2 and LEVEL_3 (undecided, leaning)
Provide information, answer questions, invite to events

For opposition:

LEVEL_4: Don't waste time (respect their decision)

Volunteer Performance

To evaluate volunteer effectiveness:

View Leaderboard on Canvass Dashboard

Metrics:

Visit count: Total doors knocked
Session count: Number of canvassing sessions
Success rate: % of visits that resulted in SPOKE_WITH outcome
Average session duration: Time spent canvassing

Identifying top performers:

High visit count + high success rate = Star volunteer (recognize publicly, ask to mentor others)
High visit count + low success rate = May be rushing (provide feedback)
Low visit count + high success rate = Quality over quantity (consider assigning harder areas)

Coaching opportunities:

Low success rate: Offer training on approach, scripting
Short sessions: Ask why (time constraints? Lack of confidence?)
High REFUSED rate: Review volunteer's approach (too pushy? Poor messaging?)

Troubleshooting

Geocoding Issues

Issue: Many locations ungeocoded after import

Solutions:

Review ungeocoded addresses (Data Quality > Export Ungeocoded)
Fix typos and re-import
Configure additional geocoding API keys (Mapbox, Google)
Manually place locations on map

Issue: Locations geocoded to wrong area

Symptoms: Locations appear far from where they should be

Solutions:

Check confidence score (likely low confidence)
Edit location and manually place on map
Re-geocode with better provider (if API key available)

Cut Issues

Issue: Locations not assigning to cut

Symptoms: Locations inside polygon not assigned after cut creation

Solutions:

Verify polygon is properly closed (check vertices)
Check for very complex polygons (may hit algorithm limits)
Manually assign locations using bulk action

Issue: Overlapping cuts

Symptoms: Some locations assigned to wrong cut

Cause: Multiple cuts cover the same area

Solution:

Locations can only belong to one cut
Later cuts override earlier assignments
Redraw cuts to avoid overlap, OR
Accept overlap and use manual assignment for edge cases

Shift Issues

Issue: Volunteer cannot start canvass session

Symptoms: "No active shift found" error

Solutions:

Verify shift date is today
Verify volunteer is signed up for shift
Verify shift has a cut assigned (required for canvassing)
Verify volunteer role is USER (not TEMP)

Issue: Shift signups not appearing

Symptoms: Public signup form doesn't show shift

Solutions:

Check shift start time (past shifts don't appear)
Check max signups (if full, shift is hidden)
Check feature toggle (Settings > Allow Public Shift Signup must be ON)

Canvassing Issues

Issue: Walking route not updating

Symptoms: Route doesn't change after completing visits

Solutions:

Route updates every 30 seconds (wait a moment)
Refresh volunteer's map (pull down)
Check internet connection (route calculation requires server)

Issue: Visit won't save

Symptoms: Volunteer reports "Save Visit" doesn't work

Solutions:

Check internet connection (visits save to server)
Verify outcome is selected (required field)
Check for abandoned session (volunteer may need to start new session)

Admin Guide: Full administrator guide (includes map management)
Volunteer Guide: Guide for volunteers using canvassing portal
Map Module: Technical documentation on locations, geocoding, cuts
Canvassing System: Technical documentation on canvass sessions and GPS tracking
API Reference: Map API endpoints

Last updated: February 2026 (V2 complete)

35 KiB Raw Blame History

Map Organizer Guide

Overview

Understanding Map Roles

SUPER_ADMIN

MAP_ADMIN

Understanding Location Data

What is a Location?

Building vs Unit Level

Data Sources

Importing Locations from CSV

Preparing Your CSV File

Importing the CSV

Troubleshooting Import Issues

NAR Import (Canadian Electoral Data)

What is NAR Data?

Obtaining NAR Data

Importing NAR Data

NAR Data Fields

Creating and Managing Cuts

What is a Cut?

Cut Best Practices

Creating a Cut (Drawing on Map)

Automatic Location Assignment

Editing Cuts

Managing Locations

Viewing and Filtering Locations

Editing a Location

Manually Placing Locations on Map

Bulk Operations

Deleting Locations

Geocoding and Data Quality

Understanding Geocoding

Geocoding Providers

Geocode Confidence Levels

Data Quality Dashboard

Improving Geocoding Quality

Organizing Volunteer Shifts

What is a Shift?

Creating a Shift

Managing Shift Signups

Adding Volunteers to a Shift

Emailing Shift Volunteers

Generating Walk Sheets

What is a Walk Sheet?

Walk Sheet Settings

Generating a Walk Sheet

Walking Order Optimization

Using Walk Sheets in the Field

Monitoring Canvass Progress

Canvass Dashboard

Cut-Level Progress

Session Monitoring

Data Analysis and Reporting

Outcome Analysis

Support Level Analysis

Volunteer Performance

Troubleshooting

Geocoding Issues

Cut Issues

Shift Issues

Canvassing Issues

Related Documentation

35 KiB

Raw Blame History