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

Administrator Guide

Overview

The Administrator role is the highest-level role in Changemaker Lite. As an administrator, you have complete control over the platform, including:

• User management: Create, edit, suspend, and delete user accounts
• Campaign oversight: Manage all advocacy campaigns and moderate responses
• Location and mapping: Import locations, create territorial cuts, and organize canvassing efforts
• Volunteer coordination: Create shifts, manage signups, and monitor canvassing activity
• Site configuration: Configure global settings, themes, email, and feature toggles
• Content management: Create landing pages, edit email templates, and manage media library
• Monitoring: View queue status, geocoding quality, and system health

This guide will walk you through all administrative functions in Changemaker Lite V2.

---

Getting Started

First Login

When you first access Changemaker Lite, you'll log in at the admin portal URL:

https://app.cmlite.org

Or if running locally:

http://localhost:3000

Default credentials (change immediately after first login):

• Email: admin@example.com
• Password: Admin123!

!!! danger "Security Critical" The default password is publicly known. Change it immediately after your first login to prevent unauthorized access.

Screenshot placeholder: Login page showing email/password fields and "Remember me" checkbox

Dashboard Overview

After logging in, you'll see the Administrator Dashboard, which provides an at-a-glance overview of your platform:

Key dashboard sections:

1. Statistics Cards

   • Total users (breakdown by role)
   • Active campaigns
   • Total locations
   • Active canvass sessions

2. Recent Activity Feed

   • New user registrations
   • Campaign responses
   • Shift signups
   • Canvass visits

3. Quick Actions

   • Create new campaign
   • Import locations
   • Create volunteer shift
   • View email queue

4. System Health

   • API status
   • Database connectivity
   • Redis cache status
   • Queue worker status

Screenshot placeholder: Dashboard showing statistics cards, activity feed, and quick action buttons

Changing Your Password

!!! warning "Required First Step" You must change the default password before performing any other administrative tasks.

To change your password:

1. Click your email address in the top-right corner
2. Select "Change Password" from the dropdown
3. Enter your current password
4. Enter new password (must meet requirements below)
5. Confirm new password
6. Click "Update Password"

Password requirements:

• Minimum 12 characters
• At least one uppercase letter (A-Z)
• At least one lowercase letter (a-z)
• At least one digit (0-9)
• Cannot reuse recent passwords

Screenshot placeholder: Change password modal showing current/new password fields and requirements checklist

Navigating the Admin Interface

The admin interface uses a sidebar navigation with the following sections:

Main Navigation:

• Dashboard — Overview and quick actions
• Influence — Campaigns, responses, representatives, email queue
• Map — Locations, cuts, shifts, map settings, data quality
• Canvass — Dashboard, sessions, activity reports
• Content — Landing pages, email templates, media library
• Services — Listmonk, Pangolin, docs, integrations
• Observability — Monitoring, metrics, alerts
• Users — User management
• Settings — Global site settings

Screenshot placeholder: Sidebar navigation showing expanded Influence and Map sections

---

User Management

Creating Users

To create a new user:

1. Navigate to Users in the sidebar
2. Click "Create User" button (top-right)
3. Fill in user details:
   • Email: User's email address (must be unique)
   • Name: User's full name
   • Password: Temporary password (user should change on first login)
   • Role: Select from dropdown (see roles below)
   • Status: ACTIVE or SUSPENDED
4. Click "Create"

The new user will receive a welcome email (if email is configured) with their login credentials.

Screenshot placeholder: Create User modal showing email, name, password, role dropdown, and status toggle

Understanding Roles

Changemaker Lite has five user roles with different permission levels:

1. SUPER_ADMIN (You)

• Access: Everything
• Capabilities: All administrative functions, user management, site configuration
• Use case: Primary administrator(s)

2. INFLUENCE_ADMIN

• Access: Influence module only
• Capabilities:
  • Create and manage campaigns
  • Moderate responses
  • View representative cache
  • Monitor email queue
• Restrictions: Cannot manage users, locations, or site settings
• Use case: Campaign managers who don't need full admin access

3. MAP_ADMIN

• Access: Map module only
• Capabilities:
  • Import and manage locations
  • Create cuts
  • Organize shifts
  • Monitor canvassing
• Restrictions: Cannot manage users, campaigns, or site settings
• Use case: Field organizers, volunteer coordinators

4. USER

• Access: Volunteer portal only
• Capabilities:
  • View assigned shifts
  • Start canvassing sessions
  • Record door visits
  • View own activity
• Restrictions: Cannot access admin areas
• Use case: Regular volunteers

5. TEMP

• Access: Very limited, volunteer portal only
• Capabilities:
  • Sign up for public shifts (creates TEMP account automatically)
  • Cannot start canvassing sessions
• Restrictions: Cannot access most features until upgraded to USER
• Use case: Anonymous shift signups (converted to USER by admin)

!!! tip "Role Upgrading" You can upgrade TEMP users to USER role to give them full volunteer access. This is common after a volunteer attends their first shift.

