Workforce Import Guide

Bulk workforce onboarding via CSV at /hrms/migration/workforce.

Where to find import

People Hub → Workforce migration (or /hrms/migration/workforce). Link from onboarding checklist.

Template

Download: /hrms/migration/workforce/template.csv

File on disk: templates/import/workforce_import_v1.csv

Required columns

Column	Notes
`external_employee_id`	Stable ID for updates
`first_name`, `last_name`
`email`	Unique per organisation
`department`	Must match existing department name
`hire_date`	`YYYY-MM-DD`

Optional columns

Column	Purpose
`job_title`
`location`	Text location
`manager_email`	Resolved in pass 2
`leave_policy_code`	Default policy if omitted
`holiday_calendar_code`
`working_pattern_code`	e.g. `STANDARD`
`opening_balance_days`	Migrated leave balance
`phone`
`country_code`	Per-employee override

Country-specific fields

Template is global; country onboarding sets org defaults. Per-row country_code optional.

Workflow

Upload — select CSV and import mode
Validate — POST validate; returns errors/warnings JSON
Preview — human review of counts
Confirm — commit in batches of 50
Complete — summary + audit ID

Errors vs warnings

Errors — row rejected (bad date, unknown department, duplicate email)
Warnings — row may commit (e.g. manager not found yet if ordered incorrectly — prefer manager exists first)

Duplicate behaviour

create_only — existing email → error
create_or_update — match external_employee_id, update fields

Manager references

manager_email must match another row’s email or existing employee. Second pass links manager_id.

Retry

Failed batch: fix CSV, re-validate, confirm again. Audit log preserves history.

Reconciliation

Compare row count in preview vs directory. Check /hrms/migration/workforce/audit for per-batch status.

Example (fictional)

external_employee_id,first_name,last_name,email,department,hire_date,manager_email,opening_balance_days
EMP001,Alex,Example,alex@example.com,Engineering,2024-01-15,,5
EMP002,Jordan,Sample,jordan@example.com,Engineering,2024-03-01,alex@example.com,0

ILLUSTRATIVE EXAMPLE — not real customer data.

Help

/help/workforce-import