Skip to content

People CSV Import Guide

Overview

The People CSV Import feature allows you to bulk import person records into the system using CSV (Comma-Separated Values) files. This feature is perfect for adding multiple people at once, such as new employees, contractors, or visitors.

Quick Start

  1. Navigate to People Section: Go to the People section in the main menu
  2. Click Import Button: Click the "Import" button in the Quick Actions panel
  3. Download Template: Click "Download CSV Template" to get a sample file
  4. Prepare Your Data: Fill in the template with your people data
  5. Upload File: Select your CSV file and click "Upload CSV"
  6. Review Results: Check the import summary and download error reports if needed

CSV File Format

Required Fields

These fields must be included in your CSV file:

Field Description Example
name Person's full name John Doe
email Valid email address john.doe@company.com
type Person type employee, visitor, contractor, guest, vendor

Optional Fields

These fields can be included but are not required:

Field Description Example
phone Phone number +1234567890
identification_document ID document number 123456789
identification_document_type Type of ID document passport, driver_license, national_id
access_levels Access level IDs (separated by semicolons) level-1;level-2
lists List IDs (separated by semicolons) list-1;list-2
vehicles Vehicle information (separated by semicolons) ABC123;XYZ789
departments Department names (separated by semicolons) Engineering;Development
activation_date Start date (YYYY-MM-DD format) 2024-01-01
expiration_date End date (YYYY-MM-DD format) 2024-12-31
timezone Timezone (UTC format) UTC-5, UTC+1
disabled Account status true, false, 1, 0, yes, no

CSV Template

Sample CSV File

name,email,type,phone,identification_document,identification_document_type,access_levels,lists,vehicles,departments,activation_date,expiration_date,timezone,disabled
John Doe,john.doe@company.com,employee,+1234567890,123456789,passport,level-1;level-2,list-1;list-2,ABC123;XYZ789,Engineering;Development,2024-01-01,2024-12-31,UTC-5,false
Jane Smith,jane.smith@company.com,visitor,+0987654321,987654321,driver_license,level-3,list-3,DEF456,Marketing,2024-01-15,2024-06-30,UTC+1,false
Bob Johnson,bob.johnson@company.com,contractor,+1122334455,112233445,national_id,level-1,list-1,GHI789,IT,2024-02-01,2024-11-30,UTC,true

Step-by-Step Import Process

Step 1: Access the Import Feature

  1. Navigate to the People section in the main menu
  2. Look for the Quick Actions panel on the right side
  3. Click the Import button (📥 icon)

Step 2: Download the Template

  1. In the import modal, click "Download CSV Template"
  2. Save the template file to your computer
  3. Open the file in Excel, Google Sheets, or any text editor

Step 3: Prepare Your Data

  1. Fill in Required Fields:

    • name: Enter the person's full name
    • email: Enter a valid email address
    • type: Choose from: employee, visitor, contractor, guest, vendor

  2. Add Optional Information:

    • Phone numbers in international format
    • ID document information
    • Access levels and lists (use semicolons to separate multiple values)
    • Department information
    • Activation and expiration dates
    • Timezone information

  3. Save the File:

    • Save as CSV format
    • Ensure UTF-8 encoding
    • Keep the header row

Step 4: Upload Your File

  1. In the import modal, click "Choose File"
  2. Select your prepared CSV file
  3. Click "Upload CSV"
  4. Wait for the upload to complete

Step 5: Review Results

  1. Check the Summary:

    • Total records processed
    • Successful imports
    • Processing time

  2. Handle Errors (if any):

    • Review error details in the table
    • Download error report for detailed analysis
    • Fix issues in your CSV file
    • Re-upload the corrected file

Data Validation Rules

Email Addresses

  • Must be in valid email format (e.g., user@domain.com)
  • Must be unique across all records
  • Cannot be empty

Person Types

Valid types include:

  • employee - Company employees
  • visitor - Temporary visitors
  • contractor - External contractors
  • guest - Guests and temporary access
  • vendor - Vendor representatives

Dates

  • Format: YYYY-MM-DD (e.g., 2024-01-15)
  • Activation date should be before expiration date
  • Both dates are optional

Timezones

  • Format: UTC, UTC+1, UTC-5, etc.
  • Range: UTC-12 to UTC+14
  • Examples: UTC, UTC+1, UTC-5, UTC+8

Boolean Values

For the disabled field, you can use:

  • true, false
  • 1, 0
  • yes, no

Best Practices

Data Preparation

  1. Use the Template: Always start with the provided template
  2. Validate Emails: Ensure all email addresses are valid and unique
  3. Check Dates: Verify date formats and logical date ranges
  4. Test with Small Files: Start with a few records to test the process
  5. Backup Data: Keep a backup of your original data

