Data Import/Export Guide
Import employee data from your HRIS or payroll system into Workbench using CSV files. This guide covers everything you need to know about preparing, validating, and importing your data.
Overview
Workbench's data import feature allows you to quickly populate your employee database by importing data from your existing HRIS or payroll system. Instead of manually entering employee information, you can export your data as a CSV file and import it directly into Workbench.
Why Use CSV Import?
CSV import is the most universal format supported by HR and payroll systems. It's fast, reliable, and allows you to import hundreds of employees in minutes rather than hours.
What You Can Import
- Employee personal information (name, email, phone, address)
- Employment details (hire date, department, position, status)
- Reporting relationships (managers and team assignments)
- Compensation data (base salary, hourly rate, bonuses)
- Team memberships
Getting Started
Step 1: Download the Template
Before you start, download the CSV template from your Workbench account. The template includes:
- All available fields with sample data
- Column headers that match Workbench's requirements
- A complete field reference guide (README)
Download Template
Access the template from Settings → Data Import/Export in your Workbench account.
Step 2: Export Your Data
Export your employee data from your HRIS or payroll system. Most systems allow you to export to CSV format. Make sure to include the fields that match Workbench's template structure.
Step 3: Prepare Your CSV File
Open your exported CSV file and ensure it matches the template format:
- Column headers match the template exactly (case-sensitive)
- Required fields (firstName, lastName) are populated
- Dates are in YYYY-MM-DD format
- Boolean values are "true" or "false"
- No empty rows between data
Field Reference
The following table describes all available fields in the import template. Only firstName and lastName are required; all other fields are optional.
| Field | Required | Type | Description |
|---|---|---|---|
| Employee Identification | |||
| employeeId | Recommended | String | Unique identifier from your HR system. Recommended for manager references and updates. |
| firstName | Required | String | Employee's first name |
| lastName | Required | String | Employee's last name |
| middleName | Optional | String | Middle name or initial |
| Contact Information | |||
| personalEmail | Optional | Email address (used for user account linking if employee needs system access) | |
| phoneNumber | Optional | String | Phone number in any format |
| Personal Information | |||
| dateOfBirth | Optional | Date (YYYY-MM-DD) | Date of birth |
| gender | Optional | String | Gender (e.g., Male, Female, Other, Prefer not to say) |
| maritalStatus | Optional | String | Marital status (e.g., Single, Married, Divorced, Widowed) |
| ssn | Optional | String | Social Security Number (will be encrypted in storage) |
| Address Information | |||
| address | Optional | String | Street address |
| city | Optional | String | City |
| state | Optional | String | State or Province |
| zipCode | Optional | String | ZIP or Postal code |
| country | Optional | String | Country |
| Employment Information | |||
| hireDate | Optional | Date (YYYY-MM-DD) | Employee hire date |
| department | Optional | String | Department name |
| position | Optional | String | Job title or position |
| isActive | Optional | Boolean | Whether employee is currently active (true/false, defaults to true) |
| Manager Relationships | |||
| primaryManagerEmployeeId | Optional | String | Primary manager's employeeId. Manager must exist in system or be in same import file. |
| primaryManagerEmail | Optional | Primary manager's email (alternative to employeeId) | |
| secondaryManagerEmployeeId | Optional | String | Secondary manager's employeeId (for dotted-line reporting) |
| secondaryManagerEmail | Optional | Secondary manager's email (alternative to employeeId) | |
| Team Memberships | |||
| teams | Optional | String | Comma-separated list of team names. Teams will be created if they don't exist. |
| Compensation Data | |||
| baseSalary | Optional | Number | Annual base salary amount. Provide either baseSalary OR hourlyRate (not both). |
| hourlyRate | Optional | Number | Hourly rate (alternative to baseSalary). Provide either baseSalary OR hourlyRate (not both). |
| compensationCurrency | Optional | String | Currency code (ISO 4217) for all compensation components. Defaults to USD. |
| bonusAmount | Optional | Number | Bonus amount |
| compensationEffectiveDate | Required if compensation provided | Date (YYYY-MM-DD) | When this compensation becomes effective. Required if any compensation fields are provided. |
| compensationChangeType | Optional | String | Type of compensation change. Options: hiring, promotion, annual, adjustment, import. Defaults to import. |
| compensationChangeReason | Optional | String | Reason for the compensation change |
| compensationNotes | Optional | String | Additional notes about this compensation record |
Field Requirements Summary
- • Required: firstName, lastName
- • Recommended: employeeId (for better matching and manager references)
- • Conditional: compensationEffectiveDate (required if any compensation fields are provided)
- • All other fields: Optional
For detailed field descriptions and examples, download the README file from the Data Import/Export page in your Workbench account.
Step-by-Step Import Process
- Navigate to Data Import/Export
Go to Settings → Data Import/Export in your Workbench account.
- Download the Template
Click "Download CSV Template" to get the template with sample data and field descriptions.
- Prepare Your Data
Fill in the template with your employee data, ensuring all required fields are populated and dates are in the correct format.
- Upload Your File
Drag and drop your CSV file or click to browse. The file will be validated automatically.
- Review Validation Results
Check for any errors or warnings. Fix any issues in your CSV file and re-upload if needed.
- Confirm Import
Once validation passes, click "Confirm Import" to process your data. You'll see a summary of created and updated records.
Common Use Cases
Initial Setup
Import your entire employee roster when first setting up Workbench. Include all employee data, compensation, and reporting relationships.
Bulk Updates
Update employee information for multiple employees at once, such as department changes or position updates.
Compensation Updates
Import new compensation records for annual reviews, promotions, or adjustments. Each record requires an effective date.
New Hires
Add new employees to the system along with their initial compensation and manager assignments.
Troubleshooting
What file format do I need?
Workbench accepts CSV (Comma-Separated Values) files. You can export employee data from most HRIS and payroll systems in CSV format.
Do I need to include all fields?
No. Only firstName and lastName are required. All other fields are optional, though we recommend including employeeId for better matching and manager references.
What happens if I import duplicate employees?
Workbench uses intelligent matching to identify existing employees. If an employee with the same email or employeeId already exists, their record will be updated rather than creating a duplicate.
Can I import compensation data?
Yes! You can include base salary, hourly rate, bonuses, and other compensation components. Each compensation record requires an effective date and will be added to the employee's compensation history.
How do I handle manager relationships?
You can reference managers by their employeeId or email address. Managers must exist in the system or be included in the same import file. Workbench will automatically create the reporting relationships.
What if my import has errors?
The import validation will show you exactly which rows have errors and what needs to be fixed. You can correct the issues in your CSV file and re-upload. Only valid rows will be processed.
Best Practices
- Include employeeId when possible: This helps Workbench match existing employees and resolve manager relationships more accurately.
- Validate before importing: Always review the validation results before confirming the import. Fix any errors to ensure data quality.
- Use consistent date formats: All dates must be in YYYY-MM-DD format (e.g., 2024-01-15).
- Check manager references: Ensure manager employeeIds or emails exist in the system or are included in the same import file.
- Test with a small file first: Import a few employees first to verify the process works correctly before importing your entire roster.
- Keep backups: Always keep a backup of your original CSV file before importing.
Ready to Import Your Data?
Access the Data Import/Export page in your Workbench account to get started.
Sign In to Workbench