Screenshot placeholder: User list table showing users with different roles and color-coded role badges

Managing Existing Users

The Users page shows all user accounts in a searchable, filterable table.

Table columns:

• Name — User's full name
• Email — Login email
• Role — Current role (color-coded badge)
• Status — ACTIVE (green) or SUSPENDED (red)
• Last Login — Most recent login timestamp
• Created — Account creation date
• Actions — Edit, suspend/activate, delete

Available filters:

• Search: Search by name or email
• Role filter: Show only specific roles
• Status filter: Active, suspended, or all
• Date range: Filter by creation date

Screenshot placeholder: Users table with search bar, role filter dropdown, and action buttons

Editing Users

To edit a user:

1. Click the Edit icon (pencil) in the Actions column
2. Modify any of:
   • Name
   • Email (must remain unique)
   • Role (change permissions)
   • Status (activate/suspend)
3. Click "Save"

!!! warning "Email Changes" Changing a user's email will require them to log in with the new email address. Notify them before making this change.

Suspending Users

To temporarily disable a user account:

1. Find the user in the table
2. Click "Suspend" in the Actions column
3. Confirm suspension

Suspended users:

• Cannot log in
• Existing sessions are invalidated immediately
• Can be reactivated at any time
• Data and history are preserved

When to suspend:

• Volunteer is temporarily unavailable
• Security concerns (investigate before deleting)
• User requests account pause

Screenshot placeholder: Suspend confirmation dialog explaining effects

Password Resets

To reset a user's password:

1. Edit the user
2. Click "Reset Password"
3. Choose one of:
   • Generate temporary password (shown on screen, expires in 24 hours)
   • Send reset email (user clicks link to set new password)
4. Provide temporary password to user securely (not via email)

!!! tip "Security Best Practice" Always use "Send reset email" option when possible. Only generate temporary passwords for in-person support scenarios.

Deleting Users

!!! danger "Permanent Action" Deleting a user is permanent and cannot be undone. All associated data (canvass visits, responses, etc.) will be anonymized.

To delete a user:

1. Click the Delete icon (trash) in the Actions column
2. Type the user's email to confirm
3. Click "Delete Permanently"

When deletion is appropriate:

• Duplicate accounts
• Test accounts in production
• User requests account deletion (GDPR compliance)

Data handling on deletion:

• User account record is deleted
• Associated content (responses, visits) remains but user reference is nullified
• Email queue jobs remain (email address is preserved for audit)

Viewing Login Activity

To see recent login activity:

1. Navigate to Users
2. Check the "Last Login" column
3. Click on a user to see detailed login history (if audit logging is enabled)

Screenshot placeholder: User detail view showing login history table with timestamps and IP addresses

---

Campaign Management

Campaign Overview

Campaigns are at the heart of the Influence module. A campaign allows citizens to:

1. Enter their postal code
2. Find their elected representatives
3. Send advocacy emails
4. Share their story on a public response wall

As an administrator, you can create, configure, publish, and monitor campaigns.

Creating a Campaign

To create a new campaign:

1. Navigate to Influence > Campaigns
2. Click "Create Campaign" (top-right)
3. Fill in the campaign form (see fields below)
4. Click "Create"

Required fields:

Basic Information:

• Title: Campaign name (shown to public)
  • Example: "Protect Our Climate"
• Slug: URL-friendly identifier (auto-generated from title)
  • Example: protect-our-climate
  • Used in public URL: /campaigns/protect-our-climate
• Description: Campaign overview (supports HTML)
  • Shown on campaign listing page
  • Recommended: 2-3 sentences

Email Configuration:

• Email Subject: Subject line for advocacy emails
  • Example: "Please support climate action legislation"
  • Variables supported: {{USER_NAME}}, {{REP_NAME}}
• Email Body: The email message citizens send
  • HTML editor available
  • Variables: {{USER_NAME}}, {{USER_EMAIL}}, {{REP_NAME}}, {{REP_EMAIL}}, {{USER_MESSAGE}}
  • Preview before publishing

Targeting:

• Government Level: FEDERAL, PROVINCIAL, or MUNICIPAL
  • Determines which representatives are looked up
  • Can select multiple levels

Screenshot placeholder: Create Campaign form showing title, slug, description, email subject, and body editor

Understanding Feature Flags

Campaigns have 12 feature flags that control functionality:

Core Features

1. Published

   • Controls public visibility
   • Unpublished campaigns only visible to admins
   • Toggle to launch/pause campaign

2. Featured

   • Featured campaigns appear at top of listing page
   • Use for high-priority campaigns
   • Limit to 2-3 featured campaigns

3. Has Response Wall

   • Enables public response wall
   • Citizens can share their story after emailing
   • Responses require admin approval (unless auto_approve_responses)

4. Collect Phone Numbers

   • Adds optional phone number field
   • Used for call-in campaigns
   • Numbers stored for admin use

5. Track Calls

   • Adds "I called my representative" button
   • Tracks call attempts separately from emails
   • Good for blended campaigns

Advanced Features

