# Admin — Practitioner Module Configuration Overview This article is the administrator's entry point for everything that controls how the practitioner module behaves in HMIS. It does not configure clinical workflows — those are covered by the user-facing articles — but it does cover every catalog, configuration key, privilege, and behaviour switch that an admin tunes when standing up a new installation or adjusting an existing one. End-user navigation is described in [Practitioner Module Overview](Practitioner-Module-Overview). ## What an admin configures | Topic | What you control | Article | |---|---|---| | Speciality catalogs | Two separate lists: All Specialities (for HR) and Doctor Specialities (for channelling). | [Admin — Specialities Catalog](Admin-Specialities-Catalog), [Admin — Doctor Specialities Catalog](Admin-Doctor-Specialities-Catalog) | | Supporting catalogs | Staff Categories, Designations, Grades — used in the full staff editor. | [Admin — Staff Categories, Designations, Grades](Admin-Staff-Categories-Designations-Grades) | | Linking staff to system users | Allow a `WebUser` login to sign bills on behalf of a `Staff` record. | [Admin — Link Staff to System User](Admin-Link-Staff-to-System-User) | | Bulk practitioner imports | Spreadsheet column specs and validation rules. | [Admin — Practitioner Bulk Upload Format](Admin-Practitioner-Bulk-Upload-Format) | | Withholding tax | Configuration keys that drive the WHT panel on every professional payment screen. | [Admin — Withholding Tax Configuration](Admin-Withholding-Tax-Configuration) | | OPD doctor payment behaviour | Whether shift closure is required before paying, marking-in/out gating, refund-aware filters. | [Admin — OPD Doctor Payment Behaviour](Admin-OPD-Doctor-Payment-Behaviour) | | Channel-doctor SMS triggers and templates | The six channel-doctor SMS events and the daily summary for referring doctors. | [Admin — Channel Doctor Notification SMS](Admin-Channel-Doctor-Notification-SMS) | | SMS gateway | URL, credentials, parameter mapping. | [SMS Configuration and Gateway Setup](SMS-Configuration-and-Gateway-Setup) | | Privileges | The minimum set of privileges users need to manage staff, pay doctors, and access reports. | [Admin — Practitioner Privileges and Access](Admin-Practitioner-Privileges-and-Access) | | Soft retire vs hard delete | When the in-app retire is enough and when database-level intervention is appropriate. | [Admin — Retirement vs Hard Delete](Admin-Retirement-vs-Hard-Delete) | | Audit trail | What fields are written for creator/retirer and how to access them. | [Admin — Audit Trail on Practitioner Records](Admin-Audit-Trail-on-Practitioner-Records) | ## Where configuration lives in HMIS HMIS holds configuration in two places that affect this module: 1. **Configuration options.** Key-value pairs in the `ConfigOption` table, edited through the in-app **Application Configuration** screen. The keys mentioned in this article series include: - `Withholding Tax Limit` - `Withholding Tax Percentage` - `Allow User To Select Whether To Pay Withholding Tax During Professional Payments` - `Withholding Tax Calculated Depending On This Month's Payments During Professional Payments` - `Withholding Tax Is Always Calculated During Professional Payments` - `Withholding Tax Is Never Calculated During Professional Payments` - `OPD Doctor Payments can be given without closing the shift.` - `Pay Doctors only After Marking Out` - `Pay Doctors only After Marking In` - `Remove Refunded Bill From OPD Staff Payment` 2. **User preferences / department preferences / institution preferences.** Stored on the `UserPreference` entity (which despite the name is used at multiple scopes). The SMS-related fields described in [Admin — Channel Doctor Notification SMS](Admin-Channel-Doctor-Notification-SMS) and the SMS gateway fields described in [SMS Configuration and Gateway Setup](SMS-Configuration-and-Gateway-Setup) live here. Privileges and roles live in their own tables and are administered through **Administration → Manage Users**. ## Recommended setup order for a new installation If you are standing up a new HMIS instance and need the practitioner module to work end-to-end, follow this order. It avoids the typical chicken-and-egg dependencies. 1. **Privileges.** Create the operator roles and assign `AdminStaff`, `OpdBilling`, `PaymentBilling`, `PaymentBillSearch`, etc. Without `AdminStaff` you cannot even see the staff management screens. See [Admin — Practitioner Privileges and Access](Admin-Practitioner-Privileges-and-Access). 2. **Specialities catalogs.** Populate Doctor Specialities and All Specialities. Most installations duplicate names across both lists. 3. **Staff categories, designations, grades.** Populate the supporting catalogs so the full staff editor's dropdowns are not empty. 4. **Institutions and departments.** Make sure the institutions and departments that will host doctors and consultants exist. 5. **Register doctors / consultants / staff.** Either one at a time or via bulk upload. 6. **Link consultants to institutions** for channelling. 7. **Link staff to system users** so cashiers can be matched to bills. 8. **WHT configuration.** Set the limit, percentage, and default calculation mode. 9. **OPD payment behaviour.** Decide whether shift closure is required. 10. **SMS gateway.** Configure the gateway, then turn on the channel-doctor SMS triggers and templates. 11. **Test.** Run an end-to-end scenario: mark in → bill → pay shift → confirm SMS history. ## Per-scope configuration Some settings can vary by **department** or **institution** rather than being global. This is most relevant for SMS templates and OPD payment behaviour — a branch hospital may want different SMS wording or a different WHT default than the flagship institution. When editing a configuration key, check whether the screen presents a scope picker (global / institution / department); if it does, edit at the level you intend to change. ## Operational checks for ongoing administration These are the periodic checks an administrator typically performs. | Check | When | Where | |---|---|---| | Catalog cleanliness | Quarterly | Specialities catalogs — drop unused ones, merge duplicates outside the UI. | | Retired-but-still-linked records | Monthly | Person-to-institution links for retired consultants; remove leftover links. | | WHT yearly threshold reset | Year-end | Confirm the cutoff is still aligned with current tax policy. | | SMS failures | Daily / weekly | `analytics/sms_faild.xhtml` — escalate gateway issues. | | Bill cancellations of professional payments | Weekly | Verify that cancelled payments correctly reset monthly totals for WHT. | | New user-to-staff link audits | When new users are added | Confirm each `WebUser` who must sign bills is linked to the correct `Staff`. | ## Related articles - [Practitioner Module Overview](Practitioner-Module-Overview) — end-user side. Then read the specific admin articles linked in the table above in the order that matches your task. [Back to Practitioner Module Overview](Practitioner-Module-Overview)