Contact Import & Export

Bulk Contact Import #

CSV and Excel File Import #

The system provides comprehensive bulk contact import capabilities for efficient contact management:

Supported File Formats:

• CSV Files: Standard comma-separated values format
• Excel Files: Both .xls and .xlsx formats supported
• File Validation: Automatic format detection and validation
• File Size Limits: Reasonable file size limits for performance

Import Process Overview:

• File Upload: Upload contact files through the bulk upload interface
• Header Parsing: Automatic detection and parsing of file headers
• Field Mapping: Map file columns to contact database fields
• Data Import: Batch processing for efficient contact creation

Import Authorization:

• Contact creation permissions required for import operations
• Team-based access control for import functionality
• User authentication required for all import operations
• Authorization checks before processing import files

Import Workflow #

The contact import process follows a structured workflow:

Step 1: File Upload and Parsing

• Upload CSV or Excel files through the bulk upload modal
• Automatic file format validation (csv, xls, xlsx only)
• Header extraction and row count calculation
• File parsing with error handling for invalid formats

Step 2: Field Mapping Configuration

• Display of detected file headers for mapping
• Available contact fields presented for mapping selection
• Mapping validation to prevent duplicate column assignments
• Option to map all headers or only required columns

Step 3: Data Processing and Import

• Contact data transformation using ContactDTO objects
• Batch processing for efficient database operations (100 contacts per batch)
• Individual contact creation fallback for failed batch operations
• Import success tracking with total imported count

Import Field Mapping #

Mapping File Columns to Contact Fields #

The field mapping system provides flexible column-to-field assignment:

Mapping Configuration:

• Column Index: Numerical index of columns in the uploaded file
• Column Name: Original header name from the uploaded file
• Mapped Column: Target contact field for data assignment
• Mapping Validation: Required mapping specification for all used columns

Available Contact Fields:

• All standard contact fields available for mapping through ContactDTO
• Personal fields: first_name, last_name, email, phone, birth_date
• Business fields: company_name, website, description
• Address fields: address_line_1, city, zip, country
• Social fields: skype, telegram, linkedin
• System fields: client_id, outreach_id, company_id

Mapping Validation Rules:

• Required Mappings: Each mapping must specify index and mapped column
• Duplicate Prevention: Same contact field cannot be mapped to multiple columns
• Column Validation: Mapped columns must be valid contact fields
• Index Validation: Column indices must be valid integers

Advanced Mapping Features #

The mapping system includes sophisticated validation and error prevention:

Mapping Validation:

• Duplicate Detection: Prevents mapping multiple file columns to same contact field
• Complete Mapping: Validates that all required mappings are specified
• Column Consistency: Ensures mapped columns exist in contact field list
• Mapping Completeness: Validates all file headers have mapping assignments

Error Prevention:

• Frontend validation prevents invalid mapping configurations
• Real-time validation feedback during mapping setup
• Clear error messages for mapping conflicts
• Mapping validation before import processing begins

Flexible Mapping Options:

• Optional field mapping allows partial data import
• Empty column mapping skips unused file columns
• Flexible mapping supports various file structures
• Custom field integration for extended data mapping

Import Validation #

Data Validation and Error Handling #

The import system includes comprehensive validation and error handling:

File Validation:

• Format Validation: Only CSV, XLS, and XLSX files accepted
• File Structure: Header row detection and validation
• Data Integrity: Row-by-row data validation during processing
• Error Recovery: Graceful handling of file parsing errors

Data Validation During Import:

• Contact Data Validation: Each contact validated against contact creation rules
• Required Field Checking: First name requirement enforced during import
• Email Format Validation: Email addresses validated for proper format
• Field Length Validation: Field length limits enforced during import

Batch Import Error Handling:

• Batch Processing: 100 contacts processed per batch for efficiency
• Batch Failure Recovery: Individual contact creation fallback for failed batches
• Success Tracking: Count of successfully imported contacts maintained
• Error Isolation: Failed contacts don’t prevent successful contact import

Import Error Recovery #

The system provides robust error recovery mechanisms:

Batch Processing Benefits:

• Large imports processed in manageable batches
• Batch failures don’t prevent other batches from succeeding
• Memory efficiency for large contact import operations
• Performance optimization for bulk operations

Individual Contact Fallback:

• Failed batch operations fall back to individual contact creation
• Individual contact errors are logged but don’t stop import process
• Partial import success allows maximum contact import completion
• Detailed error logging for troubleshooting failed contacts

Error Reporting:

• Failed contacts logged with detailed error information
• Import success count provided for verification
• Error messages returned for user feedback
• Comprehensive logging for debugging import issues

Contact Export #

Exporting Contact Data for External Use #

The contact system supports data export for external analysis and backup:

Export Integration:

• Contact data available through search and filtering APIs
• JSON format export for API integration
• Contact search results can be exported programmatically
• Team-based export filtering for proper access control

Export Data Structure:

• Contact data exported with all standard fields
• Custom field values included in export data
• Client relationship information included
• Pipeline association data available in exports

Export Access Control:

• Export operations require appropriate contact permissions
• Team-based filtering ensures proper data access
• User ownership filtering available for restricted exports
• Authorization checks for all export operations

Export Features and Capabilities #

Contact export integrates with broader system functionality:

Search-Based Export:

• Export filtered contact lists based on search criteria
• Team-specific contact export with proper access control
• Contact data includes relationships and associations
• Flexible export based on user permissions and access

API Integration:

• Contact data available through API endpoints for external integration
• JSON format for easy integration with external systems
• Search functionality supports programmatic contact access
• Real-time contact data export capabilities

Import Logging #

Tracking and Debugging Import Operations #

The import system includes comprehensive logging for monitoring and debugging:

Import Process Logging:

• File Parser Logging: Dedicated file-parser log channel for file processing
• Contact Import Logging: Dedicated contacts log channel for import operations
• Row Processing: Individual row processing logged for debugging
• Mapping Logging: Field mapping configuration logged for verification

Detailed Log Information:

• File Processing: File headers, row counts, and parsing results
• Mapping Data: Complete mapping configuration and applied mappings
• Contact Data: Individual contact data transformation and creation
• Batch Operations: Batch processing results and success/failure tracking

Error Logging and Debugging:

• File Parsing Errors: Detailed error logging for file processing failures
• Import Failures: Comprehensive error logging for failed contact imports
• Individual Contact Errors: Specific error messages for failed contact creation
• Stack Trace Logging: Complete error context for debugging

Import Monitoring and Analysis #

The logging system supports import monitoring and performance analysis:

Performance Monitoring:

• Batch Performance: Monitoring of batch processing efficiency
• Import Success Rates: Tracking of successful vs. failed imports
• Processing Time: Performance metrics for import operations
• Error Patterns: Analysis of common import failure patterns

Import Analytics:

• Import Volume: Tracking of contact import volumes over time
• Success Metrics: Analysis of import success rates and patterns
• Error Analysis: Identification of common import issues
• Performance Optimization: Data for optimizing import processes

Troubleshooting Support:

• Detailed Error Context: Complete error information for issue resolution
• Import Tracing: Full audit trail of import operations
• Data Validation Logging: Validation failure tracking and analysis
• System Health Monitoring: Import system performance and reliability tracking