File Format

  1. Encoding: Use UTF-8 encoding to handle special characters
  2. Headers: Always include the header row
  3. Delimiters: Use commas to separate fields
  4. Multiple Values: Use semicolons (;) to separate multiple values in a field
  5. File Size: Keep files under 10MB for optimal performance

Content Guidelines

  1. Names: Use full names (first and last name)
  2. Emails: Use official company email addresses when possible
  3. Phone Numbers: Include country codes for international numbers
  4. Access Levels: Verify access level IDs exist in the system
  5. Lists: Ensure list IDs are valid

Troubleshooting

Common Errors

"Invalid email format"

  • Cause: Email address doesn't follow standard format
  • Solution: Check email format (user@domain.com)
  • Example: john.doe@company.com ✅, john.doe ❌

"Invalid person type"

  • Cause: Person type is not one of the allowed values
  • Solution: Use only: employee, visitor, contractor, guest, vendor
  • Example: employee ✅, staff ❌

"Duplicate email address"

  • Cause: Email already exists in the system
  • Solution: Use unique email addresses or update existing records
  • Note: Check if the person already exists in the system

"Invalid date format"

  • Cause: Date is not in YYYY-MM-DD format
  • Solution: Use format like 2024-01-15
  • Example: 2024-01-15 ✅, 15/01/2024 ❌

"File too large"

  • Cause: CSV file exceeds 10MB limit
  • Solution: Split the file into smaller chunks
  • Recommendation: Import in batches of 100-500 records

"Invalid timezone format"

  • Cause: Timezone format is incorrect
  • Solution: Use UTC format (UTC, UTC+1, UTC-5, etc.)
  • Example: UTC-5 ✅, EST ❌

Error Report Analysis

When errors occur, download the error report to see:

  • Row Number: Which line in your CSV has the error
  • Field: Which field contains the error
  • Message: Description of the error
  • Value: The problematic value

Getting Help

If you encounter issues:

  1. Check the Error Report: Download and review the detailed error report
  2. Verify Data: Double-check your CSV data against the validation rules
  3. Test with Template: Try importing the sample template first
  4. Contact Support: If problems persist, contact your system administrator

Import Results

Success Indicators

  • ✅ All records imported successfully: No errors occurred
  • ⚠️ Partial success: Some records imported, some failed
  • ❌ Import failed: No records were imported

Understanding the Summary

  • Total Records: Number of rows in your CSV file
  • Successful Records: Number of people successfully added
  • Processing Time: How long the import took
  • Errors Found: Number of records with issues

After Import

  1. Verify Data: Check that imported people appear in the people list
  2. Review Access: Verify access levels and lists are correctly assigned
  3. Test Access: Ensure people can access appropriate areas
  4. Update if Needed: Make any necessary adjustments to individual records

Export Functionality

Exporting Current Data

You can also export the current people data:

  1. Apply Filters: Use search and type filters to narrow down the data
  2. Click Export: Click the "Export" button in Quick Actions
  3. Download: The filtered data will be downloaded as a CSV file

Export Features

  • Respects Filters: Only exports currently visible data
  • Same Format: Uses the same CSV format as import
  • Smart Filenames: Includes date and filter information
  • All Fields: Includes all person information fields

Security Considerations

Data Privacy

  • Sensitive Information: Be careful with personal data in CSV files
  • Secure Transfer: Use secure methods to transfer CSV files
  • Access Control: Ensure only authorized users can import data
  • Audit Trail: Import activities are logged for security purposes

File Security

  • Virus Scanning: Scan CSV files before upload
  • Source Verification: Only use CSV files from trusted sources
  • File Validation: The system validates file content before processing

Advanced Tips

Bulk Operations

  • Large Imports: For large datasets, consider importing in batches
  • Scheduled Imports: Plan imports during off-peak hours
  • Data Validation: Use spreadsheet formulas to validate data before import

Integration

  • HR Systems: Export data from HR systems in CSV format
  • Spreadsheet Tools: Use Excel or Google Sheets for data preparation
  • Automation: Consider automated CSV generation for regular imports

Maintenance

  • Regular Updates: Keep person data up to date
  • Clean Data: Remove outdated or duplicate records
  • Backup: Regularly backup your people data

Support and Resources

Additional Help

  • System Documentation: Check the main system documentation
  • Training Materials: Review available training resources
  • Support Team: Contact your IT support team for assistance

Contact Information

For technical support or questions about CSV imports:

  • Email: [support@company.com]
  • Phone: [Support Phone Number]
  • Hours: [Support Hours]

This guide covers the basic CSV import functionality. For advanced features or specific use cases, please consult with your system administrator.