Encore OS — Documentation

System: Forms & Workflow (FW)
Feature: Form Builder (FW-01)
Created: 2025-01-27
Updated: 2025-12-05
Status: ✅ Complete

Quick Reference

✅ When to Use Forms:

You need to collect data from users
Data is captured one time (form submission)
You need validation, conditional logic, or workflows
You need form submissions tracked over time
You need surveys, assessments, or reports

❌ When NOT to Use Forms:

You need a new entity type to track over time → Use Custom Objects (PF-24)
You need to extend an existing entity → Use Custom Fields (PF-16)
You need to control existing entity forms → Use Entity Field Configuration (PF-17)
You need entity CRUD operations → Use Custom Objects (PF-24)

Decision Tree

I need to collect data
│
├─► Is this a one-time submission?
│   │
│   ├─ Yes → Does it need workflow/approval?
│   │   │
│   │   ├─ Yes → Use Form Builder (FW-01) ✔
│   │   │   with Automation Engine (FW-03)
│   │   │
│   │   └─ No → Use Form Builder (FW-01) ✔
│   │
│   └─ No → Do you need CRUD operations on records?
│       │
│       ├─ Yes → Use Custom Objects (PF-24)
│       │
│       └─ No → Is this extending existing entity?
│           │
│           ├─ Yes → Use Custom Fields (PF-16)
│           │
│           └─ No → Use Custom Objects (PF-24)

What Are Forms?

Forms are data capture interfaces that allow users to input data, which is then stored as form submissions. Forms support:

Multiple field types (text, number, date, select, file, signature, etc.)
Validation rules
Conditional logic (show/hide fields)
Multi-page layouts (FW-05)
Workflow integration (FW-03)
Submission tracking and analytics (PF-09)

Storage: Form submissions stored in fw_form_submissions table.

Common Use Cases

Use Case 1: Resident Intake Form

Scenario: New resident intake collecting personal information, medical history, and emergency contacts. Solution: Create a form (FW-01) Why Forms:

One-time data capture (each submission is a new intake)
Needs validation (required fields, date ranges)
Needs conditional logic (show medical fields if medical needs = yes)
Needs workflow (submit → review → approve)

Implementation:

Create form in Form Builder
Add fields: name, date_of_birth, medical_needs (yes/no), emergency_contact
Add conditional logic: show medical_history if medical_needs = yes
Add validation: date_of_birth must be in past
Publish form → Users fill form → Submission created → Workflow triggered

Not Custom Objects Because:

Not tracking multiple records over time
Intake is a process, not an entity

Use Case 2: Incident Report Form

Scenario: Staff need to report incidents (safety, compliance, etc.) Solution: Create a form (FW-01) Why Forms:

One-time data capture (each submission is a new incident)
Needs validation (required fields, date/time)
Needs workflow (submit → investigate → resolve)
Needs submission tracking

Implementation:

Create form with: incident_type, date_time, location, description, severity
Add file upload for evidence
Add workflow: on submit → notify manager → create task
Publish form

Use Case 3: Daily Inspection Checklist

Scenario: Daily facility inspection checklist Solution: Create a form (FW-01) Why Forms:

Repeated submissions (daily, weekly)
Yes/No or pass/fail fields
Can generate compliance reports

Implementation:

Create form with checkbox fields for each inspection item
Add signature field for inspector
Set up recurrence (daily reminder via workflow)
Use Form Analytics (PF-09) for compliance reporting

Examples by Module

Recovery Housing (RH)

Use Case	Solution	Notes
Resident intake form	Form (FW-01)	One-time per admission
Incident report	Form (FW-01)	With supervisor workflow
Room inspection checklist	Form (FW-01)	Daily recurring
Discharge survey	Form (FW-01)	Anonymous option

Workforce (HR)

Use Case	Solution	Notes
Job application	Form (FW-01)	With hiring workflow
Time-off request	Form (FW-01)	With approval workflow
Employee satisfaction survey	Form (FW-01)	Anonymous, uses PF-09 analytics
Performance review	Form (FW-01)	Annual, linked to employee

Finance (FA)

Use Case	Solution	Notes
Expense reimbursement	Form (FW-01)	With approval workflow
Budget request	Form (FW-01)	With finance review
Vendor onboarding	Form (FW-01)	Creates vendor record via workflow

Governance (GR)

Use Case	Solution	Notes
Policy acknowledgment	Form (FW-01)	Signature required
Compliance audit checklist	Form (FW-01)	Multi-page, comprehensive
Board meeting feedback	Form (FW-01)	Anonymous option

Field Types Available

Type	Use Case	Example
Text	Short text input	Name, title
Textarea	Long text input	Description, notes
Number	Numeric input	Age, quantity
Email	Email validation	Contact email
Phone	Phone formatting	Contact phone
Date	Date picker	Incident date
DateTime	Date and time	Appointment time
Select	Single choice	Priority level
Multi-select	Multiple choices	Symptoms
Checkbox	Yes/No	Acknowledgment
Radio	Single choice (visible)	Rating 1-5
File	File upload	Documents
Signature	Digital signature	Approvals

Form Options (Inline)

Use when: Options are specific to THIS form only

Example: "How did you hear about us?"
- Website
- Referral
- Advertisement

Picklists (PF-15)

Use when: Options are used across multiple forms

Example: "Priority Level" used in:
- Incident forms
- Maintenance requests
- Support tickets

