# Admin — Practitioner Bulk Upload Format The end-user article [Practitioner — Bulk Upload from Spreadsheet](Practitioner-Bulk-Upload-Spreadsheet) describes how a user runs an upload. This article is for the administrator who prepares the source data or troubleshoots a failed import. It covers the column specifications, what validates and what does not, and how to recover from failures. ## Three uploaders, three formats | Uploader | Path | Required catalogs that must exist in HMIS first | |---|---|---| | Doctors | `/admin/staff/upload_doctors.xhtml` | All Specialities | | Consultants | `/admin/staff/upload_consultants.xhtml` | Doctor Specialities | | Staff | `/admin/staff/upload_staff.xhtml` | Optional: Bank institutions (for column O), Department, Branch | Privilege required: `AdminStaff`. ## Doctor upload column specification | Column | Field | Validation | Notes | |---|---|---|---| | A | Code | None | Short internal code. Optional. If purely numeric it is also captured as the integer code. | | B | Title | Must match a `Title` enum label (Dr., Prof., Mr., Ms., …). | Required. | | C | Name | Non-empty | Required. Becomes `Person.name`. | | D | Registration Number | None — free text. | Optional. | | E | Description | None | Optional. | | F | Sex | Must be `M` or `F`. | Required. | | G | Mobile Number | None | Optional but recommended for SMS. | | H | Speciality | Must match a `Speciality.name` (All Specialities catalog). Case-sensitive. | Required; rows with an unmatched value will appear in the preview without a speciality and will not save. | Action method: `dataUploadController.uploadDoctors`. Save method: `dataUploadController.saveDoctors`. ## Consultant upload column specification Same eight columns as the Doctor upload, with one key difference: the Speciality column must match a `DoctorSpeciality.name` (Doctor Specialities catalog), not a `Speciality.name`. | Column | Field | Notes | |---|---|---| | A | Code | Optional | | B | Title | Required | | C | Name | Required | | D | Registration Number | Optional | | E | Description | Optional | | F | Sex | Required (`M` / `F`) | | G | Mobile Number | Optional | | H | Speciality | Required (Doctor Specialities catalog) | Action method: `dataUploadController.uploadConsultants`. Save method: `dataUploadController.saveConsultants`. ## Staff upload column specification The staff uploader handles non-doctor records (nurses, technicians, cashiers, etc.). It has fifteen columns and runs as a background-polling import for files of any meaningful size. | Column | Field | Required? | Notes | |---|---|---|---| | A | Code | Optional | Internal code. | | B | EPF No | Required | Payroll EPF number. Used for many salary reports. | | C | Title | Required | `Mr.`, `Ms.`, etc. | | D | Name | Required | Display name. | | E | Full Name | Required | Legal full name. | | F | Name with Initials | Required | `X. Y. Surname` form. | | G | Address | Required | Postal address. | | H | Sex | Required | `M` / `F`. | | I | NIC No | Required | National identity card. | | J | DOB | Required | Date of birth. Excel date or ISO. | | K | Date of Retired | Optional | Set if importing already-retired records. | | L | Department | Optional | If supplied, must match an existing Department name. | | M | Branch | Optional | Existing institution name. | | N | Account No | Optional | Salary account number. | | O | Bank | Optional | Bank institution name (must already exist). | Action method: `dataUploadController.uploadStaff`. Save method: `dataUploadController.saveStaff`. The screen also enables `` to refresh the preview every 10 seconds while parsing. ## Preview vs save The Upload step parses the file into an in-memory list. Nothing is committed until the user clicks **Save**. The preview grid is the only place to spot issues before persistence — if the spreadsheet has a typo in a Speciality value, the row appears with an empty Speciality and the user can decide whether to fix and re-upload. There is **no automatic duplicate detection**. Re-uploading the same spreadsheet a second time creates a second set of records. ## What is NOT validated | Field | Reason | |---|---| | Code uniqueness | The system does not check that two rows have different codes. | | EPF No uniqueness | Same. | | NIC uniqueness | Same. | | Department / Branch existence (Staff upload) | If a value does not match, the field is left blank on the record; the row still saves. | | Bank existence (Staff upload column O) | Same. | | Dates (DOB, Date Retired) | The uploader trusts whatever Excel parsed; bad strings end up as `null`. | The administrator is responsible for ensuring the source data is clean before upload. ## Recovering from a bad upload There is no "undo upload" button. If a Save has produced wrong records, the only remedy is to retire the unwanted records: 1. Identify the rows added in error (sort the relevant list by Created At; the newest rows are usually the import batch). 2. Tick them on the **Bulk Delete Staff** screen ([Practitioner — Deactivate and Bulk Delete](Practitioner-Deactivate-and-Bulk-Delete)). 3. Click **Remove Selected**. Soft-deleting hides them from active lists; the records remain in the database. If absolutely necessary, hard-delete the rows with a database administrator's help — but be aware this loses any linked bills, sessions, or audit references. ## Recommended pre-flight steps Before running a real production upload: 1. Open a small test instance (or a test institution) and trial the spreadsheet end-to-end. 2. Confirm the speciality, department, branch, and bank names in the spreadsheet match the catalogs exactly (case-sensitive). 3. Confirm the Title column matches recognised values. 4. Check that no two rows share the same EPF No or NIC, since the uploader will not warn you. 5. Save a copy of the file under version control — the system does not retain the source. ## Limitations - No row-level error report. If a row fails to save (e.g., because of a database constraint), the screen does not produce a downloadable error log. - No upload schedule or background queue. Large files block the user's session for the duration of parsing. - No promotion path. A row in the Doctor uploader cannot be marked as "this should be a Consultant"; for consultants, use the Consultant uploader from the start. ## Related articles - [Practitioner — Bulk Upload from Spreadsheet](Practitioner-Bulk-Upload-Spreadsheet) — end-user workflow. - [Admin — Specialities Catalog](Admin-Specialities-Catalog) - [Admin — Doctor Specialities Catalog](Admin-Doctor-Specialities-Catalog) - [Admin — Staff Categories, Designations, Grades](Admin-Staff-Categories-Designations-Grades) - [Practitioner — Deactivate and Bulk Delete](Practitioner-Deactivate-and-Bulk-Delete) [Back to Admin — Practitioner Module Configuration Overview](Admin-Practitioner-Module-Configuration-Overview)