Tenant Portal Invite Auto-Expiry

A scheduled background workflow automatically expires stale tenant portal invites every day at 06:00 UTC. This keeps invite state accurate, surfaces re-invite actions to the right people, and maintains a full audit trail.

How It Works

Schedule

The workflow runs on a daily cron: 0 6 * * * (06:00 UTC).

Detection

The job queries tenantPortalInvites for any record matching both conditions:

Condition	Value
`status`	`'pending'`
`expiresAt`	`< NOW()`

Only invites that are still in a pending state and have passed their expiry timestamp are affected. Invites that have already been accepted, declined, or manually cancelled are ignored.

Actions

For each matched invite the workflow performs the following steps in order:

Update invite status — Sets tenantPortalInvites.status to 'expired'.
Write audit log — Inserts a record into auditLog capturing the expiry event, the invite ID, and the timestamp.
In-app warning notification — Creates a notifications entry targeted at the agent who originally sent the invite (invitedById), informing them that the invite has expired and a re-invite is needed.
Org admin notification (optional) — Notifies org admins via orgMembers that a tenant portal re-invite is required for the affected tenant.

Entities Affected

Entity	Operation
`tenantPortalInvites`	`UPDATE status → 'expired'`
`auditLog`	`INSERT` expiry event
`notifications`	`INSERT` in-app warning for `invitedById` agent
`tenants`	Read (to identify affected tenant)
`orgMembers`	Read (to identify org admins for optional notification)

Agent Experience

When an invite you sent expires overnight, you will see an in-app warning the next time you log in. The notification will indicate:

Which tenant's invite has expired
That a new invite needs to be sent

To resolve the warning, navigate to the tenant's record and issue a fresh portal invite.

Org Admin Experience

Org admins may receive a notification when one or more tenant portal invites expire within their organisation. This allows admins to monitor re-invite activity and ensure no tenants are left without portal access for extended periods.

Audit Trail

Every auto-expiry event is recorded in the auditLog. This provides a tamper-evident history of invite lifecycle events, which is important for demonstrating compliance with the Renters' Rights Act and for resolving any disputes about when and how portal access was offered to a tenant.

Frequently Asked Questions

Q: Will an invite expire mid-day if its expiresAt passes during business hours? The sweep only runs once per day at 06:00 UTC. An invite whose expiresAt passes at, say, 14:00 UTC on a Tuesday will be marked expired during the sweep at 06:00 UTC on Wednesday.

Q: Can I stop the workflow from expiring a specific invite? The workflow targets all invites matching the status + expiry criteria. To prevent an invite from being swept, either accept it before it expires or cancel and re-issue it manually before the cron runs.

Q: Is a tenant notified when their invite expires? The current implementation notifies the sending agent and optionally org admins. Direct tenant notification on expiry is not part of this workflow — the recommended path is for the agent to re-issue the invite.