Landlord Portal: 'Changes Requested' → Agent Task Assignment

Available from: v0.1.353

Overview

When a landlord reviews a deposit release proposal via the Landlord Portal and requests changes rather than approving outright, the platform automatically converts that decision into an actionable agent task. No manual monitoring required.

This feature is fully event-driven — it triggers on the landlord_portal.decision event and requires no manual configuration per tenancy.

How It Works

1. Trigger

The workflow activates when a landlordPortalInvites record transitions its status to changes_requested. This happens when the landlord submits their response through the portal indicating they want modifications to the proposed deductions or release terms.

2. Parsing Requested Changes

The function reads the requestedChanges JSONB array attached to the invite record. Each item in the array represents a discrete change the landlord is requesting (e.g. a revised deduction amount, a disputed line item, or an added charge).

3. Task Notification Creation

An in-app task notification is created and delivered to:

Property Manager role — the team member with property management responsibility for the associated deposit release.
Release Creator — the agent who originally created and sent the deposit release proposal.

The notification contains contextual information drawn from the linked depositReleases and depositReleaseDeductions records, giving the recipient full context without needing to navigate manually.

4. Negotiation Thread (Optional)

If the landlord has included free-text comments alongside their change requests, the system can optionally:

Open a new negotiation thread linked to the deposit release.
Post the landlord's comments as the first message in that thread.

This immediately establishes a documented communication record and gives agents a structured place to respond, counter-propose, or agree.

Entities Involved

Entity	Role
`landlordPortalInvites`	Source record; holds `changes_requested` status and `requestedChanges` JSONB array
`depositReleases`	Provides deposit release context for the task
`depositReleaseDeductions`	Provides line-item deduction detail
`negotiationThreads`	Created (if landlord comments are present)
`negotiationMessages`	Landlord's comments posted as the opening message
`notifications`	In-app task notifications sent to property manager and release creator

Workflow Diagram

Landlord Portal Decision
        │
        ▼
 [landlord_portal.decision event]
        │
        ▼
  Status = changes_requested?
        │
    Yes ▼
  Parse requestedChanges JSONB
        │
        ├──────────────────────────────────┐
        ▼                                  ▼
Create task notification          Landlord comments present?
  → Property Manager                       │
  → Release Creator               Yes ─────┤
                                           ▼
                                 Open negotiation thread
                                 Post landlord comments
                                 as first message

Notes for Agents

Check your notifications — When a landlord requests changes, you will receive an in-app task notification. Act on it promptly to stay within any statutory response windows under the Renters' Rights Act.
Negotiation thread — If a thread has been opened automatically, reply directly in the thread rather than via separate communication channels to maintain a complete audit trail.
requestedChanges detail — The full list of requested changes is available by opening the associated deposit release record. Each item in the list corresponds to a specific landlord objection.

Related Features

Deposit Release Proposals
Negotiation Threads
In-App Notifications
Landlord Portal Invites