Encore OS — Documentation

Overview

This guide explains how to migrate from hardcoded enums to organization-scoped picklists using the PF-15 Picklist System.

Why Migrate?

Organization customization: Each org can customize values
Admin UI management: Non-developers can add/edit options
Color coding: Items can have associated colors for UI display
Soft-delete: Items can be deactivated without breaking existing data

Migration Steps

1. Identify Enum Usage

Find all places where you’re using hardcoded enums:

// ❌ Before: Hardcoded enum
const STATUS_OPTIONS = [
  { value: 'active', label: 'Active' },
  { value: 'inactive', label: 'Inactive' },
];

2. Create Picklist (Admin or Migration)

Either create via Admin UI or database migration:

INSERT INTO pf_picklists (organization_id, name, label, category, is_system)
VALUES (v_org_id, 'status_options', 'Status Options', 'platform', true);

3. Use Backward-Compatible Hook

During migration, use usePicklistByEnum for backward compatibility:

import { usePicklistByEnum } from '@/platform/picklists';

// ✅ After: Picklist with enum fallback
const { items, source } = usePicklistByEnum('employment_status', {
  active: 'Active',
  on_leave: 'On Leave',
  terminated: 'Terminated',
});

// `source` tells you if data came from picklist or enum fallback
console.log(source); // 'picklist' or 'enum'

4. Use PicklistSelector in Forms

import { PicklistSelector } from '@/platform/picklists';

<PicklistSelector
  picklistName="employment_status"
  value={status}
  onChange={setStatus}
  placeholder="Select status"
/>

Seeded Picklists

The following system picklists are automatically seeded:

Category	Picklists
HR	employment_status, employment_type, leave_type, leave_request_status, fmla_case_type, fmla_case_status, assignment_status, assignment_type
FA	fa_customer_type, fa_bill_status, fa_invoice_status, fa_po_status, fa_budget_status, fa_budget_version_type, fa_journal_entry_status, account_type, account_status, fund_type, fa_payment_method, payment_terms
Platform	document_category, document_status, priority_levels, status_general
FW	form_status, automation_status, trigger_type, action_type

Best Practices

Always use usePicklistByEnum during migration for backward compatibility
Mark system picklists with is_system: true to prevent accidental deletion
Use semantic picklist names that match the database enum names
Include colors in metadata for status-type picklists

Getting Started

Data & Migration

Configuration Building Blocks

Templates & Recommendations

Scheduling & Automation

Picklist Migration Guide

Overview

Why Migrate?

Migration Steps

1. Identify Enum Usage

2. Create Picklist (Admin or Migration)

3. Use Backward-Compatible Hook

4. Use PicklistSelector in Forms

Seeded Picklists

Best Practices

​Overview

​Why Migrate?

​Migration Steps

​1. Identify Enum Usage

​2. Create Picklist (Admin or Migration)

​3. Use Backward-Compatible Hook

​4. Use PicklistSelector in Forms

​Seeded Picklists

​Best Practices

Overview

Why Migrate?

Migration Steps

1. Identify Enum Usage

2. Create Picklist (Admin or Migration)

3. Use Backward-Compatible Hook

4. Use PicklistSelector in Forms

Seeded Picklists

Best Practices