Tenant Status Auto-Lifecycle Sweep
Tenant Status Auto-Lifecycle: How the Nightly Sweep Works
Keeping tenant records accurate is fundamental to fair and compliant tenancy management. As of v0.1.280, the platform automatically maintains each tenant's lifecycle status through a nightly background sweep — eliminating the need for manual updates and reducing the risk of stale or incorrect data.
The Problem It Solves
Tenant status (prospective, active, former) must reflect the real-world state of a person's tenancy at any given time. When managed manually, this status can fall out of sync — a tenant who has moved in may still appear as prospective, or a tenant whose tenancy ended months ago may still appear as active. Inaccurate status creates downstream problems: incorrect communications, flawed reporting, and compliance risk under the Renters' Rights Act.
How It Works
Every night at 02:00 UTC, a scheduled cron job sweeps all tenant records and evaluates them against their linked tenancies via the tenancyTenants join. It applies the following rules:
Transition 1: prospective → active
Condition: One or more of the tenant's linked tenancies has a status of active.
As soon as a tenancy moves to active — meaning the tenant has moved in — the tenant's own status is automatically promoted to active.
Transition 2: active → former
Condition: All of the tenant's linked tenancies are in a terminal or archived state (ended, disputed, or archived), and no upcoming or currently active tenancy exists.
This ensures that a tenant with multiple tenancies is not incorrectly marked as former while still holding an active or upcoming tenancy elsewhere in the system.
Audit Logging
Every automated status transition writes an entry to the audit log, recording:
- The tenant whose status changed
- The previous status
- The new status
- The timestamp of the transition
This provides a complete, immutable history of all lifecycle changes, supporting both internal review and regulatory compliance.
Entities Involved
| Entity | Role |
|---|---|
tenants | Record whose status field is evaluated and updated |
tenancyTenants | Join table linking tenants to one or more tenancies |
tenancies | Source of truth for tenancy status (active, ended, disputed, archived) |
Schedule
| Property | Value |
|---|---|
| Cron expression | 0 2 * * * |
| Frequency | Daily |
| Time | 02:00 UTC |
| Type | Nightly batch |
What You Don't Need To Do
This process runs entirely in the background. No configuration, API calls, or manual steps are required. Tenant statuses will automatically reflect the correct lifecycle state after each nightly run.
If you believe a tenant's status is incorrect outside of a scheduled run window, you can still manually override tenant.status — the next sweep will only apply a transition if the criteria above are met at that time.