alumni_lookup

Version: 1.0
Last Updated: November 2025
Status: ✅ Complete
Note: This documents the current Champion Signup flow. Much of this will be replaced/reintegrated when the Champion Portal (see planning/champion-portal/) is developed.

Overview

The Champion Signup System provides a complete workflow for alumni to become “Alumni Champions” — volunteer ambassadors for Belmont University. The system spans two domains:

Domain	Audience	Features
`champions.bualum.co`	External Alumni	Multi-step signup wizard
`lookup.bualum.co`	Internal Staff	Management, review, exports

Public Signup Flow
Champion Status & Prospect Management
Staff Management Interface
Email Notifications
CSV Import/Export
Duplicate Detection & Merging
Data Model
Technical Implementation

Wizard Steps

The signup process at champions.bualum.co guides alumni through 5 steps:

Step	Status Value	What’s Collected
1. Welcome	`started` (1)	First name, last name, graduation year
2. Personal Info	`completed_questions` (2)	Contact info, address
3. Questions	`selected_role` (3)	Quiz answers → role recommendation
4. Role Selection	`interests` (4)	Confirmed role choice
5. Interests	`zip_code` (5)	Lifestage interests, completion

Champion Roles

The quiz recommends one of four roles:

Role	Description	Icon
Connection Advisor	1:1 mentorship and career guidance	🤝
Digital Ambassador	Social media and online engagement	📱
Community Builder	Events and local gatherings	🏠
Giving Advocate	Philanthropy and giving campaigns	💝

Completion

Upon completing step 5:

Champion receives a welcome email
Staff receives an admin notification email
Champion can share via SMS link

2. Champion Status & Prospect Management

Status Types

Alumni can have one of four champion-related statuses:

Status	Criteria	Visual Indicator
Completed Champion	ChampionSignup with `status: 5`	Blue border
Signup In Progress	ChampionSignup with `status: 1-4`	Yellow border
Manual Prospect	`prospect_status: 1` without signup	Sky blue border
No Champion Activity	No signup, `prospect_status: 0`	Gray border

Prospect Management

Staff can manually flag alumni as prospects from the alumni show page:

Mark as Prospect — Opens modal to add notes and flag
Remove Prospect Status — Clears flag and notes
Automatic prospects (in-progress signups) are tracked separately

Filtering Options

The alumni search supports 6 status filters:

All Alumni
Champions and Prospects
Completed Champions
Prospects (manual + in-progress)
Manual Prospects Only
Signups In Progress

3. Staff Management Interface

Champion Signups Index (`/champion_signups`)

Features:

Statistics Dashboard — Counts by status, duplicates
Filtering — By status, role, lifestage interest
Sorting — By date, name, status
Bulk Actions — Merge duplicates
Export — CSV download

Shows:

Personal information
Selected role and interests
Quiz answers and responses
Belonging categories and notes
Link to alumni record (if matched)

BUID Linking

Staff can link signups to alumni records by:

Automatic matching by email or name
Manual BUID assignment
Batch import with BUID column

4. Email Notifications

Configuration

# Required environment variables
MAILGUN_API_KEY=your_api_key
MAILGUN_DOMAIN=email.bualum.co
CHAMPION_ADMIN_EMAILS=alumni@belmont.edu,development@belmont.edu
MAILER_FROM_ADDRESS="Belmont University Alumni <noreply@email.bualum.co>"
MAILER_REPLY_TO="Belmont University Alumni <alumni@belmont.edu>"

Email Types

Welcome Email (to champion)

Subject: “You’re officially an Alumni Champion, [First Name]!”
Role-specific guidance
SMS sharing link

Admin Notification (to staff)

Subject: “New Alumni Champion Signup: [Full Name]”
Complete signup information
Link to review in admin

Testing

# Preview emails
http://localhost:3000/rails/mailers/champion_signup_mailer

# Send test emails
rails champion_signup:test_emails

5. CSV Import/Export

Import

Task: rails champion_signups:import[/path/to/file.csv]

Expected columns (case-insensitive):

First Name, Last Name, Last Name when a Student
Graduation Year, Email Address, Phone Number
Street Address, City, State / Province, Postal / Zip Code
Role selection question, Life stage question
Belonging questions, Vocation info
Submission Date

Features:

Maps role descriptions to internal keys
Combines address fields
Converts Yes/No to booleans
Skips duplicates by email
Detailed logging

Export

From /champion_signups index, click “Export CSV”.

Export includes:

