# Employee CSV import

Download a fresh sample from Employees → Import CSV. Its columns and on-screen guide come from the same definition and include the company's active custom fields.

- Automatic employee numbering: leave `employee_number` blank or omit the column. Company prefix, padding, next number and manual-override rules apply. Manual numbering requires a unique employee code. Downloading a sample does not reserve or consume a number.
- Nationality: use an enabled country name or two-letter country code, such as `AE`. The saved value matches the company nationality dropdown. Phone numbers should be spreadsheet Text cells to preserve prefixes and leading zeros.
- Emergency contacts: use separate contact name, relationship, two-letter phone country and national phone number columns. A phone requires both country and national number. Existing encrypted storage and phone validation apply.
- Organization/reporting: use existing `position_code` and `manager_employee_number`, never internal record IDs. Import managers before their reports; manager eligibility, joining dates, reporting rules, position capacity and HR scopes remain enforced. Unavailable or foreign references cause row errors and rollback.
- Hiring source: `direct`, `transfer` or `other`. Recruitment offers continue through Recruitment. `probation_ends_on` requires Career and creates a review task without confirming employment. Boolean columns accept Yes/No, True/False or 1/0. Blank optional flags use normal defaults.

Older supported CSV files remain accepted. Import creates new employees only: existing codes are rejected and records are never overwritten. Photos, private documents, contracts, salaries, account links and passwords use their dedicated workflows and are not accepted as CSV columns.

With automatically generated codes, upload each successful batch only once. Re-uploading it creates new records; the importer does not match existing people by name or email.

Use UTF-8 comma-delimited CSV, at most 500 employees and 2 MB per file. Dates use YYYY-MM-DD. Required custom fields still apply. A failed row rolls back the entire batch, including newly assigned codes and reporting/position records; errors identify CSV record numbers, counting the header as row 1.

The sample contains fictional data. Review its reporting and organizational fields before upload, especially where company policy requires a manager or scoped HR must assign a position. No migration is required for this update.

Verification: 21 SQLite import/onboarding tests (210 assertions), 13 MySQL import tests (116 assertions), and a browser workflow using the actual sample download passed. Mobile/dark layouts were inspected. Full Pint, UTF-8 checks and the production build passed.