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.

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: 
// Before: Hardcoded enum
type EmploymentStatus = 'full_time' | 'part_time' | 'contract';

// After: Picklist
const { items } = usePicklistItems('employment_status');
// Items: [{ value: 'full_time', label: 'Full-Time' }, ...]
Last Updated: 2025-12-05
Next Review: After user feedback