Date, status, personal info
Contact info (email, phone, address)
Role selections and interests
Alumni link status (BUID, linked flag)
Respects current filters

6. Duplicate Detection & Merging

Detection

Duplicates are identified by matching BUID (when multiple signups are linked to the same alumni record).

Visual indicators:

Red highlighting in index view
“Has Duplicates” badge
Duplicate count in statistics

Merging Logic

When duplicates are merged:

Most recent signup becomes the target (by created_at)
Older signups are soft deleted (deleted_at set)
Data preservation rules:
- Contact info: use most recent
- Text fields: combine with date tags
- Structured data: use most recent

Merging Tools

Web Interface:

Individual merge buttons per BUID
Bulk merge all duplicates
“Duplicates” filter view

Rake Tasks:

rails champion_signups:stats           # Statistics with duplicate counts
rails champion_signups:duplicates      # Detailed duplicate info
rails champion_signups:merge_all_duplicates  # Merge all
rails "champion_signups:merge_buid[B00123456]"  # Merge specific BUID

7. Data Model

ChampionSignup Table

create_table "champion_signups" do |t|
  t.string "first_name"
  t.string "last_name"
  t.string "graduation_year"
  t.string "email"
  t.string "phone"
  t.string "zip_code"
  t.string "street"
  t.string "city"
  t.string "state"
  t.string "interests"
  t.jsonb "answers", default: {}
  t.string "result_role"
  t.string "selected_role"
  t.string "lifestage_interest"
  t.jsonb "belonging_categories", default: []
  t.text "belonging_note"
  t.string "vocation"
  t.boolean "vocation_help", default: false
  t.string "buid"
  t.datetime "deleted_at"
  t.integer "status", default: 0, null: false
  t.timestamps
end

Status Enum

enum status: {
  started: 1,
  completed_questions: 2,
  selected_role: 3,
  interests: 4,
  zip_code: 5
}

Lifestage Interest Values

Valid keywords (comma-separated):

almost-alumni — Current seniors
young-alumni — 0-10 years since graduating
tower-society — 50+ years since graduating
families — Alumni with young children
other — Any other interests

Alumni Association

# ChampionSignup
belongs_to :alumni, primary_key: :buid, foreign_key: :buid, optional: true

# Alumni
has_many :champion_signups, foreign_key: :buid, primary_key: :buid
enum prospect_status: { not_prospect: 0, prospect: 1 }

8. Technical Implementation

Controllers

Controller	Domain	Purpose
`Champions::ChampionSignupsController`	External	Public signup wizard
`ChampionSignupsController`	Internal	Staff management

Routes

# External (champions.bualum.co)
constraints subdomain: 'champions' do
  scope module: 'champions' do
    resources :signups, controller: 'champion_signups'
    root to: "champion_signups#new"
  end
end

# Internal (lookup.bualum.co)
resources :champion_signups do
  collection do
    get :export_csv
    get :duplicates
    post :merge_duplicates
    post :merge_all_duplicates
  end
end

Services

Service	Purpose
`ChampionSignupMerger`	Handles duplicate merging logic
`Csv::ChampionSignupExporter`	Generates CSV exports

Mailers

Mailer	Method	Purpose
`ChampionSignupMailer`	`welcome_email`	Send to new champion
`ChampionSignupMailer`	`admin_notification`	Notify staff

Rake Tasks

rails champion_signups:stats                    # Show statistics
rails champion_signups:import[file.csv]         # Import from CSV
rails champion_signups:import_july_2025         # Import specific file
rails champion_signups:duplicates               # Show duplicate info
rails champion_signups:merge_all_duplicates     # Merge all duplicates

Data Cleanup

Lifestage Interest Normalization

Legacy data may have full descriptions instead of keywords. Cleanup tasks:

rails data:preview_lifestage_interest_cleanup   # Preview changes
rails data:cleanup_lifestage_interest           # Apply cleanup
rails data:cleanup_lifestage_interest_production  # Production-safe version

Future Development

The Champion Portal (planning/champion-portal/) will expand this system with:

Authenticated champion access
Profile management
Event contributions
Discussion boards
Regional coordination (CLC)

When implemented, the signup flow will integrate with the new portal, and champions will gain access to authenticated features beyond the initial signup.

planning/champion-portal/ — Future Champion Portal specifications
ALUMNI_CONTACT_ID_INTEGRATION.md — CRM Contact ID handling
../development/MODEL_RELATIONSHIPS.md — Database associations