Import system

Import types

Import	Target models	Endpoint
Employee CSV import	`Employee`	`POST /api/v1/employees/import`
Rule set CSV import	`EntitlementRuleSet` + `EntitlementRuleItem`	`POST /api/v1/rule-sets/import`

The Data Import Hub in the portal additionally exposes store, product, category, and product-image imports; see the user guide for that workflow. Every import creates an ImportBatch record tracking row counts and per-row errors.

Employee import

CSV columns

Column	Required	Description
`Employee No.`	Yes	Employee number (upsert key)
`Employee Name and Surname`	Yes	Full name; split into first name and surname
`Store No.` or `Store Name`	Yes	Matched against the client’s stores
`Uniform Category`	Yes	Category for entitlement matching
`Position`	No	Job title
`Department`	No	Matched by name
`Employment Type`	No	`PERMANENT`, `CASUAL`, or `CONTRACT`
`Start Date`	No	Employment start date
`Email` / `Contact Number`	No	Contact details

The parser accepts common header aliases (for example Staff No, Personnel Number, Full Name) in addition to the canonical names above.

Import flow

Partial failure tolerance

Valid rows are imported; invalid rows are skipped with a per-row error message
Existing employees are updated (upsert by employee number); new employees are created
Imports are not rolled back on partial failure
Missing stores can be auto-created when the option is enabled in the import dialog

Scoping

The importer extracts the client from the user’s roles, assigns every imported employee to that client, and validates store references against the client’s stores. Admins may pass an explicit clientId to narrow the target client; it can never widen their scope.

Rule set import

CSV columns

Column	Required	Description
`Client Code`	Yes	Client the rule set belongs to
`Rule Set Name`	Yes	Rule set name (grouping key)
`Effective From` / `Effective To`	Yes / No	Effective period
`Approval Required`	No	Defaults to false
`Replacement Cycle Months`	No	Defaults to 24
`Product Code`	Yes	Product allocated by the row
`Phase`	No	`INITIAL`, `REPLACEMENT`, or `BOTH`
`Qty`	Yes	Quantity per cycle
`Payment`	No	`COMPANY_PAID` or `EMPLOYEE_PAID`

Rows are grouped by client code and rule set name, so one rule set spans multiple rows, each contributing one allocation item. Criteria are not part of the CSV import; they are configured in the Entitlement Rules UI after import.

Validation

Check	Employee import	Rule set import
Required columns present	✅	✅
Data type validation	✅	✅
Foreign key validation (store, client, product)	✅	✅
Upsert on duplicate key (employee number, rule set name)	✅	✅
Client scope validation	✅	✅

Overview

System Architecture

Security

Business Engines

Notifications & Reports

Data

Operations

Engineering

Import types

Employee import

CSV columns

Import flow

Partial failure tolerance

Scoping

Rule set import

CSV columns

Validation

​Import types

​Employee import

​CSV columns

​Import flow

​Partial failure tolerance

​Scoping

​Rule set import

​CSV columns

​Validation

Import types

Employee import

CSV columns

Import flow

Partial failure tolerance

Scoping

Rule set import

CSV columns

Validation