> ## 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: Forms

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

**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:**

1. Create form in Form Builder
2. Add fields: name, date\_of\_birth, medical\_needs (yes/no), emergency\_contact
3. Add conditional logic: show medical\_history if medical\_needs = yes
4. Add validation: date\_of\_birth must be in past
5. 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:**

1. Create form with: incident\_type, date\_time, location, description, severity
2. Add file upload for evidence
3. Add workflow: on submit → notify manager → create task
4. 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:**

1. Create form with checkbox fields for each inspection item
2. Add signature field for inspector
3. Set up recurrence (daily reminder via workflow)
4. 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          |

***

## Dropdown Options: Which to Use?

### 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:**

1. **Approval Workflow**: Submit → Route to approver → Approve/Reject → Notify submitter
2. **Notification Workflow**: Submit → Notify stakeholders → Archive
3. **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

***

## Related Documentation

* [Picklists Use Case Guide](./picklists.md) - Reusable dropdown values
* [Custom Fields Use Case Guide](./custom-fields.md) - Extend existing entities
* [Custom Objects Use Case Guide](./custom-objects.md) - Create new entities
* [Data Manager Use Case Guide](./data-manager.md) - Browse and manage data
* [Clarity Analysis](./clarity-analysis.md) - Feature comparison matrix
* [FW-01 Specification](../../../specs/fw/archive/FW-01-form-builder.md)
* [PF-09 Form Analytics](../../../specs/pf/specs/PF-09-form-analytics.md)
* [FW-27 Advanced Analytics](../../../specs/fw/specs/FW-27-form-analytics-insights.md)

***

**Last Updated:** 2025-12-05