diff --git a/docs/TRAINER-IMPORT.md b/docs/TRAINER-IMPORT.md new file mode 100644 index 00000000..172332fe --- /dev/null +++ b/docs/TRAINER-IMPORT.md @@ -0,0 +1,232 @@ +# 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: + +```bash +# 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) + +```bash +./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 + +```bash +# 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" \ No newline at end of file diff --git a/scripts/import-trainers.sh b/scripts/import-trainers.sh new file mode 100755 index 00000000..88360dee --- /dev/null +++ b/scripts/import-trainers.sh @@ -0,0 +1,89 @@ +#!/bin/bash + +# HVAC Trainer CSV Import Script Wrapper +# Usage: ./scripts/import-trainers.sh + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +echo -e "${BLUE}=== HVAC Trainer CSV Import ===${NC}" +echo "Date: $(date)" +echo "" + +# Check if CSV file exists +CSV_FILE="CSV_Trainers_Import_1Aug2025.csv" +if [ ! -f "$CSV_FILE" ]; then + echo -e "${RED}❌ Error: CSV file '$CSV_FILE' not found in current directory${NC}" + echo "Please ensure the CSV file is in the project root directory." + exit 1 +fi + +echo -e "${GREEN}✅ Found CSV file: $CSV_FILE${NC}" +echo "" + +# Check if we're on staging server +if [[ "$HOSTNAME" =~ "cloudways" ]] || [[ "$PWD" =~ "cloudwaysapps" ]]; then + echo -e "${YELLOW}âš ī¸ Running on staging server${NC}" + STAGING=true +else + echo -e "${BLUE}â„šī¸ Running on local development environment${NC}" + STAGING=false +fi + +echo "" + +# Confirmation prompt +echo -e "${YELLOW}This will import/update users, create venues and organizers from the CSV file.${NC}" +echo -e "${YELLOW}Email notifications will be temporarily disabled during import.${NC}" +echo "" +read -p "Do you want to continue? (y/N): " -n 1 -r +echo "" + +if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo -e "${RED}Import cancelled.${NC}" + exit 1 +fi + +echo "" +echo -e "${BLUE}Starting import...${NC}" +echo "" + +# Run the import script +if [ "$STAGING" = true ]; then + # On staging server, use wp-cli directly + wp eval-file bin/import-trainers-from-csv.php --path=/home/974670.cloudwaysapps.com/uberrxmprk/public_html + RESULT=$? +else + # On local development, check if WP-CLI is available + if command -v wp &> /dev/null; then + wp eval-file bin/import-trainers-from-csv.php + RESULT=$? + else + echo -e "${RED}❌ Error: WP-CLI not found${NC}" + echo "Please install WP-CLI or run this script on the staging server." + exit 1 + fi +fi + +echo "" + +# Check result +if [ $RESULT -eq 0 ]; then + echo -e "${GREEN}✅ Import completed successfully!${NC}" + + if [ "$STAGING" = true ]; then + echo "" + echo -e "${BLUE}🔗 You can now test the imported users at:${NC}" + echo " â€ĸ Login: https://upskill-staging.measurequick.com/training-login/" + echo " â€ĸ Dashboard: https://upskill-staging.measurequick.com/trainer/dashboard/" + echo "" + echo -e "${YELLOW}💡 Note: New users will need to reset their passwords${NC}" + fi +else + echo -e "${RED}❌ Import failed with exit code: $RESULT${NC}" + exit $RESULT +fi \ No newline at end of file