Bulk Import of Guests from Excel File

Bulk Import of Guests from Excel File

The wedding invitation SaaS platform now features a comprehensive bulk import system that allows administrators to efficiently import guest lists from Excel files. This implementation prioritizes data integrity, user experience, and robust error handling while maintaining flexibility for various data formats.

🎥 Video Demo

Watch the bulk import feature in action:

Complete walkthrough of the Excel bulk import feature, including file upload, validation preview, and import process.

Key Features Implemented

📁 Excel File Upload & Parsing

The system supports both .xlsx and .xls file formats with intelligent parsing capabilities:

• Format Support: Handles both modern Excel (.xlsx) and legacy (.xls) formats
• Intelligent Column Mapping: Case-insensitive column detection that supports multiple variations (e.g., “Email”, “email”, “Email Address”, “E-mail”)
• Comprehensive Error Handling: Graceful handling of corrupted files, unsupported formats, and parsing errors

✅ Data Validation & Requirements

Robust validation ensures data quality while providing clear feedback:

• Required Fields: Name is mandatory for all guest entries
• Contact Requirements: At least one contact method (email, phone, or Instagram) must be provided
• Format Validation: Email format validation using standard regex patterns
• Data Cleaning: Automatic Instagram handle cleaning (removes @ prefix if present)
• Range Validation: Max guests validation (1-10 range) with clear error messaging
• Invitation Type Validation: Ensures invitation type is one of CEREMONY, RECEPTION, or BOTH

// Example validation logic
const validateGuestData = (guest: GuestData): ValidationResult => {
  const errors: string[] = [];
  
  if (!guest.name?.trim()) {
    errors.push('Name is required');
  }
  
  if (!guest.email && !guest.phone && !guest.instagram) {
    errors.push('At least one contact method is required');
  }
  
  if (guest.email && !isValidEmail(guest.email)) {
    errors.push('Invalid email format');
  }
  
  return { isValid: errors.length === 0, errors };
};

🔍 Duplicate Detection

Multi-level duplicate prevention ensures data integrity:

• Database Checking: Compares against existing guests using email, phone, and Instagram
• File-level Checking: Prevents duplicates within the same uploaded file
• Intelligent Matching: Case-insensitive comparison with trimmed whitespace

📊 Import Preview Interface

Real-time preview functionality provides immediate feedback:

• Live Data Preview: Shows parsed data immediately after file upload
• Color-coded Status: Visual indicators for valid, invalid, and duplicate entries
• Detailed Error Messages: Specific validation failure descriptions
• Summary Statistics: Displays counts for total, valid, invalid, and duplicate entries

📥 Template System

User-friendly template system with sample data:

• Pre-generated Template: Excel file with 10 diverse sample guests
• Format Demonstration: Shows proper column headers and data formats
• Downloadable Access: Available directly from the import dialog

The template includes varied examples:

• Guests with all contact methods (email, phone, Instagram)
• Guests with single contact methods
• Different invitation types (CEREMONY, RECEPTION, BOTH)
• Various guest count limits (1-10)

🚀 Import Process

Streamlined multi-step wizard interface:

1. Upload Step: File selection and initial parsing
2. Preview Step: Data review with validation status
3. Import Step: Batch processing with real-time progress
4. Complete Step: Detailed success/failure reporting

Files Created/Modified

The implementation involved creating several key components:

• ✅ src/lib/utils/excelParser.ts - Core parsing and validation logic
• ✅ src/components/ImportPreviewTable.tsx - Preview table component with status indicators
• ✅ src/components/BulkImportDialog.tsx - Main import dialog with wizard interface
• ✅ src/components/ui/badge.tsx - Badge component for status display
• ✅ src/app/admin/guests/page.tsx - Added bulk import button to guest management
• ✅ public/templates/guest_import_template.xlsx - Sample template with 10 guests
• ✅ scripts/generateTemplate.js - Automated template generation script

Excel Template Sample Data

The template demonstrates various scenarios with 10 sample guests:

| Name | Email | Phone | Instagram | Max Guests | Invitation Type |
|------|-------|-------|-----------|------------|----------------|
| John & Sarah Smith | john.smith@email.com | +1234567890 | @johnsmith | 2 | BOTH |
| Emily Johnson | emily.j@gmail.com | | @emily_j | 1 | CEREMONY |
| Michael Brown | | +1987654321 | | 4 | RECEPTION |

Usage Workflow

The complete import process follows these steps:

1. Access: Admin navigates to Guest Management page
2. Initiate: Clicks “Bulk Import” button to open import dialog
3. Template: Downloads template for reference (optional)
4. Upload: Selects and uploads Excel file
5. Preview: Reviews parsed data with validation status
6. Import: Confirms import of valid guests
7. Complete: Views detailed import results and completion status

Technical Implementation Highlights

The system architecture emphasizes:

• Performance: Efficient parsing with streaming for large files
• User Experience: Progressive disclosure with clear status indicators
• Error Handling: Graceful degradation with informative error messages
• Data Integrity: Multi-level validation and duplicate prevention
• Flexibility: Support for various column naming conventions

This implementation ensures that administrators can efficiently manage large guest lists while maintaining data quality and providing a smooth user experience. The system handles edge cases gracefully and provides clear feedback throughout the import process, making bulk guest management both powerful and user-friendly.