Deposit Release Acknowledgement Token Expiry Sweep
Deposit Release Acknowledgement Token Expiry Sweep
Introduced in: v0.1.314
Overview
The Deposit Release Acknowledgement Token Expiry Sweep is a nightly batch job that automatically identifies and expires pending acknowledgement tokens that have passed their expiry time. This prevents the deposit release workflow from silently stalling when a party fails to act on an acknowledgement link within the allowed window.
How It Works
Each day at 07:00 UTC, the sweep job runs and performs the following steps:
1. Identify Expired Tokens
The job queries depositReleaseAcknowledgements for any records matching:
status = 'pending'
AND tokenExpiresAt < NOW()
These are acknowledgements that were issued but never acted upon before their token expiry time.
2. Mark as Expired
Matched records have their status updated from pending to expired. This ensures the system has an accurate, up-to-date view of which acknowledgements are still actionable.
3. Notify Org Admins
A notification is created for the relevant organisation admins for each impacted deposit release. Admins are informed which acknowledgements have expired so they can take appropriate follow-up action.
4. Optional Re-send
The sweep can optionally dispatch a fresh acknowledgement link to the affected party. This allows the workflow to resume without requiring full manual re-initiation.
5. Audit Logging
All actions taken by the sweep — including which records were expired, which notifications were sent, and whether a re-send was triggered — are written to the auditLog for full traceability.
Re-proposal Requirement
If all pending acknowledgements for a given deposit release expire (i.e. no acknowledgement is still active), the deposit release itself may need to be re-proposed by the initiating party.
Org admins will be notified in this scenario so they can coordinate next steps with the relevant landlord, agent, or tenant.
Schedule
| Property | Value |
|---|---|
| Trigger | Scheduled (cron) |
| Cron expression | 0 7 * * * |
| Frequency | Daily |
| Time | 07:00 UTC |
Affected Entities
| Entity | Role in Sweep |
|---|---|
depositReleaseAcknowledgements | Primary target — stale pending records are marked expired |
depositReleases | Parent record — may require re-proposal if all child acks expire |
notifications | Created to alert org admins of expired tokens |
orgMembers | Used to identify admin recipients for notifications |
auditLog | Records all sweep actions for compliance purposes |
Why This Matters
Without this sweep, a deposit release could remain permanently in a pending state if a recipient never opened their acknowledgement link. This job ensures:
- No silent stalls — expired tokens are surfaced promptly rather than left undetected.
- Admin visibility — org admins are always informed when a workflow is blocked.
- Compliance integrity — the audit log captures every automated action for dispute-resolution evidence.
- Fair outcomes — all parties are given the opportunity to re-engage via the optional re-send mechanism rather than losing their position in the process.