# 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 → Preferences → Application Options | | Institution-level | Administration → Manage Institutions → Preferences → Institution Options | | Department-level | Administration → Manage Institutions → Preferences → 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. ## Related Features - [Application-Level Configuration](Admin-Application-Level-Configuration) - [Institution-Level Configuration](Admin-Institution-Level-Configuration) - [Department-Level Configuration](Admin-Department-Level-Configuration) - [User-Level Preferences](Admin-User-Level-Preferences)