Task Management

Trust tier roll-up

RBAC matrix (IC 0–100 scale)

Skills-based routing RBAC: Only users at level ≥ 55 (senior biller) or ≥ 70 (practice manager) can configure skills-based routing rules. Skill tags are assigned by the practice manager and stored as user attributes. The routing engine matches task TaskTypeString and SourceModuleString against assignee skill tags.

FK Relationship Diagram

erDiagram
    Patient ||--o{ WorkTask : "subject"
    User ||--o{ WorkTask : "AssignedToUserID"
    User ||--o{ WorkTask : "CreatedByUserID"
    WorkTask ||--o{ TaskStatusHistory : "tracks"
    User ||--o{ TaskStatusHistory : "ChangedByUserID"
    WorkTask ||--o{ TaskTimeLog : "logged against"
    User ||--o{ TaskTimeLog : "UserID"
    

SLA Auto-Escalation Flow

flowchart TD
    A[Task created with SlaDeadlineDateTime] --> B{SLA engine checks every 5 min}
    B -- Deadline not reached --> B
    B -- Deadline approaching: 1hr warning --> C[Notify assigned user]
    C --> B
    B -- Deadline breached --> D{Task still open?}
    D -- No --> E[No action]
    D -- Yes --> F[Escalate to Practice Manager]
    F --> G[Priority upgraded to Urgent]
    G --> H[Re-assign if unacknowledged after 30 min]
    H --> I[Create escalation entry in TaskStatusHistory]
    

Functional Requirements

1. P0 The system SHALL create work tasks automatically when triggering events occur (denial received, co-sign needed, RxRenewal request, referral auth pending, PA decision needed).
2. P0 The system SHALL track task status through the full lifecycle (Draft through Completed/Cancelled/EnteredInError) with immutable history.
3. P0 The system SHALL enforce SLA deadlines and auto-escalate to Practice Manager when deadlines are breached.
4. P0 The system SHALL support task assignment to specific users and reassignment by authorized roles.
5. P0 The system SHALL map WorkTask to FHIR R4 Task resource for interoperability.
6. P1 The system SHALL provide a unified worklist with filtering by TaskType, Priority, Status, AssignedToUserID, and SLA proximity.
7. P1 The system SHALL support task macros that automate multi-step workflows (appeal letters, follow-up sequences, payer call scripts).
8. P1 The system SHALL track time spent per task via TaskTimeLog for productivity reporting.
9. P1 The system SHALL display AI-suggested actions when available and allow clinicians/billers to accept or dismiss suggestions.
10. P1 The system SHALL link tasks to their source entity (Claim, Prescription, Referral) for one-click navigation.
11. P1 The system SHALL support co-sign request tasks that block the source entity until a supervising clinician signs.
12. P2 The system SHALL provide task volume and turnaround-time dashboards for practice managers.
13. P2 The system SHALL support bulk task assignment and status updates for worklist efficiency.
14. P2 The system SHALL allow Practice Managers to override SLA deadlines with documented justification.
15. P2 The system SHALL support DocumentCollection task type with checklist of required documents and completion tracking.
16. P2 The system SHALL allow patients to view their task status (e.g. "referral auth in progress") via the patient portal.

Non-Functional Requirements

• Latency: Worklist query returns within 500ms for up to 10,000 active tasks per organization.
• SLA Engine: Escalation checks run every 5 minutes; notification delivery within 30 seconds of breach detection.
• Availability: Task creation service 99.95% uptime; queued retry for transient failures.
• Audit: Every status transition logged in TaskStatusHistory; immutable; retained 7 years.
• Scalability: Support 50,000 active tasks per organization without degradation.
• Macro Execution: Macro action sequences execute within 5 seconds; failures roll back to previous state.
• FHIR Compliance: WorkTask exportable as FHIR R4 Task resource; status codes mapped per FHIR value set.
• Time Logging: TaskTimeLog entries are append-only; edits create new entries with correction flag.

icApplication Overrides

How the four Task Management AMI schemas turn into a live application: module-specific stack additions, override component bindings, FHIR R4 Task resource production, Twilio voice/SMS & SES email integration, a versioning worked example, environment cascade, and RBAC enforcement.

Technology stack P0

The shared platform stack (Cosmos DB, Redis, IC-generated API, Angular 21, SQS+SNS, OpenTelemetry, etc.) is documented in the IC Reference. Module-specific additions:

Task Management–specific override bindings P0

These overrides are declared in rules/*.rules.json and replace the default for the matching field name pattern.

FHIR R4 Task resource production P0

The system projects every WorkTask as a FHIR R4 Task resource for interoperability with payer systems. The FHIR Task endpoint is read-only and supports the standard FHIR search parameters:

The FHIR Task endpoint is secured via SMART on FHIR scopes. The CMS-0057-F Provider Access API consumer reads payer-side Task resources (PA status, claim adjudication) and writes the results back to WorkTask. The Task profile is registered in the rev.health FHIR CapabilityStatement.

Twilio voice/SMS & SES email integration P1

Payer follow-up logging uses three communication channels, each with a dedicated adapter and webhook handler:

Every logged interaction creates a TaskTimeLog entry with the duration auto-captured from Twilio call duration or manually entered for email/SMS. The interaction metadata is stored as a JSON-structured ActionString200 value (e.g., Payer call — 12 min — spoke with John D., appeal #12345 approved pending medical records).

Versioning — worked example P0

All Task Management artifacts are versioned break.feature.bug.buildtimestamp per IC hard rule #9. The example below traces a feature bump on WorkTask.

WorkTask 1.0.0.20260301T120000Z — Initial schema. 12 business fields plus four org-scoped audit columns. Component ic-ng21-task-1-work-queue and ic-ng21-task-1-task-detail bind to work-task@1.0.0.* via the DI manifest.

WorkTask 1.1.0.20260515T093000Z — feature bump — Adds a single optional field, EscalationLevelInt, to track how many times a task has been auto-escalated. Per the IC change matrix:

Because the change is backward-compatible, the component tag stays ic-ng21-task-1-work-queue. Existing UI consumers continue to bind work-task@1.x.* and ignore the new field. New UI surfaces that need escalation-level display bind work-task@^1.1.0. No new database is required (IC rule #13 only applies to break bumps).

WorkTask 2.0.0.20280101T120000Z — break bump (illustrative) — An illustrative future break bump: StatusString50 is split into separate coded fields (StatusCodeString50, StatusReasonString100, StatusDetailText) to support FHIR Task.statusReason. Per the IC change matrix this is change field type + add required fields — break bump, EditAMI (90) approval, and per IC rule #13 a new database is provisioned with ETL from the old one. The component tag becomes ic-ng21-task-2-work-queue; consumers must re-bind. The old database stays live for the configured grace period (default 90 days) for rollback.

Task Management environment details

Task Management RBAC notes

• Assignment and SLA. WorkTask write requires level ≥ 40; assignment requires ≥ 55; SLA override requires ≥ 70. Macro creation requires ≥ 70.
• Skills-based routing. Skill tags are stored as user attributes (not in the WorkTask schema). The routing engine reads skill tags from the user profile and matches against task routing rules. Skill tag management requires level ≥ 70 (practice manager only).
• FHIR API. The FHIR Task endpoint enforces SMART on FHIR scopes. Read access requires Task.read scope; the endpoint filters results by the caller’s org via partition key. No write access through the FHIR Task endpoint (writes go through the generated API).
• Payer follow-up logging. Twilio voice/SMS and SES email adapters enforce consent checks before any outbound communication. Voice calls to payer business lines require task-context verification. SMS requires TCPA opt-in. Email requires CAN-SPAM unsubscribe link.

Cross-Module Dependencies

• RCM — denials from 835 posting automatically create WorkTask rows; appeal submission and resolution update the claim record in RCM. Task Management is the primary consumer of RCM denial events.
• eRx / EPCS — RxRenewal, RxChange, and ePA decision requests from the Surescripts connector create tasks assigned to the prescriber. EPCS co-sign requests create tasks routed to the supervising physician.
• Referrals — referral authorization requests and specialist response follow-ups create tasks assigned to the referring provider or the referral coordinator.
• Eligibility — prior-authorization tasks for medical-benefit PA (X12 278 / Da Vinci PAS) are created when the eligibility check detects a PA requirement. PA status updates from CMS-0057-F flow back to Eligibility.
• Patient Portal — patient-facing tasks (appointment reminders, document upload requests, balance inquiries) surface in the portal and sync status with the internal task queue.
• Coding / CDS — clinical documentation referenced in appeal letter templates is sourced from the clinical record maintained in Coding / CDS and Clinical Documentation.
• Data Model — WorkTask, TaskStatusHistory, TaskMacro, and TaskTimeLog are org-scoped per the operational-is-org-scoped pattern. Patient and User referenced via FK are global.

Cross-Module Links

• RCM — denial follow-up and appeal tasks
• eRx & EPCS — RxRenewal routing tasks
• Referrals — referral auth tasks
• Patient Portal — SLA breach escalation; patient task visibility
• Payer Optimization — coding suggestion review tasks