Lookups (FW-15)

Use when: Options come from database tables

Example: "Department" from hr_departments
- Automatically updates when departments change
- Respects RLS for org isolation

Integration with Workflows (FW-03)

Forms integrate seamlessly with the Automation Engine:

Form Submission
      │
      ▼
┌─────────────────┐
│  Trigger Node   │  "On form submit"
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Condition Node  │  "If severity = high"
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│Notify │ │Create │
│Manager│ │ Task  │
└───────┘ └───────┘

Common Workflow Patterns:

Approval Workflow: Submit → Route to approver → Approve/Reject → Notify submitter
Notification Workflow: Submit → Notify stakeholders → Archive
Data Sync Workflow: Submit → Map to entity → Create/update record

Anti-Patterns to Avoid

❌ Using Forms for Entity Extension

Problem: Creating a form to capture employee badge number
Why Bad: Badge number belongs on employee record, not form submission
Solution: Use Custom Fields (PF-16) to add badge_number to hr_employees

❌ Using Forms Instead of Custom Objects

Problem: Creating a form to track clinical licenses
Why Bad: Licenses need CRUD operations, not one-time submissions
Solution: Use Custom Objects (PF-24) for license entity

❌ Using Inline Options for Reusable Values

Problem: Adding “Full-time, Part-time, Contractor” as inline options
Why Bad: Same values needed in multiple places, hard to maintain
Solution: Use Picklists (PF-15) for reusable dropdown values

❌ Using Forms for Database Records

Problem: Creating form to add new departments
Why Bad: Departments need CRUD in hr_departments table
Solution: Use module-specific entity forms or Raw Data Editor (PF-25)

Best Practices

1. Form Design

Keep forms focused (one purpose per form)
Group related fields with sections
Use conditional logic to hide irrelevant fields
Provide clear labels and help text

2. Field Validation

Set required fields appropriately
Use correct field types (email for emails, etc.)
Add character limits for text fields
Validate formats (phone, date, etc.)

3. Workflow Integration

Define clear approval paths
Set up appropriate notifications
Configure escalation for overdue approvals
Test workflow before production use

4. Data Management

Consider data retention policies
Set up appropriate RLS for submissions
Use Form Analytics (PF-09) for insights
Archive old forms when no longer needed

Picklists Use Case Guide - Reusable dropdown values
Custom Fields Use Case Guide - Extend existing entities
Custom Objects Use Case Guide - Create new entities
Data Manager Use Case Guide - Browse and manage data
Clarity Analysis - Feature comparison matrix
FW-01 Specification
PF-09 Form Analytics
FW-27 Advanced Analytics

Last Updated: 2025-12-05

Getting Started

Data & Migration

Configuration Building Blocks

Templates & Recommendations

Scheduling & Automation

Use Case Guide: Forms

Quick Reference

✅ When to Use Forms:

❌ When NOT to Use Forms:

Decision Tree

What Are Forms?

Common Use Cases

Use Case 1: Resident Intake Form

Use Case 2: Incident Report Form

Use Case 3: Daily Inspection Checklist

Examples by Module

Recovery Housing (RH)

Workforce (HR)

Finance (FA)

Governance (GR)

Field Types Available

Form Options (Inline)

Picklists (PF-15)

Lookups (FW-15)

Integration with Workflows (FW-03)

Anti-Patterns to Avoid

❌ Using Forms for Entity Extension

❌ Using Forms Instead of Custom Objects

❌ Using Inline Options for Reusable Values

❌ Using Forms for Database Records

Best Practices

1. Form Design

2. Field Validation

3. Workflow Integration

4. Data Management

​Quick Reference

​✅ When to Use Forms:

​❌ When NOT to Use Forms:

​Decision Tree

​What Are Forms?

​Common Use Cases

​Use Case 1: Resident Intake Form

​Use Case 2: Incident Report Form

​Use Case 3: Daily Inspection Checklist

​Examples by Module

​Recovery Housing (RH)

​Workforce (HR)

​Finance (FA)

​Governance (GR)

​Field Types Available

​Dropdown Options: Which to Use?

​Form Options (Inline)

​Picklists (PF-15)

​Lookups (FW-15)

​Integration with Workflows (FW-03)

​Anti-Patterns to Avoid

​❌ Using Forms for Entity Extension

​❌ Using Forms Instead of Custom Objects

​❌ Using Inline Options for Reusable Values

​❌ Using Forms for Database Records

​Best Practices

​1. Form Design

​2. Field Validation

​3. Workflow Integration

​4. Data Management

​Related Documentation

Quick Reference

✅ When to Use Forms:

❌ When NOT to Use Forms:

Decision Tree

What Are Forms?

Common Use Cases

Use Case 1: Resident Intake Form

Use Case 2: Incident Report Form

Use Case 3: Daily Inspection Checklist

Examples by Module

Recovery Housing (RH)

Workforce (HR)

Finance (FA)

Governance (GR)

Field Types Available

Dropdown Options: Which to Use?

Form Options (Inline)

Picklists (PF-15)

Lookups (FW-15)

Integration with Workflows (FW-03)

Anti-Patterns to Avoid

❌ Using Forms for Entity Extension

❌ Using Forms Instead of Custom Objects

❌ Using Inline Options for Reusable Values

❌ Using Forms for Database Records

Best Practices

1. Form Design

2. Field Validation

3. Workflow Integration

4. Data Management

Related Documentation