Disputed Deposit Release: Auto-Compliance-Check Workflow
Disputed Deposit Release: Auto-Compliance-Check Workflow
Introduced in v0.1.257
Overview
When a deposit release is disputed, a sequence of compliance and notification steps must happen quickly and consistently. The Disputed Deposit Release Auto-Compliance-Check workflow automates this entirely — from the moment a dispute is raised, the platform updates records, checks compliance, and notifies every relevant party without any manual action.
Trigger
| Property | Value |
|---|---|
| Event | deposit/release.disputed |
| Type | Event-driven state machine |
| Timing | Immediate — fires synchronously on event receipt |
The workflow is triggered whenever a deposit_release record transitions into the disputed state.
Workflow Steps
1. Set Tenancy Status → disputed
The associated tenancy record has its status field updated to 'disputed'. This ensures the tenancy's state is immediately consistent with the dispute and is correctly reflected across all views, filters, and downstream workflows that depend on tenancy status.
2. Run Compliance Checks
The full compliance check suite is executed against the tenancy. This covers relevant obligations under the Renters' Rights Act and deposit-handling rules. Any compliance failures are recorded against the tenancy and surfaced to admins.
Compliance checks run at dispute-open time so that:
- Violations are identified before any resolution process begins.
- Evidence of compliance (or non-compliance) is timestamped to the moment the dispute was raised.
- Org admins have an accurate compliance picture when they respond.
3. Fire tenancy/dispute.opened Domain Email
An email notification is sent to all parties associated with the tenancy:
- Tenant — informed that their deposit release is under dispute.
- Landlord — informed that the release has been disputed and the reason on record.
- Agents (where applicable) — notified of the dispute to coordinate response.
The email uses the tenancy/dispute.opened domain template and includes the dispute reason.
4. Insert Critical In-App Notification for Org Admins
A critical-priority in-app notification is created for all org_members with an admin role. The notification includes:
- The deposit release and tenancy identifiers.
- The dispute reason as recorded on the
deposit_release. - A direct link to the relevant tenancy record.
Critical notifications appear prominently in the admin dashboard and are not dismissible until acknowledged.
Entities
| Entity | Operation |
|---|---|
deposit_releases | Read — source of the disputed event and dispute reason |
tenancies | Write — status updated to 'disputed' |
tenants | Read — used to address dispute email |
landlords | Read — used to address dispute email |
org_members | Read — used to target admin notifications |
notifications | Write — critical in-app notification inserted |
audit_log | Write — all state changes and notifications are logged |
Audit Trail
Every action taken by this workflow — the status update, compliance check results, emails fired, and notifications created — is written to the audit_log. This provides a tamper-evident, timestamped record of the platform's response to the dispute, which can be referenced during resolution or in any formal proceedings.
Notes
- This workflow does not resolve the dispute — it opens and records it. Dispute resolution is handled by a separate process.
- Compliance check failures raised during this workflow are informational at dispatch time; they do not block the dispute from being opened.
- If a tenancy is already in
'disputed'status when the event fires (e.g. a duplicate event), the workflow is idempotent for the status update step.