Preferences

See the config-artifact guide for how to add, register, and deploy preference files. This page covers how to name and organise them.

Preference file names

Preference files live flat in configuration/preferences, are always .xml, and their names follow a fixed scheme that tcli lint enforces:

prefs_<scope>_<action>[__<target>][___<category>].xml

• <scope> is one of site, group, role, or user.
• <action> is one of override or merge.
• <target> is the group, role, or user the preferences apply to. It is required for group, role, and user scopes and omitted for site, since site preferences have no target.
• <category> is optional and, when present, is appended after a triple underscore (___). We recommend splitting preference files by category to avoid huge single files.

Everything after prefs_ is lower_snake_case.

Valid examples:

prefs_site_override.xml
prefs_site_merge.xml
prefs_site_override___aw.xml
prefs_group_override__engineering.xml
prefs_group_merge__engineering.xml
prefs_role_override__designer.xml
prefs_user_merge_infodba.xml
prefs_group_override__engineering___general.xml

Caution

The __target separator is a double underscore and the ___category separator is a triple underscore, which keeps them distinct from the single underscores inside a lower_snake_case scope, action, target, or category name.

Custom preferences

Custom preference definitions are named in PascalCase and may optionally carry a project prefix.

Group custom preferences into custom categories. If you add a custom general preference, for example, create a dedicated category such as General Custom. Better still, be explicit and name the category after the customisation the preference belongs to.