Task Lifecycle

Tasks (FHIR Task) are the primary work-tracking resource in CareLaunch. They represent patient care activities — case reviews, follow-ups, form completions, reminders, and integration handoffs — that need to be assigned, tracked, and completed.

This document describes every status a Task can hold, what triggers each transition, and what side effects occur.

Statuses

CareLaunch uses the standard FHIR R4 TaskStatus values:

Status	Display Name	Description
draft	Draft	Task has been created but is not yet actionable. Used for tasks that are being assembled or are pending additional information.
requested	Requested	Task has been requested and is awaiting acceptance. This is the default status when a task is created via the FHIR API or data import. Also used for scheduled reminder and check tasks.
received	Received	Task has been received by the intended performer but not yet started.
accepted	Accepted	Task has been accepted by the performer and is queued for work.
rejected	Rejected	Task has been declined by the intended performer.
ready	Ready	Task is ready to be performed. This is the default status when a task is created via the automation engine (e.g., "Create Task" action) or via AWS Connect integration.
in-progress	In Progress	Task is actively being worked on.
on-hold	On Hold	Task has been temporarily paused.
cancelled	Cancelled	Task has been cancelled before completion. Common when a linked appointment is cancelled.
completed	Completed	Task has been finished. This is typically the final active state.
failed	Failed	Task could not be completed due to an error (e.g., missing appointment reference, notification delivery failure).
entered-in-error	Entered in Error	Task was recorded by mistake.

Status Flow Diagram

stateDiagram-v2
    [*] --> requested : FHIR API / data import
    [*] --> ready : Automation engine / integration

    requested --> in_progress : User starts work (board/UI)
    requested --> completed : Callback completes task\nOR late-check/no-show resolves
    requested --> cancelled : Linked appointment cancelled\nOR appointment not found
    requested --> failed : Missing appointment reference\nOR notification delivery failure
    requested --> on_hold : User pauses task (UI)
    requested --> rejected : User rejects task (UI)

    ready --> in_progress : User starts work (board/UI)
    ready --> completed : User completes task (UI)
    ready --> cancelled : User cancels task (UI)
    ready --> on_hold : User pauses task (UI)

    in_progress --> completed : User/system completes task\nOR retry succeeds
    in_progress --> cancelled : Linked appointment cancelled
    in_progress --> failed : Notification retry exhausted
    in_progress --> on_hold : User pauses task (UI)

    on_hold --> in_progress : User resumes task (UI)
    on_hold --> cancelled : User cancels task (UI)

    completed --> in_progress : User reopens (subtask toggle)
    cancelled --> [*]
    failed --> [*]
    entered_in_error --> [*]

    state "draft" as draft
    state "requested" as requested
    state "received" as received
    state "accepted" as accepted
    state "rejected" as rejected
    state "ready" as ready
    state "in-progress" as in_progress
    state "on-hold" as on_hold
    state "cancelled" as cancelled
    state "completed" as completed
    state "failed" as failed
    state "entered-in-error" as entered_in_error

Transition Details

Creation → requested

Trigger: Task is created through the FHIR API (POST /Task) or via data import.

• FhirHelper.SetDefaults sets status to requested if no status is provided.
• intent defaults to order.
• code defaults to Case Review if not specified.
• The authoredOn timestamp is set at creation time.

Creation → ready

Trigger: Task is created by the automation engine via a "Create Task" action, or via the AWS Connect integration ("Create Task - Connect").

• AutomationProcessor.ProcessTask sets status to ready unless the automation template specifies a different status.
• The task is linked to the triggering resource via focus and to the patient via for.
• A restriction.period.start is set to the current UTC time.

Any status → any status (Board / UI)

Trigger: A user changes the task status via the admin UI — either through the task edit dialog, the task list, or by moving a card on a board.

• The board view (Board.vue) calls updateResourceStatus, which fetches the latest task, updates the status, records a status reason entry, and saves via PUT /Task/{id}.
• The task edit dialog (TaskEdit.vue) exposes all 11 statuses as selectable options.
• Task lists (CompactTaskList.vue, FullWidthTaskList.vue) allow direct status changes and form-based task completion.
• Every status change records a status reason audit entry (see Status Reason Tracking below).

requested → completed (Callback)

Trigger: A patient completes a task action via the patient portal callback endpoint (CallbackController).

• The callback validates the task matches the expected envelope and patient.
• Sets status to completed and saves via the FHIR repository.
• Redirects the patient back to the portal or registration flow.

requested → completed (Late Reminder Check)

Trigger: A scheduled late reminder check runs and determines the reminder was already handled.

• EventBridgeReminderService.ProcessLateReminderCheck checks if the patient already joined the appointment.
• If the patient joined, or if the notification type is disabled, the check task is set to completed with an appropriate statusReason.

requested → completed (No-Show Check)

Trigger: A scheduled no-show check runs and determines the appointment outcome.

• EventBridgeReminderService.ProcessNoShowCheck evaluates whether the patient attended.
• If the patient did not attend, the appointment is marked as no-show, and the check task is set to completed.
• If the appointment status was already updated, the task is completed with a note.

