Document Creation & Assignment

Every document in Otesse begins as an instance of a template. When a worker needs to complete a form — whether during onboarding, annual renewal, or a compliance check — the system creates a document instance linked to the appropriate template and the target worker. This page explains how instances are created, what data they contain, and how assignment works.

Instance vs Template

A template defines the structure: which fields exist, what type each field is, whether a signature is required, and how renewal works. An instance is a specific copy of that template assigned to a specific worker. Think of it like a class and an object — the template is the blueprint, and the instance is the filled-out form.

Instance Schema

Each document instance tracks its full lifecycle:

Field	Description
templateId	Which template this instance was created from
userId	The worker assigned to complete this document
status	Current lifecycle status (required, draft, pending_review, completed, expired)
assignedAt	When the document was assigned
startedAt	When the worker first opened the document
submittedAt	When the worker submitted the document
reviewedAt	When an admin reviewed the submission
signedAt	When the worker signed the document
expiresAt	When the completed document expires (based on renewal rules)
renewalNumber	0 for the first instance, increments on each renewal cycle
previousInstanceId	Links to the expired instance this one renews (null for first instance)

Assignment Methods

Documents can be assigned to workers through several paths:

1. Onboarding Assignment

When a new worker is added to the system, the onboarding flow automatically assigns all required documents. The assignment logic looks at each template's category and blocking status:

• Blocking templates are assigned first (W-4, I-9, Direct Deposit, Background Check Consent)
• Non-blocking templates follow (policy acknowledgments, emergency contact)
• State-specific templates are assigned based on the worker's state of residence

2. Manual Assignment

Administrators can manually assign any template to any worker from the Contracts & Forms module. This is used for:

• Assigning client-specific documents to workers servicing particular accounts
• Re-assigning documents that were previously waived
• Assigning new templates that were created after a worker's onboarding

3. Renewal Assignment

When a completed document expires, the system automatically creates a new instance (see Renewal Scheduling). The new instance:

• Links to the expired instance via previousInstanceId
• Increments the renewalNumber
• Starts at "required" status
• Uses the latest template version (not the expired instance's version)
• Pre-populates with current profile data (not data from the expired instance)

Initial Status: Required

Every new document instance starts with the status "required." At this stage:

• The document appears in the worker's forms list with a "Required" badge
• The worker has not yet opened or interacted with the document
• No auto-fill data has been written yet (auto-fill happens on first open)
• Blocking templates display prominently with a red indicator

The "required" status means the system knows the document needs to be completed, but the worker has not taken any action.

First Open: Transition to Draft

When a worker opens a required document for the first time and saves any field, the status automatically transitions to "draft":

1. The system reads the template's field definitions
2. For each field with an auto-fill source, it resolves the value from the worker's profile
3. Resolved values are written into the instance data
4. The instance status changes from "required" to "draft"
5. The startedAt timestamp is recorded

From this point forward, the document is in an active editing state. The worker can save progress, close and return later, and auto-fill fields stay in sync with profile changes.

Preventing Duplicates

The system enforces a one-active-instance rule: only one non-expired instance of a given template can exist for a worker at any time. This prevents duplicate assignments and ensures workers always see a single, clear action item for each document type.

If an administrator tries to assign a template that the worker already has an active instance of, the system shows a message: "This worker already has an active instance of this document."

Admin Dashboard Stats

The document statistics query provides administrators with real-time visibility:

Metric	Description
Total Templates	Count of all non-deleted templates in the system
Total Instances	Count of all non-deleted document instances
Status Counts	Breakdown by status: required, draft, pending_review, completed, expired
Blocking Expired	Count of expired instances where the template is blocking
Upcoming Renewals	Completed instances expiring within 30 days (sorted by soonest)

These metrics power the compliance dashboard cards and help administrators identify workers who need attention before documents expire.