Tenant Deduction Notification Expiry Sweep

Available from: v0.1.203

Overview

The Tenant Deduction Notification Expiry Sweep is a nightly automated batch job that monitors outstanding tenant deduction notifications and marks them as expired when the tenant has not responded by their deadline. Org admins are notified automatically so that the deposit deduction workflow can be progressed without delay.

How It Works

Each night at 06:00 UTC, the sweep runs and performs the following steps:

Query — Fetches all tenantDeductionNotification records where:
- status is pending or in_progress, and
- tokenExpiresAt is earlier than the current date (i.e. the access token has expired).
Update — For each matching record, sets status → expired.
Notify — Sends a notification to every org admin within the associated organisation, informing them that the tenant did not respond within the deadline.

Schedule

Field	Value
Cron expression	`0 6 * * *`
Frequency	Daily
Trigger time	06:00 UTC
Trigger type	Scheduled (nightly batch)

Affected Entities

Entity	Change
`tenantDeductionNotifications`	`status` updated to `expired` for overdue records
`notifications`	New notification record created per org admin
`organizations`	Org admins queried to determine notification recipients

Status Lifecycle

pending ──────────────────────────────────────────► expired
                 (tokenExpiresAt < today,
                  swept by nightly job)

in_progress ─────────────────────────────────────► expired
                 (tokenExpiresAt < today,
                  swept by nightly job)

The expired status is terminal — a notification in this state will not be re-processed by subsequent sweeps.

Org Admin Notifications

When a tenant notification is expired by the sweep, each org admin of the associated organisation receives a notification containing:

Confirmation that the tenant did not respond before the deadline.
Context identifying the relevant deduction notification.

This allows admins to decide on next steps — such as escalating to a formal deposit dispute or contacting the tenant directly.

Notes

Only notifications whose tokenExpiresAt is strictly before the current date are swept. Notifications expiring today are not affected until the following day's run.
The sweep does not re-send tenant-facing notifications. It solely progresses the internal workflow state and alerts org admins.
If no qualifying records exist on a given day, the job completes silently with no changes.