6. Require Verification

   • Sends verification email before submitting
   • Prevents spam and bot submissions
   • Recommended for public campaigns

7. Auto Approve Responses

   • Response wall submissions appear immediately
   • No admin moderation required
   • Only use for trusted campaigns

8. Allow Anonymous

   • Citizens can submit without creating account
   • Reduces friction but limits tracking
   • Good for privacy-sensitive topics

9. Custom Recipients

   • Override representative lookup
   • Send to specific email addresses
   • Use for non-government campaigns

10. Show Progress Bar

    • Displays email count goal and progress
    • Motivates participation
    • Requires setting email_goal field

11. Disable After Date

    • Automatically unpublish after specified date
    • Good for time-sensitive campaigns
    • Requires setting disable_date field

12. Enable Comments

    • Allow comments on response wall entries
    • Creates discussion threads
    • Requires moderation

Screenshot placeholder: Campaign feature flags showing toggles for all 12 flags with descriptive labels

!!! tip "Recommended Defaults" For most campaigns, enable: Published, Has Response Wall, Require Verification. Leave others off unless specifically needed.

Configuring Email Template

The email template is what citizens send to their representatives. Make it:

Effective email guidelines:

• Personal: Use variables like {{USER_NAME}} to personalize
• Clear: State the ask in first paragraph
• Specific: Reference specific legislation or issue
• Respectful: Professional tone, even if issue is urgent
• Actionable: Tell representatives exactly what you want them to do

Example template:

Subject: Please vote YES on Bill C-123 for climate action

Dear {{REP_NAME}},

My name is {{USER_NAME}}, and I am a constituent in your riding. I'm writing to urge you to vote YES on Bill C-123, the Climate Action Framework.

Climate change is the defining issue of our generation. This bill provides a realistic pathway to reduce emissions while protecting jobs and supporting workers.

I'm specifically asking you to:
1. Vote YES on Bill C-123 when it comes to the floor
2. Speak publicly in support of climate action
3. Oppose any amendments that weaken the bill

Thank you for considering my views. I look forward to your response.

Sincerely,
{{USER_NAME}}
{{USER_EMAIL}}

---
{{USER_MESSAGE}}

Available variables:

• {{USER_NAME}} — Citizen's full name
• {{USER_EMAIL}} — Citizen's email address
• {{USER_PHONE}} — Citizen's phone (if collected)
• {{REP_NAME}} — Representative's name
• {{REP_EMAIL}} — Representative's email
• {{REP_TITLE}} — Representative's title (MP, MPP, Councillor)
• {{USER_MESSAGE}} — Custom message from citizen (optional field)

Screenshot placeholder: Email template editor showing subject and body fields with variable insertion dropdown

Publishing a Campaign

Before publishing, verify:

• Email template is proofread (send test email to yourself)
• Feature flags are configured correctly
• Representative lookup is working (test with your postal code)
• Response wall moderation is ready (if enabled)

To publish:

1. Edit the campaign
2. Toggle "Published" flag to ON
3. Click "Save"

The campaign is now live at /campaigns/[slug].

Promoting your campaign:

• Share direct link: https://yourdomain.org/campaigns/protect-our-climate
• Embed in email newsletter
• Post on social media
• Add to landing page

Screenshot placeholder: Published campaign card on public campaigns listing page

Monitoring Email Sends

To view email statistics:

1. Navigate to Influence > Campaigns
2. Click "Emails" button in the Actions column for your campaign

The Campaign Emails drawer shows:

Statistics:

• Total emails sent
• Successful deliveries
• Failed deliveries
• Emails waiting in queue

Email list table:

• Recipient name and email
• Status (PENDING, SENT, FAILED)
• Sent timestamp
• Representative targeted
• Error message (if failed)

Actions:

• Retry failed: Re-queue failed emails
• Export CSV: Download full email list

Screenshot placeholder: Campaign Emails drawer showing statistics cards and email list table

Managing the Email Queue

The email queue processes advocacy emails asynchronously using BullMQ.

To monitor queue health:

1. Navigate to Influence > Email Queue

Queue statistics:

• Waiting: Emails queued but not yet processing
• Active: Emails currently being sent
• Completed: Successfully sent emails (last 24 hours)
• Failed: Failed emails requiring retry
• Delayed: Scheduled for future sending

Queue controls:

• Pause Queue: Stop processing new emails (emergencies only)
• Resume Queue: Restart after pause
• Clean Completed: Remove old completed jobs (frees memory)
• Retry Failed: Re-queue all failed emails

!!! warning "Queue Pausing" Only pause the queue during system maintenance or if email configuration is broken. Citizens expect immediate sends.

Screenshot placeholder: Email Queue page showing statistics cards, job counts, and control buttons

Moderating Responses

If your campaign has "Has Response Wall" enabled, citizens can share their stories publicly.

To moderate responses:

1. Navigate to Influence > Responses
2. Use filters to find pending responses
3. Review each response
4. Approve or reject

Response filters:

