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

> System: Platform Foundation (PF) Feature: Entity Field Configuration (PF-17) Created: 2025-12-05 Status: ✅ Complete

**System:** Platform Foundation (PF)\
**Feature:** Entity Field Configuration (PF-17)\
**Created:** 2025-12-05\
**Status:** ✅ Complete

***

## Quick Reference

**When to Use Field Configuration:**

* ✅ You need to **hide fields by role** (salary visible to admins only)
* ✅ You need to **make fields required by context** (required on edit, optional on create)
* ✅ You need to **control field order** in entity forms
* ✅ You need **conditional visibility** (show field B when field A = "Yes")

**When NOT to Use Field Configuration:**

* ❌ You need to **add a new field** → Use Custom Fields (PF-16)
* ❌ You need to **create new entity** → Use Custom Objects (PF-24)
* ❌ You need to **create form layout** → Use Form Builder (FW-01)
* ❌ You need **dropdown options** → Use Picklists (PF-15)

***

## What Is Field Configuration?

Field Configuration controls **how existing fields behave** in entity forms and views. It defines visibility rules, required status, field ordering, and conditional logic without changing the underlying data schema.

**Key Characteristics:**

* Context-aware (different rules for create vs edit vs view)
* Role-based (visibility varies by user role)
* Conditional (show/hide based on other field values)
* Non-destructive (doesn't modify data schema)

**Storage:** `pf_entity_field_configs` table

***

## Common Use Cases

### Use Case 1: Hide Salary from Non-Admins

**Scenario:** Your organization tracks employee salaries, but only HR managers and admins should see salary information.

**Solution:** Configure Field Visibility (PF-17)

**Why Field Configuration:**

* Controlling existing field (hr\_employees.salary)
* Role-based visibility
* Field exists in schema (not adding new field)

**Implementation:**

1. Go to Settings → Field Configuration
2. Select entity: `hr_employees`
3. Find field: `salary`
4. Set visibility rules:
   * View Context: `edit_form`
   * Visible to roles: `['org_admin', 'hr_manager']`
   * Hidden from roles: `['staff', 'viewer']`
5. Save configuration
6. Salary field only visible to admins/managers

**Not Custom Fields Because:**

* Not adding new field (salary exists in schema)
* Controlling visibility (not defining new data)

***

### Use Case 2: Require Fields by Context

**Scenario:** On employee creation, department is optional. On employee edit, department is required.

**Solution:** Configure Required Rules (PF-17)

**Why Field Configuration:**

* Controlling existing field behavior
* Context-dependent requirements
* Different rules for create vs edit

**Implementation:**

1. Go to Settings → Field Configuration
2. Select entity: `hr_employees`
3. Find field: `department_id`
4. Set required rules:
   * Create form: `required: false`
   * Edit form: `required: true`
5. Save configuration
6. Department optional on create, required on edit

**Benefits:**

* Flexible data entry on create
* Enforce completeness on edit
* Same field, different requirements by context

***

### Use Case 3: Conditional Field Visibility

**Scenario:** Show "License Expiration Date" only when "Has License" is checked.

**Solution:** Configure Conditional Visibility (PF-17)

**Why Field Configuration:**

* Conditional show/hide logic
* Based on other field values
* Dynamic form behavior

**Implementation:**

1. Go to Settings → Field Configuration
2. Select entity: `hr_employees`
3. Find field: `license_expiration_date`
4. Add conditional rule:
   ```json theme={null}
   {
     "field": "has_license",
     "operator": "equals",
     "value": true
   }
   ```
5. Save configuration
6. Expiration date only shows when "Has License" = true

**Benefits:**

* Cleaner forms (hide irrelevant fields)
* Better UX (context-aware forms)
* No code changes needed

***

### Use Case 4: Reorder Fields in Forms

**Scenario:** You want to show "Emergency Contact" fields at the top of employee forms, not at the bottom.

**Solution:** Configure Field Order (PF-17)

**Why Field Configuration:**

* Controlling field display order
* Improving UX (important fields first)
* No schema changes needed

**Implementation:**

1. Go to Settings → Field Configuration
2. Select entity: `hr_employees`
3. Set display\_order for fields:
   * `emergency_contact_name`: 1
   * `emergency_contact_phone`: 2
   * `first_name`: 3
   * `last_name`: 4
   * etc.
4. Save configuration
5. Emergency contact fields appear first

***

## When NOT to Use Field Configuration

### ❌ Don't Use Field Configuration For: Adding New Fields

**Example:** "I need to add badge\_number to employees"

**Why Not Field Configuration:**

* Adding new field (not controlling existing)
* Need to define data type, validation
* New data storage needed

**Use Instead:** Custom Fields (PF-16)

***

### ❌ Don't Use Field Configuration For: Creating Forms

**Example:** "I need to create an intake form"

**Why Not Field Configuration:**

* Creating new form (not configuring entity fields)
* Form with its own fields
* One-time data capture

**Use Instead:** Form Builder (FW-01)

***

### ❌ Don't Use Field Configuration For: Creating Entities

**Example:** "I need to track Clinical Licenses"

**Why Not Field Configuration:**

* Creating new entity type
* Not configuring existing entity

**Use Instead:** Custom Objects (PF-24)

***

## Integration with Other Systems

### Field Configuration + Custom Fields (PF-16)

**Use Case:** Control visibility of custom fields

**Example:** Hide "Badge Number" custom field from non-admins

**Implementation:**

1. Create custom field (PF-16): `badge_number`
2. Configure visibility (PF-17):
   * Entity: hr\_employees
   * Field: `custom_fields.badge_number` (or referenced by field\_definition\_id)
   * Visible to roles: `['org_admin']`
3. Custom field respects visibility configuration

**Benefits:**

* Custom fields integrate with field configuration
* Consistent visibility control

***

### Field Configuration + Picklists (PF-15)

**Use Case:** Conditional field based on picklist value

**Example:** Show "Contractor Details" section when Employment Status = "Contract"

**Implementation:**

1. Create picklist (PF-15): `employment_status`
2. Add picklist item: `contract`
3. Configure conditional visibility (PF-17):
   * Field: `contractor_company`
   * Condition: `employment_status == 'contract'`
4. Contractor fields only show for contractors

***

### Field Configuration + DynamicFormRenderer

**Use Case:** Render entity forms with field configuration applied

**Example:** Employee edit form with role-based visibility

**Implementation:**

```tsx theme={null}
import { DynamicFormRenderer } from '@/platform/field-config';

<DynamicFormRenderer
  entityType="hr_employees"
  context="edit_form"
  record={employee}
  onSubmit={handleSubmit}
/>
```

The renderer automatically:

* Filters fields by role-based visibility
* Applies conditional visibility rules
* Orders fields by display\_order
* Enforces required rules by context

***

## Decision Tree

```
I need to control a field
├─ Does the field already exist in the entity?
│  ├─ Yes → Do I need to control visibility?
│  │   ├─ Yes → Use Field Configuration (PF-17) ✅
│  │   │   Example: Hide salary from non-admins
│  │   └─ No → Do I need to control required status?
│  │       ├─ Yes → Use Field Configuration (PF-17) ✅
│  │       │   Example: Required on edit, optional on create
│  │       └─ No → Do I need to control field order?
│  │           └─ Yes → Use Field Configuration (PF-17) ✅
│  └─ No → Do I need to add a new field?
│       └─ Yes → Use Custom Fields (PF-16) ✅
│           Then optionally configure with PF-17
```

***

## Configuration Options

### Visibility Rules

| Option              | Description                  | Example                        |
| ------------------- | ---------------------------- | ------------------------------ |
| `visible_to_roles`  | Roles that can see field     | `['org_admin', 'hr_manager']`  |
| `hidden_from_roles` | Roles that cannot see field  | `['viewer', 'guest']`          |
| `view_contexts`     | Contexts where field appears | `['edit_form', 'detail_view']` |

### Required Rules

| Option                | Description             | Example                                |
| --------------------- | ----------------------- | -------------------------------------- |
| `required_on_create`  | Required when creating  | `true` / `false`                       |
| `required_on_edit`    | Required when editing   | `true` / `false`                       |
| `required_conditions` | Conditional requirement | `{ field: 'status', value: 'active' }` |

### Conditional Visibility

| Operator       | Description               | Example                                                    |
| -------------- | ------------------------- | ---------------------------------------------------------- |
| `equals`       | Field equals value        | `{ field: 'type', operator: 'equals', value: 'contract' }` |
| `not_equals`   | Field doesn't equal value | `{ operator: 'not_equals', value: null }`                  |
| `contains`     | Array contains value      | `{ operator: 'contains', value: 'admin' }`                 |
| `is_empty`     | Field is empty/null       | `{ operator: 'is_empty' }`                                 |
| `is_not_empty` | Field has value           | `{ operator: 'is_not_empty' }`                             |

***

## Best Practices

### 1. Use Role-Based Visibility for Sensitive Data

✅ **Do:** Hide salary, SSN, compensation from non-privileged roles\
❌ **Don't:** Rely only on RLS (field config provides UI-level hiding)

### 2. Make Fields Required Progressively

✅ **Do:** Optional on create, required on edit (allow incomplete records initially)\
❌ **Don't:** Require everything on create (blocks quick data entry)

### 3. Use Conditional Visibility to Simplify Forms

✅ **Do:** Hide irrelevant fields based on other values\
❌ **Don't:** Show all fields all the time

### 4. Group Related Fields

✅ **Do:** Use display\_order to group related fields together\
❌ **Don't:** Scatter related fields throughout form

### 5. Document Configuration Decisions

✅ **Do:** Add notes explaining why fields are hidden/required\
❌ **Don't:** Configure without documentation

***

## Common Mistakes

### Mistake 1: Using Field Config for New Fields

**Problem:** Trying to add new fields via field configuration\
**Solution:** Use Custom Fields (PF-16) first, then configure with PF-17

### Mistake 2: Over-Hiding Fields

**Problem:** Hiding too many fields, users can't find information\
**Solution:** Balance visibility - hide sensitive data, not all data

### Mistake 3: Complex Conditional Chains

**Problem:** Field A shows Field B which shows Field C which shows Field D\
**Solution:** Keep conditional logic simple (max 2 levels)

### Mistake 4: Inconsistent Required Rules

**Problem:** Field required on edit but data entered on create can't be empty\
**Solution:** If required on edit, guide users to fill on create too

***

## Related Documentation

* [PF-17: Entity Field Configuration Spec](../../../specs/pf/specs/PF-17-entity-field-configuration.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