Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
CategoryPicklists
HRemployment_status, employment_type, leave_type, leave_request_status, fmla_case_type, fmla_case_status, assignment_status, assignment_type
FAfa_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
Platformdocument_category, document_status, priority_levels, status_general
FWform_status, automation_status, trigger_type, action_type

​
Best Practices

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