• Campaign: Filter by specific campaign
• Status: PENDING, APPROVED, REJECTED
• Search: Search response text
• Date range: Filter by submission date

Response table columns:

• Name: Citizen's name
• Campaign: Which campaign
• Status: Approval status (color-coded)
• Upvotes: Number of upvotes received
• Submitted: Submission date
• Actions: View, approve, reject, delete

Screenshot placeholder: Responses table with filter controls and status badges

To review a response:

1. Click "View" in Actions column
2. Read full response text
3. Decide:
   • Approve: Make public (appears on response wall)
   • Reject: Hide from public (not deleted)
   • Delete: Permanently remove

Moderation guidelines:

Approve responses that:

• Are authentic personal stories
• Relate to the campaign issue
• Use respectful language
• Add value to the public conversation

Reject responses that:

• Contain profanity or hate speech
• Are spam or off-topic
• Violate privacy (include private information about others)
• Are duplicate submissions

Screenshot placeholder: Response detail modal showing full text, citizen info, and approve/reject buttons

---

Location Management

Location Data Overview

Locations represent physical addresses where canvassing occurs. Each location has:

• Address: Street address, city, province, postal code
• Coordinates: Latitude/longitude (from geocoding)
• Metadata: Building type, federal district, unit count
• Cut assignment: Which territorial cut it belongs to
• Canvass history: Visits, outcomes, support levels

Importing Locations from CSV

To import locations:

1. Navigate to Map > Locations
2. Click "Import CSV" button
3. Upload CSV file
4. Map CSV columns to location fields
5. Click "Import"

Required CSV columns:

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

Optional columns:

• latitude — Pre-geocoded latitude
• longitude — Pre-geocoded longitude
• buildingType — RESIDENTIAL, APARTMENT, BUSINESS
• unitCount — Number of units in building
• federalDistrict — Electoral district
• notes — Internal notes

CSV example:

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

!!! tip "Excel to CSV" If your data is in Excel, use "Save As" > "CSV (Comma delimited)" to export.

Screenshot placeholder: CSV import dialog showing file upload, column mapping interface, and preview table

NAR Import (Canadian Electoral Data)

For Canadian campaigns, you can import official electoral data from Elections Canada NAR (National Address Register) files.

To import NAR data:

1. Navigate to Map > Locations
2. Click "NAR Import" button
3. Select province
4. Choose NAR dataset (year)
5. Apply filters:
   • City filter (optional)
   • Postal code filter (optional)
   • Cut filter (assign to specific cut)
   • Residential only (exclude commercial)
6. Click "Start Import"

The import runs server-side and can take several minutes for large provinces.

NAR data includes:

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

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

!!! note "NAR Data Source" NAR data must be obtained from Elections Canada and placed in the /data directory on the server. Contact your system administrator.

Geocoding Addresses

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

Automatic geocoding:

• CSV imports without lat/lng are automatically geocoded
• NAR imports include pre-geocoded coordinates
• Manual location creation triggers geocoding

Manual geocoding:

1. Navigate to Map > Locations
2. Filter for "Ungeocoded" locations
3. Select locations to geocode
4. Click "Geocode Selected" (bulk action)

Geocoding providers (tried in order):

1. Nominatim (OpenStreetMap) — Free, no API key required
2. ArcGIS — Free tier, accurate for North America
3. Photon — Free, Europe-focused
4. Mapbox — Requires API key, very accurate
5. Google — Requires API key, most accurate
6. LocationIQ — Requires API key, Nominatim-based

!!! tip "Geocoding Quality" Check Map > Data Quality to review geocoding confidence levels. Re-geocode low-confidence addresses.

Screenshot placeholder: Locations table with "Geocode Selected" button and geocoding status column

Creating Cuts

Cuts are geographic areas (wards, neighborhoods, districts) used to organize canvassing.

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 point)
6. Fill in cut details:
   • Name: Cut identifier (e.g., "Ward 5", "Downtown")
   • Category: WARD, NEIGHBORHOOD, DISTRICT, or CUSTOM
   • Color: Display color on map
   • Description: Internal notes
7. Click "Save Cut"

Cut best practices:

• Size: 200-500 locations per cut (manageable for canvassing)
• Boundaries: Use natural boundaries (roads, rivers, parks)
• Naming: Use official ward/district names when available
• Colors: Use distinct colors for adjacent cuts

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

Assigning Locations to Cuts

Automatic assignment (during cut creation):

• Locations inside polygon are automatically assigned
• Uses point-in-polygon algorithm

Manual assignment:

1. Navigate to Map > Locations
2. Select locations to assign
3. Choose "Assign to Cut" from bulk actions
4. Select target cut
5. Click "Assign"

Viewing cut assignments:

• Location table has "Cut" column
• Filter locations by cut using dropdown

Screenshot placeholder: Bulk action modal showing "Assign to Cut" with cut selector dropdown

Managing Locations

To edit a location:

1. Navigate to Map > Locations
2. Click "Edit" in Actions column
3. Modify fields:
   • Address details
   • Coordinates (manually adjust map pin)
   • Building type
   • Unit count
   • Notes
   • Cut assignment
