Patient Worklist & Scheduling

Relevant source files

The following files were used as context for generating this wiki page:

• src/js/apps/patients/worklist/worklist_app.js
• src/js/apps/patients/schedule/schedule_app.js
• src/js/views/patients/worklist/worklist_views.js
• src/js/views/patients/schedule/schedule_views.js
• test/integration/patients/worklist/worklist.js
• test/integration/patients/worklist/schedule.js
• test/integration/patients/worklist/bulk-edit.js
• test/integration/patients/worklist/reduced-schedule.js
• src/js/i18n/en-US.yml

The Patient Worklist & Scheduling module is a central component of the application designed to help clinicians manage patient care tasks, track progress across workflows, and organize daily activities. It provides two primary paradigms for task management: a worklist-oriented view (focusing on entity ownership and recency) and a schedule-oriented view (focusing on specific due dates and times).

The system manages two core operational entities: Actions (individual tasks, often associated with forms or outreach) and Flows (logical groupings of Actions representing a high-level care process). Clinicians can filter these lists by ownership, team affiliation, and status to focus on high-priority patient needs.

Architecture and Components

The module is built using a Backbone/Marionette-based architecture, utilizing Marionette.Toolkit.App for lifecycle management and state persistence.

Core Applications

• WorklistApp: Manages the retrieval and display of Actions and Flows based on ownership and activity. It supports various list types such as "Owned By", "Shared By", and time-based views (e.g., "New < 1 Day").
• ScheduleApp: Specifically focuses on Actions that have assigned due_date attributes. It organizes tasks chronologically and allows clinicians to view their daily or monthly agenda.

Sources: test/integration/patients/worklist/worklist.js:46-70, test/integration/patients/worklist/schedule.js:80-100

View Hierarchy

The UI is organized into several specific view components:

1. Layout Views: Provide the structural frame, including headers, count regions, and filter regions.
2. Table Views: Handle the rendering of collections, supporting sorting and multi-select capabilities.
3. Filter/Sidebar Views: Allow users to narrow down data by clinician, team, state, or date range.
4. Bulk Edit Sidebar: A specialized interface for updating multiple Actions or Flows simultaneously.

Sources: src/js/i18n/en-US.yml:195-250, test/integration/patients/worklist/bulk-edit.js:100-150

Data Flow and API Interaction

The Worklist and Schedule apps interact with the backend via JSON:API endpoints, primarily /api/actions and /api/flows.

Data Fetching Flow

When a clinician navigates to a worklist or changes a filter, the application constructs a request with complex filter and inclusion parameters.

The application includes related resources such as patient, flow, and owner to provide context in the list views without requiring additional requests per item.
Sources: test/integration/patients/worklist/worklist.js:1440-1460, test/integration/patients/worklist/schedule.js:250-280

Filtering Capabilities

The system supports several filter categories:

• Clinician/Owner: Filters by a specific clinician ID or NIL_UUID for unassigned items.
• Team: Filters items owned by any member of a specific care team.
• State: Filters by status (e.g., To Do, In Progress, Done).
• Date: Filters by created_at, updated_at, or due_date using relative (e.g., "Today", "This Week") or absolute ranges.

Sources: src/js/i18n/en-US.yml:251-300, test/integration/patients/worklist/schedule.js:315-350

Worklist Functional Areas

Actions vs. Flows

Users can toggle between viewing individual Actions and high-level Flows.

Entity	Description	Key Attributes
Action	A discrete task for a patient.	name, due_date, state, form, outreach
Flow	A collection of related actions.	name, progress (complete/total), state, owner

Sources: test/integration/patients/worklist/worklist.js:100-140, src/js/i18n/en-US.yml:343-355

Sorting Logic

Sorting is performed on the client-side or requested via the API depending on the view. Supported sort options include:

• Added/Updated: Oldest to Newest or Newest to Oldest.
• Due Date: Sooner to Later or Later to Sooner (Schedule only).
• Patient Name: Alphabetical by Last Name.
• Custom Fields: Sorting by specific patient-level metadata (e.g., risk scores).

Sources: test/integration/patients/worklist/worklist.js:1750-1850, src/js/i18n/en-US.yml:450-480

Bulk Operations

The system provides a robust bulk editing mechanism. Clinicians can select multiple items using checkboxes or shift-clicking and open the Bulk Edit Sidebar.

Bulk updates are processed as individual PATCH requests to ensure transactional integrity per record.
Sources: test/integration/patients/worklist/bulk-edit.js:200-300, test/integration/patients/worklist/schedule.js:650-700

Real-time Updates (WebSockets)

The application subscribes to real-time updates via WebSockets to ensure worklists remain accurate without manual refreshes. It handles several category-specific messages:

• NameChanged/DetailsChanged: Updates individual item text.
• StateChanged: Transitions items between sections or removes them if they no longer match filters (e.g., moving from "In Progress" to "Done").
• OwnerChanged: Updates the owner badge or removes the item if the user is filtering by "Owned By Me".
• FlowProgressChanged: Updates the progress bar on Flow list items.
• ResourceCreated: Adds new items to the top of the list if they match current filters.

Sources: test/integration/patients/worklist/worklist.js:180-280, test/integration/patients/worklist/worklist.js:1000-1100

Schedule Worklist Specifics

The Schedule view is distinct from the general worklist as it groups Actions by their due_date. It displays a chronological list where:

• Overdue items are flagged with a specific "is-overdue" class and red styling.
• Today's items are highlighted with an "is-today" indicator.
• Time-specific items are sorted within the day group by their due_time.

Sources: test/integration/patients/worklist/schedule.js:140-160, src/js/i18n/en-US.yml:405-415

Reduced Schedule View

For certain clinician roles (e.g., roleReducedEmployee), a simplified version of the schedule is rendered. This view removes advanced filtering, multi-select, and complex navigation to provide a focused, read-only list of essential tasks.

Sources: test/integration/patients/worklist/reduced-schedule.js:10-50