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

# Use Case Guide: Picklists

> System: Platform Foundation (PF) Feature: Picklist System (PF-15) Created: 2025-01-27 Status: ✅ Complete

**System:** Platform Foundation (PF)\
**Feature:** Picklist System (PF-15)\
**Created:** 2025-01-27\
**Status:** ✅ Complete

***

## Quick Reference

**When to Use Picklists:**

* ✅ You need **dropdown values used across multiple forms/entities**
* ✅ Values are **organization-specific** (vary by organization)
* ✅ Values **change frequently** (need to update without code)
* ✅ Values need to be **managed by users** (not developers)

**When NOT to Use Picklists:**

* ❌ Values are **form-specific** → Use Form Options (FW-01)
* ❌ Values come from **database table** → Use Lookups (FW-15)
* ❌ Values are **system constants** → Use Enum (TypeScript)
* ❌ Values need **strict type safety** → Use Enum (TypeScript)

***

## What Are Picklists?

Picklists are **organization-scoped, user-manageable dropdown values** that can be reused across forms, entities, and custom fields. They replace hardcoded enums and magic strings with flexible, customizable values.

**Key Characteristics:**

* Organization-scoped (each org has their own values)
* User-manageable (org admins can add/edit/delete)
* Reusable (used across multiple forms/entities)
* Versioned (track changes over time)
* Active/Inactive states (hide without deleting)

**Storage:** `pf_picklists` and `pf_picklist_items` tables

***

## Common Use Cases

### Use Case 1: Employment Status

**Scenario:** Your organization needs employment status dropdown (Full-Time, Part-Time, Contract, etc.) used in multiple places (employee forms, reports, filters).

**Solution:** Create Picklist (PF-15)

**Why Picklists:**

* Used across multiple forms/entities
* Organization-specific (values may vary)
* User-manageable (add new statuses without code)
* Reusable (one picklist, many uses)

**Implementation:**

1. Go to Settings → Picklists
2. Create picklist:
   * Name: `employment_status`
   * Label: "Employment Status"
   * Category: HR
3. Add items:
   * Full-Time (value: `full_time`)
   * Part-Time (value: `part_time`)
   * Contract (value: `contract`)
   * Temporary (value: `temporary`)
4. Use in forms/custom fields by referencing picklist name

**Benefits:**

* Values managed in one place
* Updates automatically across all uses
* No code changes needed

**Not Form Options Because:**

* Not form-specific (used across multiple forms)
* Not one-time use (reusable)

***

### Use Case 2: Department Types

**Scenario:** Your organization categorizes departments (Operations, Clinical, Administrative) and needs this dropdown in multiple forms.

**Solution:** Create Picklist (PF-15)

**Why Picklists:**

* Used across multiple forms/entities
* Organization-specific (categories may vary)
* User-manageable (add new categories)

**Implementation:**

1. Create picklist: `department_types`
2. Add items: Operations, Clinical, Administrative
3. Use in forms/custom fields

**Not Lookups Because:**

* Not from database table (categories, not departments themselves)
* Static values (not dynamic from hr\_departments)

***

### Use Case 3: Priority Levels

**Scenario:** Your organization uses priority levels (Low, Medium, High, Critical) across workflows, forms, and tasks.

**Solution:** Create Picklist (PF-15)

**Why Picklists:**

* Used across multiple systems (workflows, forms, tasks)
* Organization-specific (priority definitions may vary)
* User-manageable (add new priority levels)

**Implementation:**

1. Create picklist: `priority_levels`
2. Add items: Low, Medium, High, Critical
3. Use in workflows, forms, custom fields

**Benefits:**

* Consistent priority values across system
* Easy to update (add "Urgent" without code)

***

## When NOT to Use Picklists

### ❌ Don't Use Picklists For: Form-Specific Options

**Example:** "I need Yes/No for this specific form question"

**Why Not Picklists:**

* Form-specific (not reusable)
* Simple binary choice (not worth picklist)

**Use Instead:** Form Options (FW-01) - static "Yes"/"No" options

***

### ❌ Don't Use Picklists For: Database Table Data

**Example:** "I need departments from hr\_departments table"

**Why Not Picklists:**

* Data exists in database table
* Real-time data (departments added/removed dynamically)
* Needs to respect RLS policies

**Use Instead:** Lookups (FW-15) - reference hr\_departments table

***

### ❌ Don't Use Picklists For: System Constants

**Example:** "I need status values that never change (Active, Inactive)"

**Why Not Picklists:**

* System constants (same for all organizations)
* Need strict type safety
* Never change

**Use Instead:** Enum (TypeScript) - `type Status = 'active' | 'inactive'`

***

## Integration with Other Systems

### Picklists + Custom Fields (PF-16)

**Use Case:** Custom field needs dropdown values

**Example:** Employee shirt size (S, M, L, XL)

**Implementation:**

1. Create picklist: `employee_shirt_sizes`
2. Create custom field (PF-16):
   * Entity: hr\_employees
   * Field Type: `select`
   * Picklist: employee\_shirt\_sizes