4. Click "Save"

To delete locations:

1. Select locations in table
2. Choose "Delete" from bulk actions
3. Confirm deletion

!!! warning "Canvass History" Deleting a location preserves associated canvass visits (visits are linked to coordinates, not location records).

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

Exporting Walk Sheets

Walk sheets are printable lists of addresses for door-to-door canvassing.

To generate a walk sheet:

1. Navigate to Map > Locations
2. Filter to specific cut
3. Click "Walk Sheet" in the cut's action menu

OR:

1. Navigate to Canvass > Walk Sheet
2. Select cut from dropdown
3. Configure settings (see below)
4. Click "Print"

Walk sheet settings (from Map > Map Settings):

• Header text: Organization name, campaign info
• Instructions: How to use the walk sheet
• QR code: Include QR code linking to volunteer canvass map
• Sorting: Sort by street name or walking route
• Include map: Embed cut map on first page

Walk sheet contents:

• Cut name and statistics
• QR code (volunteers scan to start canvass session)
• Location table:
  • Address
  • Unit count
  • Last visit date
  • Last outcome
  • Notes field (blank for volunteers to fill)

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

---

Volunteer Management

Creating Shifts

Shifts are scheduled volunteer canvassing sessions assigned to specific cuts.

To create a shift:

1. Navigate to Map > Shifts
2. Click "Create Shift"
3. Fill in shift details:
   • Title: Shift name (e.g., "Saturday Morning Canvass - Ward 5")
   • Description: Additional details for volunteers
   • Start Time: Shift start date and time
   • End Time: Shift end date and time
   • Cut: Which cut to canvass (optional, but recommended)
   • Max Signups: Capacity limit (0 = unlimited)
   • Meeting Location: Where volunteers should meet
4. Click "Create"

Screenshot placeholder: Create Shift modal showing date/time picker, cut selector, and capacity field

!!! tip "Cut Assignment" Shifts assigned to a cut appear in the volunteer portal under "My Assignments" for volunteers who signed up. Volunteers can start canvassing directly from their dashboard.

Managing Shift Signups

To view shift signups:

1. Navigate to Map > Shifts
2. Click "Signups" in Actions column

The signups drawer shows:

• Total signups vs capacity
• Signup list: Name, email, role, signup date
• Actions: Remove signup, upgrade TEMP users to USER

Signup sources:

• Public signup form: /shifts page (creates TEMP users)
• Admin-created: You manually add volunteers
• Volunteer portal: USER-role volunteers sign up themselves

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

Emailing Shift Volunteers

To email all volunteers in a shift:

1. Navigate to Map > Shifts
2. Click "Signups" for the shift
3. Click "Email All" button
4. Compose email:
   • Subject: Email subject line
   • Body: Message (supports HTML)
   • Variables: Use {{NAME}}, {{SHIFT_TITLE}}, {{SHIFT_START}}
5. Click "Send"

Common email scenarios:

• Reminder: Day before shift
• Cancellation: Weather or other issues
• Location change: Meeting point updated
• Follow-up: Thank you after shift

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

Monitoring Canvass Sessions

To view active canvass sessions:

1. Navigate to Canvass > Dashboard

The dashboard shows:

Statistics cards:

• Active sessions: Currently in progress
• Total visits today: Doors knocked
• Completed sessions: Finished today
• Average session duration

Activity feed:

• Real-time visit stream
• 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

Leaderboard:

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

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

Viewing Canvass Activity Reports

To see detailed canvassing data:

1. Navigate to Canvass > Dashboard
2. Use filters:
   • Date range: Last 7 days, last 30 days, custom
   • Cut: Specific cut or all
   • Volunteer: Specific volunteer or all
   • Outcome: Filter by visit outcome

Exportable reports:

• Visit history CSV: All visits with outcomes, notes, timestamps
• Support levels CSV: LEVEL_1 through LEVEL_4 breakdown
• Session summary CSV: Session duration, visit count, volunteer info

Screenshot placeholder: Activity report filters and export buttons

---

Site Configuration

Site Settings

To configure global site settings:

1. Navigate to Settings (gear icon in sidebar)

Available settings:

Branding:

• Site Name: Your organization name
• Site URL: Public website URL
• Logo URL: URL to your logo image
• Primary Color: Brand color (hex code)
• Secondary Color: Accent color

Email Configuration:

• From Name: Sender name for system emails
• From Email: Sender email address
• SMTP Host: Email server hostname
• SMTP Port: Usually 587 (TLS) or 465 (SSL)
• SMTP Username: SMTP authentication username
• SMTP Password: SMTP authentication password
• Test Mode: Send to MailHog instead of real SMTP (dev only)

Representative API:

• Represent API Base URL: Usually https://represent.opennorth.ca
• API Key: If required by provider
• Cache TTL: How long to cache representative data (hours)

Feature Toggles:

