Filling Out Documents
Once a document instance has been assigned and the worker opens it, they enter the form-filling phase. This page covers the worker experience: how fields are displayed, how auto-fill works in practice, how progress is saved, and what validation rules apply before submission.
Form Layout
Document forms are rendered based on the template's field definitions. Fields are organized into sections (if defined) and displayed in sort order within each section.
Section Rendering
If a template defines sections, fields are grouped under section headers:
Personal Information
├── First Name .............. [Nathaniel] (auto-filled)
├── Last Name ............... [Maddox] (auto-filled)
├── Email ................... [hello@otesse.com] (auto-filled)
└── Phone ................... [(541) 555-0123] (auto-filled)
Address
├── Street .................. [123 Main St] (auto-filled)
├── City .................... [Eugene] (auto-filled)
├── State ................... [OR] (auto-filled)
└── ZIP ..................... [97401] (auto-filled)
Tax Information
├── SSN ..................... [***-**-4567] (auto-filled, masked)
└── Filing Status ........... [Select...] (manual entry)
Signature
├── Legal Name .............. [ ] (signature field)
└── Date .................... [auto-dated]Fields without a section assignment appear under a default "General" section.
Field Types
Each field type renders as an appropriate input control:
| Type | Input Control | Notes |
|---|---|---|
| text | Single-line text input | Standard text entry |
| textarea | Multi-line text area | For longer responses |
| date | Date picker | Calendar widget with manual entry fallback |
| number | Numeric input | With increment/decrement controls |
| boolean | Checkbox | For yes/no or acknowledgment fields |
| signature | Signature input | Special handling (see E-Signature Workflow) |
| address | Structured address group | Street, city, state, ZIP as connected fields |
| ssn | Masked text input | Shows last 4 digits, encrypts full value |
| bank_account | Masked text input | Similar masking behavior to SSN |
| phone | Phone input | With formatting and country code |
| Email input | With format validation | |
| select | Dropdown | Options defined in template field configuration |
Saving Progress
Workers do not need to complete a document in one sitting. The system saves field values individually:
- When a worker tabs away from a field or clicks elsewhere, the current field value is saved automatically
- Each save triggers the
saveFieldValuemutation, which persists the value to the instance data - If the instance status is "required," the first field save transitions it to "draft"
- Workers can close the form and return later — all saved values are preserved
- The form shows a subtle "Saved" indicator after each successful save
Save Behavior by Status
| Status | Can Save | Notes |
|---|---|---|
| Required | Yes (transitions to draft) | First save triggers status change |
| Draft | Yes | Standard editing mode |
| Pending Review | No | Locked during admin review |
| Completed | No | Permanently locked |
| Expired | No | Archived, read-only |
Validation Rules
Before a document can be submitted, all required fields must pass validation:
Field-Level Validation
| Rule | Behavior |
|---|---|
| Required field is empty | Red border, error message: "This field is required" |
| Email format invalid | Error message: "Enter a valid email address" |
| Phone format invalid | Error message: "Enter a valid phone number" |
| SSN format invalid | Error message: "Enter a valid Social Security number" |
| Date is invalid | Error message: "Enter a valid date" |
| Number out of range | Error message with min/max bounds |
Form-Level Validation
When the worker clicks "Submit" or "Sign," the system validates all fields at once:
- All required fields must have values
- All field-level validations must pass
- If any validation fails, the form scrolls to the first error and highlights all invalid fields
- The submit/sign button remains disabled until all validations pass
Auto-Fill Indicators
Auto-filled fields display a small indicator showing that the value came from the worker's profile. This gives workers confidence about where the data originated and whether they need to verify it:
- Auto-filled, not edited: Light blue background with "From your profile" tooltip
- Auto-filled, manually edited: Normal background, no indicator
- No auto-fill source: Normal background, standard empty field
Offline and Error Handling
- Network error during save: The system retries automatically. If the retry fails, a banner appears: "Unable to save. Check your connection and try again."
- Concurrent editing: If two browser tabs are open on the same document, the last save wins. This is an edge case (workers typically use one tab) but the system handles it gracefully.
- Session expiry: If the worker's session expires while filling out a form, unsaved changes in the current field are lost. The worker is prompted to log in again, and all previously saved fields are intact.
On this page