The Workflow domain manages the lifecycle of work items (tasks), their routing to queues, SLA tracking against regulatory deadlines, and operational metrics. It is a behavior-shaped domain — the task lifecycle is governed by a state machine with guards, effects, and routing rules rather than ad-hoc CRUD logic.
See Domain Design Overview for context and Contract-Driven Architecture for the contract approach.
A task is the atomic unit of caseworker activity — reviewing an application, verifying a document, completing a redetermination. It represents a single, ownable piece of work with a clear beginning and end. Tasks are assigned to a single owner (caseworker, supervisor, or automated process) at a time and have an explicit lifecycle governed by the state machine. They carry slaInfo entries that track deadline status against regulatory requirements, and link to a Queue that controls routing and visibility. Spec: workflow-openapi.yaml
Tasks associate with a subject entity via a polymorphic subjectType / subjectId pair. subjectType identifies the kind of record the task is about (e.g., application, case, document); subjectId holds the UUID of that record. This replaces a fixed caseId FK and allows tasks to be linked to any entity type without schema changes. States extend the subjectType enum via overlay to add program-specific entity types. Resolution of subjectId is always conditional on subjectType — no automatic expansion is performed (consistent with how Salesforce WhatId, ServiceNow parent, and GitHub subject_id handle polymorphic references).
Queues are the organizing structure for caseworker workloads. A queue represents a logical grouping of tasks — typically by program (SNAP, Medicaid), team, or skill — and determines which workers can see and claim which tasks. Tasks enter a queue automatically when created or released, based on assignment rules. Supervisors manage queues to balance workload across their teams. Spec: workflow-openapi.yaml
Every state machine transition and lifecycle hook emits an immutable domain event. Events serve two purposes: they are the audit trail (a complete history of what happened to every task and when) and the integration surface for cross-domain communication (other domains subscribe to workflow events rather than polling task state). All domains share the same events collection; domain, resource, and action identify the event type. Read-only API. Spec: workflow-openapi.yaml
The task lifecycle is governed by a declarative state machine rather than ad-hoc endpoint logic. Tasks move through states like pending → in_progress → awaiting_client → in_progress → completed, with each transition triggered by an explicit named action. Transitions declare guards (preconditions) and effects (side effects such as updating fields or emitting events). The state machine also supports multiple lifecycles within the same domain — task-type-specific states and transitions are scoped via taskType guards, keeping fair hearing tasks, recertification tasks, and standard casework tasks within a single contract. Spec: workflow-state-machine.yaml
See State machine in the design reference for the full transition table, guard definitions, and design decisions.
Assignment and priority rules express routing logic that doesn't belong in the state machine. When a task is created or returns to pending, rules determine which queue it should go to and what priority it should have. Keeping this logic in a separate rules file means states can replace their routing and priority logic entirely without touching the state machine.
| Rule Set | Purpose |
|---|---|
assignment |
Route tasks to the correct queue based on program type and other criteria |
priority |
Set task priority based on expedited status, program type, or other criteria |
Rules use a first-match-wins evaluation model. The baseline rules are illustrative — states replace them with their own program-specific routing logic. See Rules engine in the design reference.
Federal regulations impose strict processing deadlines on benefits applications. SLA types define these deadlines and the conditions under which the clock pauses (e.g., while waiting on the client) and resumes. Each task carries a slaInfo array with one entry per applicable SLA type, tracking deadline status in real time. SLA types are auto-assigned at task creation based on task attributes and updated on every state transition. Spec: workflow-sla-types.yaml
See SLA and deadline management in the design reference for baseline types, clock behavior, and design decisions.
Operational metrics give supervisors visibility into queue health, team performance, and compliance risk. Each metric is defined declaratively in a contract artifact — specifying what data to query, how to aggregate it, and optionally what performance target to evaluate against. Spec: workflow-metrics.yaml
See Metrics in the design reference for baseline metrics and design decisions.
The baseline contracts are a starting point. States customize via overlays:
- State machine: add transitions, extend guards, add effects to existing transitions
- Multiple lifecycles: add task-type-specific states and transitions scoped via
taskTypeguards to support multiple lifecycles within the same domain (e.g., fair hearing tasks alongside standard casework tasks) - Subject types: extend the
subjectTypeenum on Task to add program-specific entity types beyond the baseline (application,case,document,appointment) - Rules: replace
workflow-rules.yamlentirely with state-specific assignment and priority logic - SLA types: replace or extend
workflow-sla-types.yamlwith state-specific deadlines and pause conditions - Metrics: replace or extend
workflow-metrics.yamlwith state-specific metrics and targets
See the State Overlays Guide for overlay mechanics.
| Artifact | File |
|---|---|
| OpenAPI spec | workflow-openapi.yaml — Tasks, Queues, Events, Metrics |
| State machine | workflow-state-machine.yaml — States, transitions, guards, effects |
| Rules | workflow-rules.yaml — Assignment and priority rule sets |
| SLA types | workflow-sla-types.yaml — Baseline SLA types for SNAP and Medicaid |
| Metrics | workflow-metrics.yaml — Baseline operational metrics |
| Document | Description |
|---|---|
| Workflow Design Reference | Vendor comparisons, design decisions, customization points, and comprehensive gap assessment |
| Workflow Prototype | Full design spec — states, transitions, rules, metrics |
| Domain Design | Workflow section in the domain overview |
| Case Management | Staff, teams, offices — closely related domain |
| Scheduling | Appointments may trigger workflow tasks |
| Contract-Driven Architecture | Contract artifacts and the adapter pattern |