• Enable Media Features: Enable video library and media management
• Enable Listmonk Sync: Sync contacts to Listmonk newsletter platform
• Allow Public Shift Signup: Anyone can sign up for shifts (creates TEMP users)
• Require Email Verification: Campaign responses require email confirmation

Screenshot placeholder: Settings page showing branding, email, and feature toggle sections

!!! tip "Test Email Configuration" After changing SMTP settings, click "Send Test Email" to verify configuration before publishing campaigns.

Map Settings

To configure map defaults:

1. Navigate to Map > Map Settings

Map Configuration:

• Default Center: Latitude/longitude for map center
  • Used on public map and admin map
  • Usually your city center
• Default Zoom: Zoom level (1-18)
  • 12 = city-wide view
  • 15 = neighborhood view
• Enable Fullscreen: Allow fullscreen button on public map
• Enable Geolocation: Allow "Find My Location" button

Walk Sheet Configuration:

• Header Text: Appears at top of walk sheets
• Footer Text: Appears at bottom
• Include QR Code: Add QR code linking to volunteer map
• QR Code Size: Small, medium, or large
• Instructions: Text explaining how to use walk sheet

Screenshot placeholder: Map Settings page showing map center picker and walk sheet config

Feature Toggles

Feature toggles allow you to enable/disable major platform features without code changes.

To manage feature toggles:

1. Navigate to Settings
2. Scroll to Feature Toggles section
3. Toggle features on/off
4. Click "Save"

Available toggles:

ENABLE_MEDIA_FEATURES

• Enables Media Library and video management
• Shows Media menu in sidebar
• Allows video uploads and public media gallery
• Requires media-api service running

ENABLE_LISTMONK_SYNC

• Enables newsletter integration
• Syncs campaign participants to Listmonk lists
• Shows Listmonk menu in sidebar
• Requires Listmonk service configured

ALLOW_PUBLIC_SHIFT_SIGNUP

• Public can sign up for shifts at /shifts
• Creates TEMP user accounts automatically
• Shows shifts on public pages
• Disable for invitation-only volunteering

REQUIRE_EMAIL_VERIFICATION

• Campaign responses require email verification
• Prevents spam and fake submissions
• Sends verification link before recording response
• Recommended for public campaigns

Screenshot placeholder: Feature Toggles section showing four toggles with descriptions

!!! warning "Media Features" Enabling media features requires the media-api Docker container to be running. Check with your system administrator.

---

Email Templates

Understanding Email Templates

Changemaker Lite uses email templates for system-generated emails:

System templates:

• Welcome Email: Sent to new users
• Password Reset: Sent when user requests password reset
• Shift Confirmation: Sent when volunteer signs up for shift
• Shift Reminder: Sent day before shift
• Response Verification: Sent to verify campaign response

Custom templates:

• You can create custom templates for specific needs
• Use in shift emails, campaign follow-ups, etc.

Editing Templates

To edit an email template:

1. Navigate to Content > Email Templates
2. Click "Edit" for the template
3. Modify:
   • Subject: Email subject line
   • HTML Body: Rich email content
   • Plain Text Body: Fallback for text-only clients
4. Use variables (e.g., {{USER_NAME}}, {{SHIFT_TITLE}})
5. Click "Preview" to see rendered email
6. Click "Save"

Screenshot placeholder: Email Template Editor showing subject field, HTML editor, and variable buttons

Available Variables

Templates support variable interpolation:

User variables:

• {{USER_NAME}} — User's full name
• {{USER_EMAIL}} — User's email address

Shift variables:

• {{SHIFT_TITLE}} — Shift name
• {{SHIFT_START}} — Start date/time
• {{SHIFT_END}} — End date/time
• {{SHIFT_LOCATION}} — Meeting location
• {{SHIFT_CUT}} — Cut name

Campaign variables:

• {{CAMPAIGN_TITLE}} — Campaign name
• {{CAMPAIGN_URL}} — Link to campaign page

System variables:

• {{SITE_NAME}} — Your organization name
• {{SITE_URL}} — Website URL

Screenshot placeholder: Variable reference table in template editor sidebar

Testing Templates

To test an email template:

1. Edit the template
2. Click "Send Test Email"
3. Enter your email address
4. Click "Send"

You'll receive the email with sample data filled in for variables.

!!! tip "Always Test" Test templates before using them in production. Check both HTML and plain text versions.

---

Media Library

!!! note "Optional Feature" Media features must be enabled via Settings > Feature Toggles > ENABLE_MEDIA_FEATURES. Requires media-api service.

Uploading Videos

To upload a video:

1. Navigate to Content > Media > Library
2. Click "Upload Video"
3. Either:
   • Drag and drop video file
   • Click to browse and select file
4. Fill in metadata:
   • Title: Video title
   • Description: Video description
   • Producer: Organization or creator
   • Creator: Individual creator/director
   • Tags: Comma-separated tags
   • Directory: Organize into folders
5. Click "Upload"

Supported formats:

• MP4 (recommended)
• MOV
• AVI
• MKV
• WebM
• M4V
• FLV

