> ## 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.

# Picklist Migration Guide

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

## 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:

```typescript theme={null}
// ❌ 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:

```sql theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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

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