3. Field renders as dropdown with picklist values

**Benefits:**

* Reusable picklist values
* Consistent values across system

***

### Picklists + Forms (FW-01)

**Use Case:** Form field needs dropdown values

**Example:** Employment status in onboarding form

**Implementation:**

1. Create picklist: `employment_status`
2. In Form Builder, create select field
3. Choose "Picklist" as data source
4. Select picklist: employment\_status
5. Form renders with picklist values

**Benefits:**

* Values managed in one place
* Updates automatically across all forms

***

### Picklists + Workflows (FW-03)

**Use Case:** Workflow condition needs dropdown values

**Example:** Branch workflow based on priority level

**Implementation:**

1. Create picklist: `priority_levels`
2. In Workflow Builder, create condition
3. Reference picklist values in condition
4. Workflow branches based on priority

**Benefits:**

* Consistent values across workflows
* Easy to update (add new priority level)

***

## Decision Tree

```
I need dropdown options
├─ Are these values used across multiple forms/entities?
│  ├─ Yes → Are these values from a database table?
│  │   ├─ Yes → Use Lookups (FW-15) ✅
│  │   │   Example: Departments from hr_departments
│  │   └─ No → Are these values organization-specific?
│  │       ├─ Yes → Use Picklists (PF-15) ✅
│  │       │   Example: Employment status, priority levels
│  │       └─ No → Are these system constants?
│  │           └─ Yes → Use Enum (TypeScript) ✅
│  └─ No → Are these values form-specific?
│       └─ Yes → Use Form Options (FW-01) ✅
│           Example: Yes/No for form question
```

***

## Examples by Category

### HR Category

* **Employment Status**: Full-Time, Part-Time, Contract, Temporary
* **Department Types**: Operations, Clinical, Administrative
* **Position Types**: Manager, Staff, Contractor
* **Credential Types**: RN, LCSW, LPC, etc.

### Finance Category

* **Account Types**: Asset, Liability, Equity, Revenue, Expense
* **Invoice Status**: Draft, Pending, Paid, Overdue
* **Payment Methods**: Check, ACH, Credit Card, Wire

### Operations Category

* **Priority Levels**: Low, Medium, High, Critical
* **Incident Types**: Safety, Compliance, Maintenance
* **Work Order Status**: Open, In Progress, Completed, Cancelled

### General Category

* **Yes/No**: Yes, No (if used across system)
* **Boolean States**: Active, Inactive
* **Common Statuses**: Pending, Approved, Rejected

***

## Best Practices

### 1. Use Descriptive Names

✅ **Do:** Use descriptive names (`employment_status`, `priority_levels`)\
❌ **Don't:** Use abbreviations (`emp_stat`, `prio`)

### 2. Use Consistent Value Format

✅ **Do:** Use snake\_case for values (`full_time`, `part_time`)\
❌ **Don't:** Use mixed case (`Full-Time`, `part-time`)

### 3. Add Metadata

✅ **Do:** Add colors, icons, descriptions to items\
❌ **Don't:** Leave items without metadata

### 4. Use Categories

✅ **Do:** Organize picklists by category (HR, Finance, Operations)\
❌ **Don't:** Create picklists without categories

### 5. Version Control

✅ **Do:** Track changes to picklists (versioning)\
❌ **Don't:** Delete items (use is\_active = false)

***

## Common Mistakes

### Mistake 1: Using Picklists for Database Table Data

**Problem:** Creating picklist for departments when hr\_departments table exists\
**Solution:** Use Lookups (FW-15) to reference table

### Mistake 2: Using Picklists for Form-Specific Options

**Problem:** Creating picklist for one form's Yes/No question\
**Solution:** Use Form Options (FW-01) - static options

### Mistake 3: Not Using Picklists for Reusable Values

**Problem:** Manually typing employment status in each form\
**Solution:** Create picklist and reference in all forms

### Mistake 4: Deleting Items Instead of Deactivating

**Problem:** Deleting picklist items (breaks historical data)\
**Solution:** Set is\_active = false (preserves history)

***

## Migration from Enums

### When to Migrate Enum to Picklist

**Migrate if:**

* Values vary by organization
* Values change frequently
* Users need to customize values
* Values used in multiple places

**Don't Migrate if:**

* Values are system constants
* Values never change
* Need strict type safety

**Example Migration:**

```typescript theme={null}
// Before: Hardcoded enum
type EmploymentStatus = 'full_time' | 'part_time' | 'contract';

// After: Picklist
const { items } = usePicklistItems('employment_status');
// Items: [{ value: 'full_time', label: 'Full-Time' }, ...]
```

***

## Related Documentation

* [PF-15: Picklist System Spec](../../../specs/pf/specs/PF-15-picklist-system.md)
* [PF-16: Custom Field Definitions Spec](../../../specs/pf/specs/PF-16-custom-field-definitions.md)
* [Custom Fields Use Case Guide](./custom-fields.md)
* [Clarity Analysis](./clarity-analysis.md)

***

**Last Updated:** 2025-12-05\
**Next Review:** After user feedback