Admin Configuration Overview - hmislk/hmis GitHub Wiki
Configuration Overview — Scopes and Levels
Overview
HMIS has a comprehensive configuration system built around ConfigOptions — named key-value settings that control system behaviour without requiring code changes. Configuration options are organised into four scopes, each applying at a different level of the organisation hierarchy. Understanding scopes is essential before changing any configuration.
The Four Configuration Scopes
| Scope | Where It Applies | Who Manages It |
|---|---|---|
| APPLICATION | The entire HMIS installation — all institutions and users | System administrators only |
| INSTITUTION | One specific institution and all its departments | Institution administrators |
| DEPARTMENT | One specific department within an institution | Department managers with config privilege |
| USER | One specific user account | The user themselves (with ChangePreference privilege) or an admin |
Settings at a narrower scope (e.g. department) can override broader settings (e.g. institution) for the same key. This allows system-wide defaults with targeted overrides.
Option Value Types
Each ConfigOption can store different types of values:
| Value Type | Example Keys |
|---|---|
| BOOLEAN (true/false) | "Enable mandatory fields for admission", "Show Claimable Field" |
| STRING | SMS gateway API key, bill number prefix |
| DECIMAL | Tax rate, default discount percentage |
| SHORT TEXT | Short labels, codes |
| LONG TEXT | SMS message templates, terms and conditions text |
Navigating to Configuration
| Configuration Level | Navigation Path |
|---|---|
| Application-level | Administration → Manage Institutions → Application Options |
| Institution-level | Administration → Manage Institutions → Institution Options |
| Department-level | Administration → Manage Institutions → Department Options |
| User-level | Administration → Manage Users → Manage Preferences (for that user) |
Configuration Best Practices
- Change application-level settings with caution — they affect all users instantly
- Test new configuration in a non-production environment first
- Click "Reload Config" after making changes to application options to ensure all sessions pick up the new values
- Export settings before bulk changes — the Export Selected button creates a backup
- Use Import/Export when migrating config from one environment to another
How ConfigOptions Work Internally
Each ConfigOption record has:
- Key — a unique string identifying the setting (e.g.
Inward Admission - Mandatory Fields Enabled) - Value — the stored value
- Scope — APPLICATION, INSTITUTION, DEPARTMENT, or USER
- Institution/Department/User — the entity this option applies to (null for APPLICATION)
The ConfigOptionApplicationController (ApplicationScoped bean) holds the APPLICATION-scope settings in memory for fast access. The ConfigOptionController (SessionScoped) handles CRUD at all levels.