File size limit: 10 GB per file

Screenshot placeholder: Upload Video modal showing drag-drop area, metadata form, and progress bar

Automatic Metadata Extraction

When you upload a video, the system automatically extracts:

• Duration: Length in seconds
• Dimensions: Width x height in pixels
• Orientation: PORTRAIT, LANDSCAPE, or SQUARE
• Quality: SD, HD, FULL_HD, or 4K
• Has Audio: Boolean
• File Size: Bytes

This metadata is used for filtering and organizing videos.

Organizing the Library

Directory structure:

• Create directories to organize videos
• Directories are simple text paths (e.g., "events/2024", "testimonials")
• Set directory when uploading or editing

Filtering videos:

• Search: Search title, description, tags
• Directory: Filter by directory
• Quality: Filter by SD, HD, etc.
• Orientation: Portrait, landscape, square
• Locked: Show only locked or unlocked

Sorting:

• Upload date (newest first)
• Title (A-Z)
• Duration (shortest first)

Screenshot placeholder: Media Library showing directory tree, filters, and video grid

Sharing Videos Publicly

To make videos public:

1. Navigate to Content > Media > Shared Media
2. Select videos from library
3. Choose category:
   • TESTIMONIAL
   • EVENT
   • EDUCATIONAL
   • PROMOTIONAL
4. Click "Share"

Shared videos appear on the public media gallery at /media.

To unshare videos:

1. Go to Shared Media
2. Select videos
3. Click "Unshare"

Screenshot placeholder: Shared Media page showing category filter and share/unshare buttons

Locking Videos

Locked videos cannot be deleted or moved. Use locks to protect important content.

To lock a video:

1. Select video in library
2. Click "Lock" (padlock icon)

To unlock:

1. Select locked video
2. Click "Unlock"

!!! warning "Lock Before Sharing" Lock videos before sharing publicly to prevent accidental deletion.

---

Monitoring & Reports

Viewing Queue Status

To monitor the email queue:

1. Navigate to Influence > Email Queue

Key metrics:

• Waiting: Emails queued for sending
  • High number = slow processing (check SMTP)
• Active: Currently processing
  • Should be 1-5 (concurrent workers)
• Completed: Sent in last 24 hours
• Failed: Delivery failures
  • Click "View Failed" to see error messages

Queue health indicators:

• Green: < 50 waiting, < 5 failed
• Yellow: 50-200 waiting, 5-20 failed
• Red: > 200 waiting, > 20 failed

Screenshot placeholder: Email Queue dashboard showing job counts with color-coded health indicators

Geocoding Quality Dashboard

To review geocoding quality:

1. Navigate to Map > Data Quality

Quality metrics:

• Total locations: All location records
• Geocoded: Have lat/lng coordinates
• Ungeocoded: Missing coordinates
• Low confidence: Confidence < 0.5
• Medium confidence: 0.5-0.8
• High confidence: > 0.8

Quality breakdown:

• Provider distribution: Which geocoding service was used
• Confidence histogram: Distribution of confidence scores
• Error analysis: Common geocoding failures

Actions:

• Re-geocode low confidence: Retry with different provider
• Export ungeocoded: CSV of failed addresses
• Manual review: Edit addresses and re-geocode

Screenshot placeholder: Data Quality Dashboard showing geocoding statistics and confidence distribution chart

Canvass Completion Statistics

To view canvass progress:

1. Navigate to Canvass > Dashboard

Completion metrics:

• Locations visited: Total unique addresses visited
• Visit rate: Visits per day/week
• Completion by cut: % of each cut visited
• Outcome breakdown: % NOT_HOME, REFUSED, SPOKE_WITH, etc.

Support level analysis:

• LEVEL_1 (Strong support): Count and percentage
• LEVEL_2 (Leaning support): Count and percentage
• LEVEL_3 (Undecided): Count and percentage
• LEVEL_4 (Opposition): Count and percentage

Volunteer performance:

• Sessions per volunteer: Distribution histogram
• Visits per volunteer: Leaderboard
• Average session duration: Time spent canvassing

Screenshot placeholder: Canvass statistics showing completion gauges, outcome pie chart, and support level breakdown

Observability Dashboard

To monitor system health:

1. Navigate to Observability

The observability dashboard has three tabs:

Metrics Tab

• Custom metrics: 12 cm_* Prometheus metrics
  • API uptime
  • Request counts
  • Email queue size
  • Active sessions
  • Geocoding success rate
• HTTP metrics: Request duration, status codes
• System metrics: CPU, memory, disk

Screenshot placeholder: Metrics tab showing API uptime gauge and request count graph

Dashboards Tab

• Links to Grafana dashboards:
  • API Health (uptime, response times, error rates)
  • Queue Monitoring (email queue, geocoding queue)
  • Canvassing Activity (sessions, visits, outcomes)
• Click dashboard name to open in Grafana

Screenshot placeholder: Dashboards tab showing three dashboard cards with "Open" buttons

Alerts Tab

