Action Required Auto-Flagging
Action Required Auto-Flagging
The Action Required system automatically detects overdue tenancy events, flags them for the assigned agent, sends notifications, and clears flags once the issue is resolved — with no manual intervention needed.
How It Works
1. Daily Scan (7 AM UTC)
An Inngest cron job (action-required-scan) runs once per day and performs three operations in order:
- Auto-resolve existing flags — Any flag whose underlying condition has been resolved is cleared automatically (see Auto-Resolution below).
- Detect overdue move-ins — Tenancies where the start date is in the past and the status is still
pending(non-legacy tenancies only). - Detect overdue renewal decisions — Renewals where
decision_due_dateis in the past and the status is stilldecision_requiredorpending. These renewals are also transitioned toaction_requiredin the state machine.
Flags are deduplicated — if a flag already exists for a given resource, no duplicate is created.
2. Notifications
For each new flag, the scanner fans out a notification event handled by action-required-notify. The assigned agent receives:
- An in-app notification via the platform notification system.
- An email notification via Resend with a branded HTML template and a direct link to the relevant tenancy.
3. Dashboard Alert Panel
The ActionRequiredAlerts component is rendered at the top of the agent dashboard, above KPI cards. It is only shown when at least one unresolved flag exists.
Overdue Move-In (Red / High Severity)
Displayed when a tenancy's start date has passed but the tenant has not been moved in.
| Field | Description |
|---|---|
| Property address | The address of the affected property |
| Tenant name | The primary tenant on the tenancy |
| Due date | The original tenancy start date |
| Days overdue | Calendar days past the due date |
| Assigned agent | The agent responsible for the tenancy |
Action link: "Confirm Move-In" — links directly to the tenancy detail page.
Overdue Renewal Decision (Amber / Medium Severity)
Displayed when a renewal's decision due date has passed without a confirmed action.
| Field | Description |
|---|---|
| Property address | The address of the affected property |
| Tenant name | The tenant on the renewal |
| Decision due date | The date by which a decision was required |
| Days overdue | Calendar days past the decision due date |
| Assigned agent | The agent responsible for the renewal |
Action link: "Action Renewal" — links to the tenancies list.
4. Manual Dismissal
Every flag in the dashboard panel includes a dismiss button (✕). Clicking it calls dashboard.dismissActionFlag and immediately removes the flag from the panel and updates the portfolio metrics count.
Auto-Resolution
Flags are automatically cleared during the next daily scan without any agent action if:
| Flag Type | Resolved When |
|---|---|
| Overdue Move-In | Tenancy status changes to active |
| Overdue Renewal Decision | Renewal status progresses to renewal_in_progress, renewal_confirmed, renewed, set_to_end, or ended |
Dashboard Metrics
The Outstanding Items section on the agent dashboard includes action required flag counts. The badge variant switches to danger (red) whenever any action-required flags are present, alongside existing triggers for expired compliance or overdue todos.
portfolioMetrics now exposes actionRequired.total, which feeds into the total outstanding count displayed in the dashboard summary.
Database
Flags are persisted in the action_required_flags table:
| Column | Description |
|---|---|
id | Primary key |
flagType | overdue_move_in or overdue_renewal_decision |
resourceId | ID of the related tenancy or renewal |
assignedAgent | Agent user ID |
overdueDate | The date the event became overdue |
emailSent | Whether the Resend notification has been dispatched |
resolvedAt | Timestamp of auto- or manual resolution (null if open) |
A uniqueness constraint on (flagType, resourceId) prevents duplicate open flags for the same resource.
Inngest Functions
| Function ID | Trigger | Description |
|---|---|---|
action-required-scan | Cron — daily at 07:00 UTC | Scans for overdue events, auto-resolves closed flags, creates new flags, fans out notification events |
action-required-notify | Event — one per new flag | Sends in-app + email notification to the assigned agent |
Both functions are registered at /api/inngest.