Compliance → Alerts

Purpose

Surface compliance deadlines and critical conditions before they become problems — license expirations, biennial inventory due dates, reporting deadlines you track yourself, scheduled DEA inspections, and operator-defined alerts. Alerts have three severity tiers (info / warning / critical) and three states (active / resolved / dismissed).

This is general product information about CS Logbook, not legal advice. Alerts are a convenience aid; they do not define deadlines or certify compliance. Verify current requirements with the DEA Diversion Control Division and your state veterinary/pharmacy board.

Regulatory basis: the proactive surfacing of deadlines is a best-practice convenience that supports records compliance (DEA recordkeeping rules, record availability and retention) — it is not a regulation-mandated feature, and the underlying deadlines are set by the DEA and your state, not by CS Logbook.

When to use it

• Daily compliance review: open /compliance/alerts first thing each morning to see what needs attention
• License expiration approaching: the system auto-generates alerts at 90/60/30/14/7 days before each license expires
• Biennial inventory window opens: an alert fires 60 days before the biennial deadline so you have time to schedule
• DEA inspection scheduled: when you learn an inspector is coming, manually create an inspection_scheduled alert with the visit date
• Custom deadline tracking: any clinic-internal compliance deadline (renewal of a state-specific permit, training certification expirations) can be captured as an other alert

Walkthrough

Step 1 — Open the alerts page

Navigate to /home/<your-clinic>/compliance/alerts. Three tabs:

• Active Alerts — unresolved alerts, sorted by severity (critical → warning → info) then due date
• Critical Alerts — same data filtered to severity=critical; useful for daily focus
• Resolved Alerts — alerts that were marked resolved or dismissed (preserves audit trail)

If the clinic has critical alerts open, a destructive banner across the top of the page summarizes the count and links to the critical tab.

Step 2 — Create an alert

Click Create Alert in the top-right (only visible to users with canManageCompliance — owners/admins/managers).

Fill in 4 required fields + 2 optional:

• Alert Type: pick the closest category. license_expiration, biennial_inventory_due, pdmp_submission_due, inspection_scheduled, or other. The DB CHECK accepts these 5 plus 5 system-only values reserved for auto-generated alerts. You set every alert yourself; CS Logbook does not know your reporting cadence and does not create these for you.
• Severity: info (FYI), warning (action needed soon), or critical (action needed now)
• Title: short summary, ≤255 chars
• Message: full description, multiline OK
• Due Date (optional): YYYY-MM-DD; surfaces in the alerts list and drives sort order
• Action URL (optional): link to the resource that resolves the alert (e.g., the renewal portal URL)

Click Create Alert. The new alert appears on the Active Alerts tab.

Step 3 — Resolve, dismiss, or snooze an alert

On any active alert, the row's Actions menu offers:

• Resolve Alert — marks the alert resolved (resolved=true, resolved_at=now(), resolved_by=user.id). Use when the underlying compliance issue is genuinely fixed.
• Snooze Alert — temporarily hides the alert until a future datetime. Use when you've acknowledged it but action is deferred. (Snooze UI is deferred to Sprint B — see CHANGELOG.)
• Dismiss Alert — marks the alert resolved with a DISMISSED: prefix on the resolution notes. Use when the alert is a false positive or no longer applicable.

After Resolve, the alert moves to the Resolved Alerts tab. Resolved alerts are read-only — the Actions menu reduces to a single View Details entry.

Field reference

Alert form

Hidden fields auto-populated:

• account_id (the team account UUID)
• resolved (default false)
• created_at, updated_at
• On resolve: resolved, resolved_at, resolved_by, resolution_notes
• On dismiss: same as resolve, with resolution_notes prefixed DISMISSED:

The DB CHECK on alert_type accepts the 5 form values plus 5 system-only values reserved for auto-generated alerts: audit_deadline, pdmp_submission, low_balance, discrepancy, transaction_approval. End users only see the 5 form values; the system reserves the others for cross-feature alert generation. Nothing writes them today, so in practice every alert in your clinic is one a person created.

Edge cases

Duplicate-detection on related entity

If you provide relatedEntityId (UUID of a license, audit, or container) when creating an alert, the action checks whether an unresolved alert already exists for that entity + alert type. If yes, it returns success without creating a duplicate ({success: true, duplicate: true}). This prevents alert spam from auto-generators.

Auto-generated alerts vs manual

The 4 system-only alert types are reserved for cross-feature alert generators (e.g., the biennial-inventory due-date generator inserts audit_deadline alerts). Manual alerts created via the UI use the 5 user-facing types.

Dismiss vs resolve

Both set resolved=true and resolved_at=now(). The difference is the resolution_notes content: resolve uses your provided notes; dismiss prefixes the reason with DISMISSED:. Reports filter on this prefix when distinguishing genuine resolutions from dismissals.

Common mistakes

• Resolving an alert without fixing the underlying issue. A resolved alert is a claim that the compliance issue is fixed. If you're just acknowledging, use snooze or dismiss instead.
• Marking critical alerts as info. Severity drives the alerts banner, the daily focus view, and any future paging integrations. A genuinely critical alert (license expired, biennial overdue) must be marked critical so it surfaces correctly.
• Forgetting to use the action URL field. A well-formed actionUrl (e.g., the state's online renewal portal) makes the alert actionable in one click.

Related

• Compliance → Licenses — license expirations are the most common alert source
• Audits → Biennial Inventory — the biennial-due alert points users to this flow
• Audits → DEA Audit Prep — pending DEA inspections may have alerts
• Glossary § DEA CFR citations