Renewal Scheduling

Documents can be configured with one of three renewal models: none (one-time), calendar-based (fixed date), or signature-date-based (relative to signing). The renewal system handles expiry detection, reminder notifications, grace periods, and automatic creation of new document instances — keeping the workforce compliant without manual intervention.

Renewal Types

None — One-Time Documents

The document is signed once and never expires.

Property	Value
Examples	Background Check Consent, Equipment Checkout, Emergency Contact Form
Expiry	Never
Reminders	None
New instance	Only created if an admin manually re-assigns

Use this for documents that establish a one-time agreement or capture static information that does not need periodic re-verification.

Calendar — Fixed Date Renewal

The document expires on the same calendar date every year, regardless of when it was signed.

Property	Value
Examples	W-9 (Dec 31), Employee Handbook (Jan 1), Anti-Harassment Policy (Jan 1)
Configuration	`renewalMonth` (1-12) and `renewalDay` (1-31)
Calculation	Next occurrence of month/day after the signing date

Calendar renewal aligns with regulatory deadlines. For example, the W-9 expires December 31 because the IRS requires an updated form for each tax year. If a worker signs the W-9 on December 15, it expires December 31 of the same year (just 16 days later). The next renewal would be December 31 of the following year.

Signature-Based — Relative to Signing Date

The document expires a fixed number of months after the worker signs it.

Property	Value
Examples	I-9 (36 months), NDA (12 months), Vehicle Insurance Proof (6 months), Safety Training (12 months)
Configuration	`renewalDurationMonths`
Calculation	`signedAt + renewalDurationMonths`

Signature-based renewal is used for certifications and agreements where the validity period starts from the moment of signing. An NDA signed February 15 with a 12-month duration expires February 15 of the following year.

Reminder Notifications

Reminders are sent at configurable intervals before the expiry date. The default schedule sends notifications at 30, 14, 7, and 1 day before expiry.

Days Before	Worker Notification	Admin Notification
30 days	"Your [document] expires in 30 days. Please review and renew."	Included in weekly digest
14 days	"Your [document] expires in 14 days. Action required."	Included in weekly digest
7 days	"Your [document] expires in 7 days. Renew now to avoid disruption."	Individual notification
1 day	"Your [document] expires tomorrow. Immediate action required."	Individual notification

Reminder Rules

Reminders are sent via in-app notification and email
Administrators receive a weekly digest summarizing all upcoming expirations
Custom intervals can be set per template via the reminderDaysBefore array
Reminders stop once the worker completes the renewal instance

Grace Period

The grace period is the window after expiry before blocking effects take hold:

Property	Value
Default	0 days (blocking is immediate on expiry)
Configurable	Per template via `gracePeriodDays`
During grace	Worker can still accept jobs but sees a warning banner
After grace	If the template is blocking, the worker is blocked from job assignment

Grace Period Example

Document expires: March 1
Grace period: 7 days

March 1    → Status: expired. Banner: "Your W-9 has expired. Renew within 7 days."
March 1-7  → Worker can still accept jobs. Warning banner visible.
March 8    → Grace period ends. Worker blocked from job assignment.

Renewal Flow

When a document reaches its expiry date, the system executes four steps:

Step 1: Archive Old Instance

The expired instance's status is set to "expired" with an archivedAt timestamp. The instance remains in the database as a permanent record — expired documents are never deleted.

Step 2: Create New Instance

A new instance is created with:

The latest template version (not the expired instance's version)
The same worker assignment
Status set to "required"
previousInstanceId linking to the expired instance
renewalNumber incremented from the expired instance
Auto-fill data from the worker's current profile (not copied from the expired instance)

Step 3: Notify Worker

The worker receives a notification: "Your [document name] has expired and a new version is ready for review."

Step 4: Worker Reviews and Re-Signs

The new instance follows the normal lifecycle: required, draft (on first open), submission, and completion. The worker reviews their pre-populated data, makes any necessary corrections, and signs the renewed document.

Key Rules

Old instances are never deleted — They are archived for full audit trail
New instances use the latest template version — Template updates are picked up on renewal
Auto-fill uses current profile data — Not data from the expired instance
Each signed version is independently immutable — A worker may have multiple completed instances over time
Renewal is automatic — The system creates the new instance without admin intervention
The worker must still act — The new instance starts at "required" and the worker must complete it

Edge Cases

Scenario	Behavior
Calendar renewal on leap year (Feb 29)	Uses February 28 in non-leap years
Worker signed yesterday, template updated today	Signed instance unaffected. New fields appear on next renewal
Multiple active instances of same template	Prevented — one non-expired instance per worker per template
Worker deactivated before renewal	Deactivated workers do not receive renewal instances. Admin re-assigns if reactivated