• Active alerts: Currently firing alerts
• Alert history: Recent resolved alerts
• Alert rules: Configured thresholds
• Silence alerts: Temporarily mute alerts

Common alerts:

• API Down: API not responding
• High Error Rate: > 5% requests failing
• Queue Backed Up: > 1000 emails waiting
• Disk Space Low: < 10% free space

Screenshot placeholder: Alerts tab showing active alert for "Queue Backed Up" with severity and details

---

Troubleshooting

Common Admin Issues

Issue: Cannot Log In

Symptoms: "Invalid credentials" error

Solutions:

1. Verify email address: Check for typos, spaces
2. Try password reset: Use "Forgot Password" link
3. Check account status: Ask another admin if account is suspended
4. Check browser console: Look for API errors

Issue: Emails Not Sending

Symptoms: Emails stuck in "Waiting" status

Solutions:

1. Check SMTP configuration:
   • Navigate to Settings
   • Verify SMTP host, port, username, password
   • Click "Send Test Email"
2. Check email queue:
   • Navigate to Influence > Email Queue
   • Look for error messages in failed jobs
3. Check email test mode:
   • If EMAIL_TEST_MODE=true, emails go to MailHog (not real recipients)
   • Change in environment settings
4. Restart queue worker:
   • Ask system administrator to restart api service

Issue: CSV Import Fails

Symptoms: Error during CSV upload

Solutions:

1. Check CSV format:
   • Must be valid CSV (comma-separated)
   • First row must be headers
   • Required columns: address, city, province, postalCode
2. Check file encoding:
   • Use UTF-8 encoding
   • Excel users: "Save As" > "CSV UTF-8"
3. Check file size:
   • Maximum 10,000 rows per import
   • Split large files
4. Check for special characters:
   • Remove emoji, unusual symbols
   • Use standard quotes ("not "" or '')

Issue: Geocoding Fails

Symptoms: Addresses remain ungeocoded after import

Solutions:

1. Check address format:
   • Include full civic address
   • Include city and postal code
   • Use standard abbreviations (St, Ave, Rd)
2. Check geocoding providers:
   • Navigate to Map > Data Quality
   • See which providers are responding
3. Try manual geocoding:
   • Edit location
   • Click and drag map pin to correct position
   • Save
4. Use NAR data (Canada only):
   • NAR import includes pre-geocoded coordinates
   • More reliable than automatic geocoding

Issue: Map Not Loading

Symptoms: Blank map or loading spinner

Solutions:

1. Check browser console: Look for JavaScript errors
2. Check internet connection: Map tiles require network
3. Try different browser: Test in Chrome, Firefox
4. Clear browser cache: Hard refresh (Ctrl+Shift+R)
5. Check locations:
   • Navigate to Map > Locations
   • Verify locations have coordinates
   • At least one location needed to display map

Issue: Campaign Not Appearing Publicly

Symptoms: Campaign visible in admin but not on /campaigns

Solutions:

1. Check "Published" flag:
   • Edit campaign
   • Ensure "Published" toggle is ON
   • Save
2. Check URL:
   • Campaign URL is /campaigns/[slug]
   • Slug is auto-generated from title
   • Must be unique
3. Clear browser cache: Public pages may be cached
4. Check representative lookup:
   • Test with your postal code
   • If lookup fails, campaign won't display form

Issue: Volunteer Cannot Start Canvass Session

Symptoms: Error when volunteer clicks "Start Canvassing"

Solutions:

1. Check shift assignment:
   • Navigate to Map > Shifts
   • Verify shift has a cut assigned
   • Shifts without cuts cannot be canvassed
2. Check volunteer role:
   • Navigate to Users
   • Verify volunteer is USER role (not TEMP)
   • Upgrade TEMP users to USER
3. Check cut locations:
   • Navigate to Map > Cuts
   • Verify cut has locations assigned
   • Empty cuts cannot be canvassed
4. Check for existing session:
   • Volunteer may have abandoned session
   • Ask admin to close abandoned session

Getting Help

Documentation:

• Feature docs: /docs/v2/features/ (detailed feature guides)
• API reference: /docs/v2/api/ (API endpoint documentation)
• User guides: /docs/v2/user-guides/ (this guide and others)
• Deployment: /docs/v2/deployment/ (server setup, Docker, backups)

Support channels:

• GitHub Issues: Report bugs, request features
• Community Forum: Ask questions, share tips
• Email Support: Contact your system administrator

Before asking for help:

1. Check browser console for errors (F12)
2. Try in different browser
3. Check server logs (if you have access)
4. Document steps to reproduce issue

---

Related Documentation

• Volunteer Guide: Guide for volunteers using the canvassing portal
• Campaign Manager Guide: Deep dive on campaign strategy and management
• Map Organizer Guide: Advanced location and territory management
• Content Editor Guide: Landing pages and media library
• Influence Module: Technical details on campaigns and email sending
• Map Module: Technical details on geocoding and canvassing
• API Reference: REST API documentation for integrations

---

Last updated: February 2026 (V2 complete)