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: 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: 
    {
  "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: 
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

OptionDescriptionExample
visible_to_rolesRoles that can see field['org_admin', 'hr_manager']
hidden_from_rolesRoles that cannot see field['viewer', 'guest']
view_contextsContexts where field appears['edit_form', 'detail_view']

​
Required Rules

OptionDescriptionExample
required_on_createRequired when creatingtrue / false
required_on_editRequired when editingtrue / false
required_conditionsConditional requirement{ field: 'status', value: 'active' }

​
Conditional Visibility

OperatorDescriptionExample
equalsField equals value{ field: 'type', operator: 'equals', value: 'contract' }
not_equalsField doesn’t equal value{ operator: 'not_equals', value: null }
containsArray contains value{ operator: 'contains', value: 'admin' }
is_emptyField is empty/null{ operator: 'is_empty' }
is_not_emptyField 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 ✅ 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
Last Updated: 2025-12-05
Next Review: After user feedback