Organization Setting
Data Entity
Description
A one-to-one configuration record per organization storing all org-level preferences, branding assets, terminology overrides, accounting integration credentials, portal integration state, sensitive field declarations, impact calculator multipliers, and operational defaults. Acts as the single source of truth for per-tenant configuration consumed by both the mobile app and admin portal.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Surrogate primary key. Generated server-side on record creation. | PKrequiredunique |
organization_id |
uuid |
Foreign key to organizations. Enforces the one-to-one relationship — each organization has exactly one settings row. | requiredunique |
logo_url |
string |
HTTPS CDN URL of the organization's branding logo. Uploaded via Logo Upload Adapter to the platform's object storage bucket. Used in mobile app header, admin portal, and exported documents. | - |
primary_color |
string |
Organization brand color as a CSS hex string (#RRGGBB). Applied to accent elements in the mobile app and admin portal for this organization. Must meet WCAG 2.2 AA contrast requirements when evaluated against the platform's background tokens. | - |
terminology_map |
json |
JSONB key-value map of canonical terminology keys (from TerminologyConstantsRegistry) to organization-specific label strings. Enables each org to replace platform defaults (e.g. 'Peer Mentor' → 'Likeperson', 'Contact' → 'Bruker'). Keys not present in this map fall back to platform defaults. | - |
sensitive_field_ids |
json |
JSONB array of field ID strings that are designated as sensitive for screen reader readout warning. When a VoiceOver/TalkBack user focuses one of these fields, the SensitiveFieldWidget intercepts focus and surfaces a warning dialog before allowing readout. Required by NHF and Blindeforbundet for fields containing health data, home addresses, and assignment details. | - |
impact_multipliers |
json |
JSONB object containing organization-specific impact calculation parameters: coordinator_hourly_rate (decimal), volunteer_hour_equivalent (decimal), cost_per_activity_reduction (decimal). Consumed by Impact Calculator Service and the Advantage Calculator screen to produce org-specific ROI figures. | - |
wizard_step_order |
json |
JSONB array of step configuration objects defining the order, visibility, and labels of activity wizard steps for this organization. Consumed by WizardStepConfigResolver to customize the multi-step activity registration flow per org. | - |
default_activity_duration_minutes |
integer |
Default activity duration pre-filled in the quick-log widget and activity wizard. Configurable per organization. HLF standard is 30 minutes. Must be between 5 and 480. | - |
accounting_system_type |
enum |
Identifies which accounting backend is configured for this organization. Drives adapter selection in the Accounting API Client and Accounting Adapter at export time. | - |
accounting_credentials_encrypted |
text |
Envelope-encrypted blob of accounting system API credentials (API keys, OAuth tokens, client secrets). Encrypted by Credential Vault / Accounting Credentials Store using platform KMS before persistence. Never stored or returned in plaintext. Decrypted only at adapter invocation time. | - |
accounting_field_mappings |
json |
JSONB object mapping internal expense type IDs to target accounting system account codes. Used by Accounting Field Mapper to translate Meander expense records into the target system's journal entry or voucher format. | - |
accounting_export_schedule |
json |
JSONB object containing the cron expression and export preferences (format, batch_size, notification_email) for scheduled automated accounting exports. Managed by Accounting Export Scheduler. | - |
portal_integration_enabled |
boolean |
Whether the external portal integration (HLF Dynamics 'Min Side') is active for this organization. Controls whether sync jobs are scheduled and portal adapter calls are made. | - |
portal_credentials_encrypted |
text |
Envelope-encrypted blob of external portal API credentials. Encrypted by Credential Manager Service before persistence. Decrypted only when Portal Adapter makes outbound requests. | - |
portal_data_sharing_rules |
json |
JSONB object defining per-field data sharing rules and sync direction (push/pull/bidirectional) for the external portal integration. Consumed by Portal Integration Config Store and Sync Orchestration Service. | - |
bufdir_format_version |
string |
Active Bufdir format specification version string (e.g. '2024-v2'). Used by Bufdir Field Mapper to load the correct field mapping spec when generating exports for this organization. | - |
notification_defaults |
json |
JSONB object defining the default notification preference map applied when a new user is provisioned under this organization. Keys match notification category and channel pairs (e.g. assignments.push, expenses.email). Users may override individually. | - |
external_links_config |
json |
JSONB array of curated external link objects (title, url, category, launch_mode) surfaced in the mobile app's External Resource Links screen. Scoped to this organization's users. | - |
created_at |
datetime |
Timestamp when the settings record was first created. Set once on INSERT. | required |
updated_at |
datetime |
Timestamp of the most recent settings update. Updated on every PATCH via trigger or ORM hook. | required |
Database Indexes
idx_organization_setting_organization_id
Columns: organization_id
idx_organization_setting_accounting_system_type
Columns: accounting_system_type
Validation Rules
organization_id_exists
error
Validation failed
primary_color_hex_format
error
Validation failed
logo_url_https_scheme
error
Validation failed
logo_url_max_length
error
Validation failed
default_activity_duration_range
error
Validation failed
terminology_map_value_max_length
error
Validation failed
impact_multipliers_positive_numbers
error
Validation failed
sensitive_field_ids_string_array
error
Validation failed
bufdir_format_version_known
warning
Validation failed
external_links_url_https
error
Validation failed
Business Rules
one_settings_row_per_organization
Each organization must have exactly one organization_setting record. The UNIQUE constraint on organization_id enforces this at the database level. The settings row is created atomically when a new organization is provisioned.
terminology_keys_must_be_registered
All keys in the terminology_map JSONB must exist in the TerminologyConstantsRegistry. Unrecognized keys are rejected before persistence to prevent stale or misspelled overrides from silently failing in the UI.
accounting_credentials_never_plaintext
accounting_credentials_encrypted must be envelope-encrypted by the Credential Vault / Accounting Credentials Store before any INSERT or UPDATE. The service layer must never write raw credential strings to the column. Decryption is performed in memory at adapter invocation time only.
portal_credentials_never_plaintext
portal_credentials_encrypted must be envelope-encrypted by Credential Manager Service before persistence. Same rule as accounting credentials — decrypted in-memory only when Portal Adapter makes outbound calls.
accounting_system_type_required_with_credentials
If accounting_credentials_encrypted is set, accounting_system_type must also be set to a value other than 'none'. Prevents credentials from being stored without a known adapter target, which would make them unresolvable at export time.
portal_integration_requires_credentials
If portal_integration_enabled is set to true, portal_credentials_encrypted must be non-null. Prevents the sync scheduler from enqueuing jobs for an integration that has no credentials to authenticate with.
logo_url_must_use_platform_cdn
logo_url must reference the platform's authorized CDN domain. The Logo Upload Adapter enforces this by constructing the URL from the upload response rather than accepting arbitrary user-provided URLs, preventing hotlinking to external untrusted origins.
settings_seeded_to_mobile_on_login
A subset of organization_setting fields (terminology_map, sensitive_field_ids, impact_multipliers, external_links_config, wizard_step_order, default_activity_duration_minutes) must be included in the session bootstrap payload delivered to the mobile app at login. The Local Data Seeder persists this to local SQLite for offline availability.
feature_flag_cache_invalidated_on_settings_change
When any field governing feature availability (e.g. portal_integration_enabled, accounting_system_type) is updated, the Feature Flag Cache Adapter must invalidate the cached flag map for this organization to force a fresh read on next request.