Admin Staff Categories Designations Grades - hmislk/hmis GitHub Wiki
Admin — Staff Categories, Designations, and Grades
Three small but important catalogs sit behind the full staff editor: Staff Category, Designation, and Grade. Their entries populate the dropdowns on the Employment Details tab of the staff editor (/admin/staff/staff.xhtml) and drive grouping in HR and payroll reports. This article describes how each is administered and where each is used.
Why these catalogs matter
The catalogs are not strictly required to register a practitioner — a doctor can be created with neither a designation nor a category — but most reports and many downstream filters expect the values to be set. Bulk staff uploads do not validate against these catalogs, so missing entries will silently leave the field blank.
| Catalog | Entity | Used to express | Used in screens |
|---|---|---|---|
| Staff Category | StaffCategory |
Broad role grouping (Medical, Nursing, Allied Health, Administrative, Support). | Staff editor (Employment Details → Staff Category autocomplete); Staff List grid filter; payroll group reports. |
| Designation | Designation |
Specific job title (House Officer, Senior Nursing Officer, Lab Technologist Grade II). | Staff editor (Employment Details → Designation autocomplete); HR reports; printed name on some bill formats. |
| Grade | Grade |
Pay grade level (Grade 1, Grade 2, etc.). | Used on Staff.grade for payroll calculations. Not exposed on the simpler doctor and consultant editors. |
Navigation
Each catalog has its own screen, reached via Administration → Manage HR (the HR admin index) rather than the Manage Staff index. The HR admin screen is the central administration page for HR-related catalogs.
| Catalog | Path |
|---|---|
| Staff Category | /hr/hr_staff_category.xhtml |
| Designation | /hr/hr_staff_designation.xhtml |
| Grade | /hr/hr_staff_grade.xhtml |
Privilege required: HrAdmin (for the HR admin index) plus AdminStaff to reach the staff editor that consumes the catalogs.
Adding entries
Each catalog screen follows the same pattern HMIS uses for every reference list:
- Open the catalog.
- Click Add.
- Fill in the name and an optional description / income name.
- Click Save.
The new value is immediately available in the staff editor autocompletes.
Editing entries
- Select the value in the listbox.
- Edit name / description.
- Click Save. References update everywhere.
Deleting entries
Soft-delete (sets retired = true). Existing references continue to display the old value; the dropdown stops suggesting it.
Where each catalog is consumed
Staff Category
- Staff editor. Autocomplete field on Employment Details. Uses
staffCategoryController.completeStaffCategory. - Reports. Many HR salary reports group or filter by staff category (e.g.,
staff_payroll_by_department_by_roster.xhtml). - Bulk delete grid. The Bulk Delete Staff screen does not show category, but you can filter the Staff List by category before retiring.
Designation
- Staff editor. Autocomplete on Employment Details. Uses
designationController.completeDesignation. - Print layouts. Some bill / certificate formats include the staff member's designation on the signature line.
- Reports. Used in attendance and leave reports to group staff by job title.
Grade
- Staff editor. Available on the underlying entity but not exposed on the simplified doctor or consultant editors. Use the full staff editor to set Grade.
- Payroll. Most installations key the basic salary off Grade through a
PaysheetComponent. The detail is HR-specific and is not covered here.
Setup recommendations
- Start narrow, broaden as you go. Fewer, more general entries are easier to administer than dozens of granular ones. You can always add more later.
- Match payroll requirements. If your payroll has fixed salary scales by Grade, populate Grade first and ensure each staff member has the right Grade before you start running salary reports.
- Avoid duplicates with different casing. Medical Officer vs medical officer will appear as two values in the catalog but as one effective concept to the user. Either entry's selection will be the one that sticks.
Bulk imports and these catalogs
The bulk Staff upload supports a Department column, but not Staff Category, Designation, or Grade. Uploaded staff get the rest of their fields, then go back into the editor to set category / designation / grade afterward. Doctor and Consultant uploads do not include any of these fields either.
Limitations
- No hierarchy. Each catalog is a flat list.
- No bulk merge. To consolidate two redundant entries, edit each staff member to point at the surviving entry, then retire the duplicate.
- These catalogs do not propagate across institutions — they are global to the HMIS instance.