> ## Documentation Index
> Fetch the complete documentation index at: https://system.muzemus.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Import system

> Bulk CSV import for employees and entitlement rule sets

## 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](https://doc.muzemus.online/administrator/data-import-hub) 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

```mermaid theme={null}
flowchart TD
    A[Upload CSV] --> B[Parse and validate headers]
    B --> C{Headers recognised?}
    C -->|No| D[Return error with expected format]
    C -->|Yes| E[Validate each row]
    E --> F{Row valid?}
    F -->|Yes| G[Upsert employee by employee number]
    F -->|No| H[Record row error]
    G --> I[ImportBatch with success/error counts]
    H --> I
```

### 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                                  | ✅               | ✅               |