requested → cancelled (Appointment Cancelled)

Trigger: The linked appointment is cancelled or dismissed.

• EventBridgeReminderService.CancelReminders finds all active reminder and check tasks linked to the appointment.
• Sets each task to cancelled with statusReason: "Appointment cancelled".
• Also triggered when a ServiceRequest linked to the appointment is dismissed.

requested → cancelled (Appointment Not Found)

Trigger: A scheduled check runs but the linked appointment no longer exists or has been cancelled.

• The late reminder check or no-show check cannot find a valid appointment.
• Sets the task to cancelled with statusReason: "Appointment not found or cancelled".

requested → failed

Trigger: A scheduled check task cannot proceed due to a missing reference or a delivery error.

• If the task has no appointment reference, status is set to failed with statusReason: "No appointment reference".
• Concierge service actions that fail are mapped to failed status.

in-progress → completed (Notification Retry)

Trigger: A notification retry task successfully delivers the notification.

• EventBridgeReminderService.ProcessRetry sets the retry task to in-progress at the start of processing.
• On success, sets the task to completed with statusReason: "Retry {N} completed successfully".

in-progress → failed (Retry Exhausted)

Trigger: A notification retry task fails after all retry attempts.

• The retry task status is set to failed with the error message as statusReason.

in-progress → cancelled (Retry — Appointment Gone)

Trigger: During retry processing, the linked appointment is no longer valid.

• Sets the retry task to cancelled with statusReason: "Appointment not found or cancelled".

Subtask Toggle: completed ↔ in-progress

Trigger: A user clicks the subtask checkbox in the task list.

• Toggles the subtask between completed and in-progress.
• Updates via the task store API.

Business Status (Plan-Based Workflows)

In addition to the FHIR status, tasks associated with a Plan (FHIR PlanDefinition) use a businessStatus field to track workflow progression through plan-defined stages.

• Board columns can be configured to group by businessStatus instead of status.
• Business statuses are defined by the plan's action elements (e.g., "Registered", "Records Collection", "In Review", "Completed").
• When a task has a plan, the board's status dropdown shows plan-defined stages instead of FHIR statuses.
• Business status changes are recorded in the same status reason audit trail.

For more information on plans, see Plans.

Status Reason Tracking

Every task status change records an audit entry in the statusReason field:

{
  "statusReason": {
    "text": "2024-01-15T14:30:00.000Z",
    "coding": [
      {
        "code": "requested",
        "display": "2024-01-15T10:00:00.000Z"
      },
      {
        "code": "in-progress",
        "display": "2024-01-15T14:30:00.000Z"
      }
    ]
  }
}

Each entry in the coding array represents a status the task has passed through, with the display field recording the ISO 8601 timestamp of the transition. This provides a full audit trail of the task's lifecycle. The text field is updated to the timestamp of the most recent change.

Automations

Tasks participate in the CareLaunch automation engine in two ways:

Tasks Created by Automations

The "Create Task" automation action creates tasks when a trigger condition is met:

• Triggers: Patient registration, resource creation, resource update, scheduled events.
• Default status: ready (unless the automation template specifies otherwise).
• Configuration: The automation template can pre-populate task fields including status, code, description, owner, due date, and linked questionnaires.
• Subtasks: Automations can create subtasks as part of a plan-based workflow.

Automations Triggered by Task Changes

Task creation and updates can themselves trigger automations:

• Resource Creation trigger: Fires when a new Task is created.
• Resource Update trigger: Fires when a Task is updated (including status changes).
• Resource Delete trigger: Fires when a Task is deleted.

Automations can filter on task fields (code, status, owner) to scope which task events trigger downstream actions.

Concierge Service Integration

The Concierge service maps task statuses to internal action states:

Task Status	Action Status
requested	pending
completed	executed
cancelled	cancelled
failed	failed
All others	in-progress

Reminder and Check Task Automations

The platform automatically creates and manages tasks for appointment-related workflows:

1. Reminder tasks — Created with status: requested for upcoming appointments. Cancelled automatically if the appointment is cancelled.
2. Late reminder check tasks — Created to verify whether a patient joined before the appointment. Auto-resolve to completed, cancelled, or failed based on appointment state.
3. No-show check tasks — Created to evaluate post-appointment attendance. Auto-resolve based on whether the patient attended.
4. Notification retry tasks — Created when initial notification delivery fails. Progress through requested → in-progress → completed/failed/cancelled.

Access Control

Action	Who Can Perform
Create	Admin users, automation engine, patient portal (via callback)
Read	Platform Admin, Organization Admin, Instance Admin, assigned practitioner
Update status	Admin users (via UI), automation engine, system processes
Complete (portal)	Patient (via callback endpoint with valid envelope)
Delete	Platform Admin, Organization Admin, Instance Admin

Related Documentation

• Tasks — task creation, types, and management overview
• Boards — visual kanban-style task management
• Plans — configure task workflow stages and business statuses
• Automations — create and manage tasks automatically
• Service Request Lifecycle — related resource lifecycle documentation