changemaker.lite/mkdocs/docs/v2/user-guides/map-organizer-guide.md

# 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:**

```csv
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:**

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

**Excel to CSV:**

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

### Importing the CSV

**To import locations:**

1. Navigate to **Map > Locations**
2. Click **"Import CSV"** button (top-right)
3. Upload your CSV file (drag-drop or browse)
4. Map CSV columns to location fields
5. Preview imported data (first 10 rows shown)
6. 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:**

1. System validates each row (checks required fields)
2. Skips invalid rows (logs errors)
3. Creates location records
4. Geocodes addresses (if lat/lng not provided)
5. 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:

1. Contact Elections Canada Open Data team
2. Request latest NAR dataset (e.g., "NAR 2025 Server")
3. Download Address and Location files
4. 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:**

1. Navigate to **Map > Locations**
2. Click **"NAR Import"** button
3. Select province (e.g., Ontario)
4. Choose dataset (if multiple years available)
5. Apply filters (see below)
6. 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:**

1. System scans NAR files for selected province
2. Joins Address and Location files on `LOC_GUID` (internal Elections Canada ID)
3. Filters by city, postal code (if specified)
4. Converts coordinates from EPSG:3347 (Lambert projection) to WGS84 (lat/lng)
5. Creates location records
6. 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:**

1. Navigate to **Map > Cuts**
2. Click the **"Map Drawing"** tab
3. Click **"Start Drawing"**
4. Click on the map to add polygon vertices
5. Close the polygon (click near first vertex)
6. Fill in cut details (see form below)
7. Click **"Save Cut"**

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

**Drawing tips:**

1. **Start at a corner**: Begin at a distinct landmark (intersection, park corner)
2. **Follow roads**: Click along roads and boundaries
3. **Use zoom**: Zoom in for precision, out for overview
4. **Closing detection**: System detects when you're near the first point and offers to close
5. **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:

1. Checks which locations fall inside the polygon (point-in-polygon algorithm)
2. Assigns those locations to the cut
3. 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:**

1. Navigate to **Map > Cuts**
2. Click **"Edit"** in Actions column
3. Modify name, category, color, or description
4. Click **"Save"**

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

**To delete a cut:**

1. Click **"Delete"** in Actions column
2. 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:**

1. 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:**

1. Click **"Edit"** in Actions column
2. Modify fields (see below)
3. 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:

1. Edit the location
2. Use the map at the bottom of the form
3. Drag the red pin to the correct position
4. Latitude and longitude fields update automatically
5. Click **"Save"**

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

### Bulk Operations

**To perform bulk actions:**

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

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

### Deleting Locations

**To delete locations:**

1. Select locations in table (or filter and select all)
2. Choose **"Delete"** from bulk actions
3. 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:

1. **Nominatim** (OpenStreetMap) — Free, no API key, global coverage
2. **ArcGIS** — Free tier, accurate for North America
3. **Photon** — Free, Europe-focused
4. **Mapbox** — Requires API key, very accurate
5. **Google Geocoding** — Requires API key, most accurate
6. **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:**

1. 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**

1. Export ungeocoded locations (CSV)
2. Review addresses in Excel
3. Fix typos, formatting errors
4. 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**

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

---

**Strategy 3: Manually Place Locations**

1. Filter locations with confidence < 0.5
2. Edit each location
3. Find correct position on map (use satellite view)
4. Drag pin to correct location
5. 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:**

1. Navigate to **Map > Shifts**
2. Click **"Create Shift"**
3. Fill in shift details (see below)
4. 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:**

1. Navigate to **Map > Shifts**
2. 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:**

1. **Public signup form** (`/shifts` page):
   - Anyone can sign up
   - Creates TEMP user account automatically
   - Sends confirmation email

2. **Admin-added**:
   - You manually add volunteers
   - Select existing users or create new

3. **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:**

1. Click **"Signups"** for the shift
2. Click **"Add Volunteer"**
3. Select existing user from dropdown (or click "Create New User")
4. Click **"Add"**

**Upgrading TEMP users to USER:**

After a TEMP user attends their first shift:

1. Open shift signups
2. Find the TEMP user
3. Click **"Upgrade to USER"**
4. Confirm

This gives them full canvassing access for future shifts.

### Emailing Shift Volunteers

**To email all volunteers in a shift:**

1. Click **"Signups"** for the shift
2. Click **"Email All"**
3. Compose email:
   - Subject
   - Body (HTML supported)
   - Variables: `{{NAME}}`, `{{SHIFT_TITLE}}`, `{{SHIFT_START}}`, `{{MEETING_LOCATION}}`
4. 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:**

1. Navigate to **Map > Map Settings**
2. Scroll to **"Walk Sheet Configuration"**
3. 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:**

1. Navigate to **Canvass > Walk Sheet**
2. Select cut from dropdown
3. Click **"Generate"**
4. Review PDF preview
5. Click **"Print"** or **"Download PDF"**

**OR:**

1. Navigate to **Map > Locations**
2. Filter to specific cut
3. 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:**

1. Start at center of cut
2. Find nearest unvisited address
3. Move to that address
4. 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:**

1. Print one walk sheet per volunteer (or per pair, if canvassing in pairs)
2. Bring clipboards and pens
3. 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:**

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

---

## Monitoring Canvass Progress

### Canvass Dashboard

**To view overall canvass progress:**

1. 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:**

1. Navigate to **Canvass > Dashboard**
2. 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:**

1. Navigate to **Canvass > Dashboard**
2. 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:**

1. Navigate to **Canvass > Dashboard**
2. 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:**

1. 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:**

1. 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:**

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

---

**Issue: Locations geocoded to wrong area**

**Symptoms:** Locations appear far from where they should be

**Solutions:**

1. Check confidence score (likely low confidence)
2. Edit location and manually place on map
3. 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:**

1. Verify polygon is properly closed (check vertices)
2. Check for very complex polygons (may hit algorithm limits)
3. 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:**

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

---

**Issue: Shift signups not appearing**

**Symptoms:** Public signup form doesn't show shift

**Solutions:**

1. Check shift start time (past shifts don't appear)
2. Check max signups (if full, shift is hidden)
3. 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:**

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

---

**Issue: Visit won't save**

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

**Solutions:**

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

---

## Related Documentation

- **[Admin Guide](admin-guide.md)**: Full administrator guide (includes map management)
- **[Volunteer Guide](volunteer-guide.md)**: Guide for volunteers using canvassing portal
- **[Map Module](../features/map.md)**: Technical documentation on locations, geocoding, cuts
- **[Canvassing System](../features/canvassing.md)**: Technical documentation on canvass sessions and GPS tracking
- **[API Reference](../api/map.md)**: Map API endpoints

---

**Last updated**: February 2026 (V2 complete)