Template Versioning

Document templates evolve over time — fields are added, descriptions are updated, and regulatory changes require form modifications. Otesse's versioning system ensures that template updates never compromise the integrity of previously signed documents while keeping new instances current with the latest requirements.

How Versioning Works

Every template has a version number that starts at 1 and increments each time the template is modified. When a document is signed, the signature record captures the template version at that moment. This creates an immutable link between the signed document and the exact template definition that was in effect.

Version Lifecycle

Event	Version Behavior
Template created	Version = 1
Template fields modified	Version increments (e.g., 1 to 2)
Template metadata updated (name, description)	Version increments
Renewal/blocking rules changed	Version increments
Document instance created	Instance references the current (latest) version
Document signed	Signature records the version at signing time
Renewal creates new instance	New instance uses the latest version, not the expired instance's version

What Triggers a Version Increment

• Adding a new field to the template
• Removing a field from the template
• Changing a field's type, label, or requirements
• Modifying the template description or name
• Changing signature, blocking, or renewal configuration

What Does NOT Trigger a Version Increment

• Reordering fields (sort order changes)
• Cosmetic changes to help text or placeholder text
• Changes to the template's sort order in the category list

Impact on Existing Documents

Completed Documents (Signed)

Completed documents are permanently frozen. They reference the template version that was active at signing time:

• If the W-4 was version 3 when a worker signed it, that signed document is forever associated with version 3
• If the W-4 is later updated to version 4 (adding a new field), the signed document still shows version 3 content
• The signed document's fields, values, and structure cannot change regardless of template updates

This is critical for legal compliance — a signed document must be an accurate record of what the worker agreed to at the time of signing.

Draft Documents

Draft documents always display the form defined by the template version they were created with. If a template is updated while a worker has an open draft:

• The draft continues to use the version it was created with
• The worker completes and signs the form as they see it
• On next renewal, the new instance will use the updated version

Renewal Instances

When a completed document expires and a renewal instance is created:

1. The new instance uses the latest template version, not the expired instance's version
2. This ensures renewed documents always capture the most current fields and requirements
3. If new fields were added, the worker sees them during renewal
4. Auto-fill populates the worker's current profile data (not data from the expired instance)

Viewing Version History

Administrators can view a template's version history in the template detail drawer:

Column	Description
Version	Version number (e.g., v1, v2, v3)
Changed	Timestamp of the version change
Changed By	Administrator who made the change
Fields	Number of fields in that version
Active Instances	Count of non-expired instances using this version
Signed Instances	Count of completed documents signed under this version

This gives administrators visibility into how a template has evolved and how many documents are associated with each version.

Seed System and External IDs

Templates are managed through a seed system that uses external IDs for idempotent creation:

• Template external IDs follow the pattern dtpl-[slug] (e.g., dtpl-w4, dtpl-state-w4-or)
• Field external IDs are auto-generated: {templateExternalId}-field-{fieldName}

The seed uses upsert logic — if a template with a given external ID already exists, it patches the existing record rather than creating a duplicate. This allows the seed to be run repeatedly without data duplication, which is essential for deploying template updates across environments.

Running the Seed

Templates are deployed as a Convex mutation:

npx convex run documents/seed:seedDocumentTemplates

This command processes all template definitions, creates or updates templates and their fields, and reports the count of created versus updated records.

Best Practices

1. Review before updating — Check how many active instances exist for the current version before making changes. Workers with in-progress drafts will not see your updates until their next renewal.
2. Communicate changes — When updating templates that affect many workers (like the annual W-4 update), send a notification explaining what changed and why.
3. Test with a draft — Create a test instance after updating a template to verify that all fields render correctly and auto-fill mappings still work.
4. Track regulatory changes — Set calendar reminders for annual form updates (IRS form revisions, state tax form changes) and update templates proactively before the renewal cycle begins.