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:

```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"