Picklists

Administrators can manage all picklists at /settings/picklists. This route renders PicklistsPage from src/platform/picklists/pages/PicklistsPage.tsx with no explicit route-level permission wrapper.

​

Overview

The Picklists page lists all picklists available to the organization using PicklistsTable. It is organized in two tabs: Picklists (the main list) and a Templates library (PicklistTemplateLibrary). Users with pf.picklists.admin permission can export picklists via PicklistExportDialog, import picklists via PicklistImportDialog, and apply templates from the template library (which pre-populates the import dialog with templateRecords). Selecting a picklist row navigates to /settings/picklists/:id for detail view and editing.

​

Who it’s for

Access follows your organization’s role and module configuration. Admin actions (export, import) require pf.picklists.admin (checked at component level).

​

Before you start

• You must be signed in.

​

Steps

1. Navigate to Settings > Picklists (/settings/picklists).
2. Browse the list of picklists in the Picklists tab.
3. Select a picklist to view its details and items.
4. Use Export to download picklist definitions.
5. Use Import to upload picklist definitions from a file.
6. Switch to the Templates tab to browse and apply predefined picklist templates.

​

Key concepts

Picklist — A named list of selectable values used to populate dropdown fields across forms and data objects throughout the platform. Template library — Pre-built picklist collections that can be applied to an organization in bulk to accelerate setup.

​

Editing a picklist

Administrators can view and edit a specific picklist at /settings/picklists/:id. This route renders PicklistDetailPage from src/platform/picklists/pages/PicklistDetailPage.tsx with no explicit route-level permission wrapper. The page displays the metadata and items for a specific picklist identified by its :id URL parameter. Picklist data is loaded via usePicklist(). Items are managed via PicklistItemsEditor. The PicklistForm dialog allows editing the picklist’s name, label, and description. A SystemPicklistBanner is shown for picklists where is_system = true and organization_id = null to indicate they are read-only global definitions. Users with pf.picklists.admin permission can duplicate a system picklist to their organization via duplicatePicklistToOrg(). Dynamic breadcrumb labels are set via useBreadcrumbLabel(). Editing actions require pf.picklists.admin (checked at component level via useHasPermission).

1. Navigate to Settings > Picklists and select a picklist, or go directly to /settings/picklists/:id.
2. Review the picklist items and their display order.
3. To edit metadata, select the edit button to open PicklistForm.
4. Add, reorder, or remove items in the PicklistItemsEditor.
5. If viewing a system picklist, use Duplicate to Org to create an editable copy.

System picklist — A global, platform-managed picklist (is_system = true, organization_id = null). These are read-only; to customize, duplicate to your organization. Organization picklist — A tenant-specific picklist that can be freely edited.

​

Locked picklists

Some picklists mirror a database constraint or a regulated code set (for example, consent types or payment methods). They are shipped with a value-set lock so a tenant edit can’t silently break a database insert or a regulated workflow. On a locked picklist the detail page shows an explanatory alert and disables Add item, Delete, and Deactivate. You can still edit:

• Item label, color, and display order
• The new Aliases field (see below)

To change the underlying value set on a locked picklist, the platform team ships a migration that updates both the database constraint and the seed. The classification model — Tier A workflow states, Tier B org vocabulary, Tier C constraint-mirrored — is documented in ADR-027.

​

Aliases

Each picklist item has an Aliases field for alternate strings that should resolve to this value. Aliases are used by the importer’s value-mapping step to match incoming source values (for example, mapping "ACH" to a Payment Method item whose value is eft). Aliases are case-insensitive and never change the stored value — only the mapping suggestion. Add one alias per line in the item editor. Aliases are available on both editable and locked picklists.

​

Naming convention

New system picklists use a dot-namespace name of the form {core}.{domain}.{field} — for example, cl.notes.type, pm.payments.method, lo.meetings.type. Older flat names (such as hr_employment_status) are kept as-is to avoid breaking saved data. When you create an organization picklist in the form, the name must match ^[a-z0-9_]+(\.[a-z0-9_]+)*$.

​

Related

Documentation sources

• src/routes/platform.tsx
• src/platform/picklists/pages/PicklistsPage.tsx
• src/platform/picklists/components/PicklistsTable.tsx
• src/platform/picklists/pages/PicklistDetailPage.tsx
• src/platform/picklists/hooks/usePicklist.ts