Custom User Preferences

User preferences are settings that change how the platform behaves for each individual user — things like preferred language, theme, default landing page, notification channels, and timezone. They differ from custom user fields in that preferences typically affect the application's behaviour, not its data.

Common Preferences

• Theme: Light, Dark, or System default.
• Language: The locale to render the UI in.
• Timezone: Override of the tenant default so dates render in the user's local time.
• Default landing page: Which page to open when they sign in.
• Density: Compact (more rows visible) vs Comfortable (taller rows, easier on the eye).
• Notification channels: Which categories of notification arrive by which channel.

Defining a New Preference

1. Open Architect Panel → Custom User Preferences and click Add Preference.
2. Give it a key (used in code: theme, density), a display label, and a help blurb.
3. Pick a control type (toggle, dropdown, text, color).
4. Set the default value if the user never changes it.
5. Mark the scope: User-only (just this user), Tenant-default (admins set, users override), Global default (only admins).

Worked Examples

• Accessibility: Add a “High contrast mode” toggle and a “Reduce motion” toggle. Combined they give visually impaired users a much more usable interface.
• Field workers: Add a “Default to GPS-enabled forms” preference so engineers landing on the new-job form get location captured automatically.
• Localisation: Add a “Decimal separator” preference (period vs comma) for European users entering numbers.
• Power users: Add a “Keyboard shortcuts enabled” toggle that defaults off but unlocks hotkeys for advanced users.

Defaults matter — most users never change a preference, so what they get out-of-the-box is what they experience forever. This article covers how preference defaults cascade across the platform.

The Cascade

1. Platform default — the value baked into the preference definition.
2. Tenant default — what the tenant admin set for all users in that tenant.
3. Group default — some preferences can be set per security group.
4. User value — the user's explicit choice.

The user value wins if set; otherwise the closest non-null upper layer is used.

Setting Tenant Defaults

1. Open Site Settings → User Preferences.
2. For each preference, set the tenant-wide default (or leave blank to inherit the platform default).
3. Tick “Lock — users cannot override” for any preference that should be a tenant policy rather than a personal choice.

Setting Group Defaults

Group defaults are useful for role-specific overrides — e.g. setting the default landing page to “Dashboard” for managers but to “My Tickets” for support agents.

Worked Examples

• Healthcare clinic: Theme set to Light at tenant level, locked — high-contrast medical settings shouldn't change. Timezone defaults to the clinic's local zone but users can override if they work remotely.
• SaaS multi-tenant: Each tenant gets a different default landing page based on what their workflow centres on. Users can still override.
• Frontline staff: Group default for the “Density” preference is Compact (more data on screen for ops dashboards); management group inherits Comfortable.
• Localisation: Tenant default language follows the tenant's country, but users from international branches can pick their own.

Warning: Locking a preference means users see the option but cannot save changes — confusing UX. Hide locked preferences from the UI rather than leaving disabled toggles visible.