Importing Users

Overview

The User Import Wizard allows you to bulk import users from a CSV file, saving time when adding multiple employees to your organization. The wizard guides you through a four-step process: uploading your CSV file, mapping columns to user fields, previewing and validating the data, and finally importing the users.

Accessing the Import Wizard

To access the User Import Wizard:

1. Log in to your CitoHR account with an ADMIN role
2. Navigate to Admin in the main navigation
3. Click on Users from the admin menu
4. On the Users page, click the Import Users button (with an upload icon)
5. The User Import Wizard dialog will open

Step 1: Upload CSV File

The first step is to upload your CSV file containing user data:

1. In the Import Wizard, you'll see an upload area with drag-and-drop functionality
2. You can either:
   • Drag and drop your CSV file onto the upload area
   • Click to browse and select your CSV file from your computer
3. The file must be in CSV format (.csv extension)
4. If you don't have a template, click Download Template to get a CSV file with all available fields
5. Once uploaded, the wizard will automatically parse the file and move to the mapping step

Step 2: Map Columns

After uploading, you need to map your CSV columns to CitoHR user fields:

1. The wizard will automatically attempt to map columns based on column names (e.g., "email" → Email field)
2. Review each CSV column and select the corresponding CitoHR field from the dropdown:
   • Name - Full name (required)
   • Email - Email address (required, must be unique)
   • Phone - Phone number
   • Employment Type - FULL_TIME, PART_TIME, CONTRACTOR, etc.
   • Status - ACTIVE, INACTIVE, PENDING
   • Roles - ADMIN, MANAGER, EMPLOYEE (comma-separated for multiple)
   • Department - Department name
   • Job Title - Job title
   • Start Date - Employment start date
   • And many more fields...
3. For columns you don't want to import, select Skip
4. You can use Mapping Presets if your CSV matches a common format (e.g., BreatheHR, Simple format)
5. Some fields support transformations (e.g., converting text to uppercase, parsing dates)
6. Click Validate to proceed to the preview step

Step 3: Preview and Validate

Before importing, review the validation results:

1. The preview shows each row from your CSV with validation results
2. Check for errors (red) - these must be fixed before importing:
   • Missing required fields (Name, Email)
   • Invalid email format
   • Duplicate emails
   • Invalid field values
3. Review warnings (yellow) - these won't prevent import but may need attention:
   • Missing optional fields
   • Unusual data formats
4. If there are errors, go back to Step 2 to fix your CSV file or adjust mappings
5. Optionally, enable Send Invites to automatically send invitation emails to imported users
6. Click Import Users to proceed with the import

Step 4: Import Results

After importing, you'll see a summary of the results:

1. The results page shows:
   • Total Rows - Number of rows processed
   • Successful - Number of users successfully imported
   • Failed - Number of users that failed to import
2. If there are failures, you'll see detailed error messages for each failed row
3. Successfully imported users will appear in the Users list
4. If you enabled "Send Invites", invitation emails will be sent to imported users
5. Click Close or Import More to continue

CSV File Format

Your CSV file should follow these guidelines:

• First row should contain column headers
• Required columns: Name, Email
• Column names can be flexible - the wizard will auto-map common variations
• Date formats: Use standard date formats (YYYY-MM-DD, MM/DD/YYYY, etc.)
• Multiple values: For fields like Roles, use comma-separated values
• Encoding: Use UTF-8 encoding for special characters

Available Import Fields

The following fields can be imported (required fields are marked with *):

Troubleshooting

Common Errors

• Duplicate emails: Each user must have a unique email address. Check for duplicates in your CSV.
• Invalid email format: Ensure all email addresses are in valid format (e.g., user@example.com).
• Missing required fields: Name and Email are required for all users.
• Invalid department: Department names must match existing departments in your organization.
• Invalid date format: Use standard date formats. The wizard will attempt to parse common formats.

Tips for Successful Imports

• Always download and use the template CSV file for the correct structure
• Test with a small file (5-10 users) first before importing large batches
• Review the preview step carefully to catch errors before importing
• Ensure department names match exactly (case-sensitive)
• Use the "Send Invites" option to automatically notify imported users
• Keep a backup of your original CSV file

Related Documentation

• Admin Users Guide - Learn how to manually create and manage users
• Departments - Set up departments before importing users
• Quick Start - Get started with CitoHR