upskill-event-manager/docs/TRAINER-IMPORT.md

HVAC Trainer CSV Import Documentation

This document explains how to import trainers from a CSV file into the HVAC Community Events plugin.

Overview

The import system consists of three main components:

1. Preview Script - Analyzes CSV data without making changes
2. Import Script - Performs the actual import with full error handling
3. Wrapper Script - Provides a user-friendly interface for running imports

Files

• bin/import-trainers-from-csv.php - Main import script
• bin/preview-csv-import.php - Preview and analysis script
• scripts/import-trainers.sh - User-friendly wrapper script
• CSV_Trainers_Import_1Aug2025.csv - Data file to import

CSV Format

The CSV file must contain the following columns:

Column	Required	Description
Name	Yes	First name
Last Name	Yes	Last name
Work Email	Yes	Email address (used as unique identifier)
Company Name	No	Company/organization name
Role	No	Job title/role
Date Certified	No	Certification date (various formats supported)
Certification Type	No	Type of certification
Certification Status	No	Active/Expired/etc.
Country	No	Country
State	No	State/province
City	No	City
Training Audience	No	Who they train
Organizer Category	No	Type of organization
Company Website	No	Website URL
Phone Number	No	Phone number
Application Details	No	Additional details
User ID	No	Suggested username
Create Venue	No	"yes" to create venue record
Create Organizer	No	"yes" to create organizer record

Import Process

Step 1: Preview the Import

Before running the actual import, use the preview script to analyze the data:

# On staging server
wp eval-file bin/preview-csv-import.php

# Or locally with WP-CLI
wp eval-file bin/preview-csv-import.php

The preview will show:

• Total records found
• How many venues/organizers will be created
• Existing users that will be updated
• Data quality analysis
• Sample records

Step 2: Run the Import

Option A: Using the Wrapper Script (Recommended)

./scripts/import-trainers.sh

This script will:

• Check if the CSV file exists
• Detect if you're on staging vs local
• Ask for confirmation
• Run the import with proper error handling
• Show results summary

Option B: Direct WP-CLI Execution

# On staging server
wp eval-file bin/import-trainers-from-csv.php --path=/home/974670.cloudwaysapps.com/uberrxmprk/public_html

# Or locally with WP-CLI
wp eval-file bin/import-trainers-from-csv.php

What the Import Does

User Management

• Existing Users: Updates information if user exists (matched by email)
• New Users: Creates new WordPress user with hvac_trainer role
• User Fields: Sets both standard WordPress fields and HVAC plugin meta fields
• Passwords: Generates secure random passwords for new users
• No Emails: Prevents WordPress from sending notification emails during import

Venue Creation

• When: Only when Create Venue column = "yes"
• Name Format: "{Company Name} {City, State}"
• Example: "HVAC U Southfield, Michigan"
• Fields: Company info, location, website (excludes phone numbers)
• Author: Sets the imported user as the venue author
• Duplicates: Checks for existing venues to prevent duplicates

Organizer Creation

• When: Only when Create Organizer column = "yes"
• Name Format: "{Company Name}"
• Example: "HVAC U"
• Fields: Company info, email, website (excludes phone numbers)
• Author: Sets the imported user as the organizer author
• Duplicates: Checks for existing organizers to prevent duplicates

HVAC Plugin Meta Fields

The import populates these custom meta fields for each user:

• hvac_role - Job title/role
• hvac_company_name - Company name
• hvac_certification_date - Certification date
• hvac_certification_type - Type of certification
• hvac_certification_status - Certification status
• hvac_country - Country
• hvac_state - State
• hvac_city - City
• hvac_training_audience - Training audience
• hvac_organizer_category - Organization type
• hvac_company_website - Website URL
• hvac_phone_number - Phone number
• hvac_application_details - Additional details

Output and Reporting

The import script provides detailed output:

🚀 Starting HVAC Trainer CSV Import...
📄 File: CSV_Trainers_Import_1Aug2025.csv

📊 Found 44 records to process

⏳ Processing row 2: Brynn Cooksey...
  👤 Created new user: brynn@hvactrain.com (username: brynn.cooksey)
  📋 Updated user meta fields
  🏢 Created venue: HVAC U Southfield, Michigan
  🏛️  Created organizer: HVAC U
✅ Row 2 completed successfully

[... continues for all records ...]

============================================================
📊 IMPORT SUMMARY
============================================================
👤 Users imported: 25
📝 Users updated: 19
🏢 Venues created: 17
🏛️  Organizers created: 19
❌ Errors: 0

✅ Import completed!

Error Handling

• Individual Failures: If one record fails, the import continues with the remaining records
• Detailed Errors: Each error includes the row number and specific error message
• Rollback: No automatic rollback - WordPress users/posts are created permanently
• Email Prevention: All WordPress email notifications are disabled during import

Post-Import Actions

After a successful import:

1. New Users: Will need to reset their passwords via the login page
2. Testing: Verify imported users can login at /training-login/
3. Data Verification: Check user profiles, venues, and organizers were created correctly
4. Clean Up: Remove the CSV file if it contains sensitive information

Safety Features

• Duplicate Prevention: Won't create duplicate users, venues, or organizers
• Data Sanitization: All input data is properly sanitized
• Email Suppression: No notification emails sent during import
• Preview Mode: Can analyze data without making changes
• Detailed Logging: Complete record of all actions taken

Troubleshooting

Common Issues

"CSV file not found"

• Ensure CSV_Trainers_Import_1Aug2025.csv is in the project root directory

"Failed to create user"

• Check if email addresses are valid and unique
• Verify username doesn't already exist

"No data found in CSV"

• Check CSV file format and encoding
• Ensure headers are present in first row

WP-CLI not found

• Install WP-CLI or run scripts directly on staging server

Testing Locally

To test the import process locally:

1. Set up local WordPress with HVAC plugin
2. Ensure WP-CLI is installed
3. Place CSV file in project root
4. Run preview script first: wp eval-file bin/preview-csv-import.php
5. Run import: wp eval-file bin/import-trainers-from-csv.php

Security Considerations

• Sensitive Data: CSV may contain personal information - handle securely
• Staging First: Always test on staging before production
• Backup: Consider backing up user database before large imports
• Access Control: Only run imports with appropriate admin privileges

Current Import Data (August 1, 2025)

The current CSV contains:

• 44 total records
• 17 venues to create (first ~17 records have Create Venue = "yes")
• 19 organizers to create (first ~17 plus a few others have Create Organizer = "yes")
• Mix of US and Canadian users
• Two certification types: "Certified measureQuick Trainer" and "Certified measureQuick Champion"