Chapter 23: Schedule Center & Calendar Management

Overview

The Schedule Center is the central hub for managing all clinical visits, staff assignments, and time scheduling across your agency. This powerful drag-and-drop calendar interface combines traditional scheduling with intelligent compliance task management, ensuring that both routine visits and regulatory requirements are properly scheduled and completed.

Understanding the Interface

Main Screen Layout

Schedule Center Main View

The Schedule Center consists of four main areas:

1. Left Sidebar: Needs Scheduling

This panel displays patients who have unscheduled visits or compliance tasks that need to be assigned to clinicians. It shows:

Patient search bar - Filter patients by name or MRN
Patient cards - Each card shows:
- Patient name
- Number badge indicating total unscheduled items
- Red "compliance" chip - Appears when the patient has pending compliance tasks (e.g., "2 compliance" means 2 compliance tasks need scheduling)
- MRN (Medical Record Number)
- Earliest visit date
- Branch name (if multi-branch feature is enabled)

When you click a patient card, it expands to show all unscheduled visits and compliance tasks for that patient.

2. Top Header Bar

Branch Selector (for users with "branch:manage" permission) - Switch between Head Quarter and specific branches to view different scheduling contexts
Date Navigator - Left/right arrows to move between days
Date Display - Shows the currently selected date (e.g., "Fri, Apr 10 (Today)")
Calendar Icon - Opens a date picker modal to jump to any specific date
Active Visits Button - Opens a drawer showing all visits currently "In Progress" or ready to check in
Cancelled Visits Button - Opens a drawer showing recently cancelled visits that can be rescheduled

3. Center: Calendar Grid

The main calendar displays time slots from 6:00 AM to 10:00 PM in one-hour increments. Each column represents a clinician (staff member) showing:

Clinician name and role/discipline (e.g., "Michael Rodriguez - Skilled Nursing")
Visit cards on the timeline - Each card shows:
- Patient name
- Visit type (e.g., "HHA Visit", "OASIS SOC", "PT Evaluation")
- Time slot placement on the timeline

4. Right Panel: Clinician Details (appears when you click a clinician column)

Shows detailed information about the selected clinician including their scheduled visits for the day.

Understanding Visit Types vs. Compliance Tasks

The Schedule Center handles two distinct types of scheduling items, each with different behaviors:

Regular Visits

Created through Care Orders, Plan of Care, or manually via "Create Manual Visit"
May or may not have a pre-assigned clinician
If unassigned, they appear in the left sidebar as draggable items that can be assigned to any qualified clinician
Once assigned, they appear on the calendar

Compliance Tasks

Compliance tasks are automatically generated by the system when specific conditions occur. They ensure regulatory requirements are met. They appear in the left sidebar with special visual indicators.

Types of Compliance Tasks

Task Type	When Created	Due Date	Description
OASIS_ASSESSMENT	New patient admission (SOC) created	5 days after SOC date	Complete Start of Care OASIS assessment
OASIS_RECERTIFICATION	Recertification episode is initiated	Episode end date	Complete Recertification OASIS before episode expires
OASIS_DISCHARGE	Discharge process is initiated	As specified	Complete Discharge OASIS assessment
OASIS_DEATH	Death at Home process is initiated	As specified	Complete Death at Home OASIS assessment
HHA_SUPERVISORY_VISIT	First HHA visit is completed OR a supervisory visit is completed	14 days after triggering visit	Conduct HHA supervisory visit (every 14 days)
LPN_SUPERVISORY_VISIT	First LPN/LVN visit is completed	30 days after triggering visit	Conduct LPN supervisory visit by RN case manager
PHYSICIAN_SIGNATURE	Document requires physician approval	As specified	Obtain physician signature on clinical document
RENEW_AUTHORIZATION	Authorization is expiring	Before expiration	Renew prior authorization with payer
UNSIGNED_DOCUMENT	Document pending signature	As specified	Complete document signature requirement

How Compliance Tasks Work in Schedule Center

Automatic Creation: Compliance tasks are created automatically by backend logic when trigger conditions are met (e.g., first HHA visit completed → creates HHA_SUPERVISORY_VISIT task due in 14 days)
Assignment: Most compliance tasks are automatically assigned to the Case Manager of the care order. Some tasks (like HHA/LPN supervisory visits) must be performed by clinicians with specific disciplines (e.g., RN for LPN supervisory).
Visibility: Compliance tasks appear in the left sidebar with:
- Red "compliance" chip on the patient card
- Special visual styling when the patient is expanded
- Due date display ("Today", "Tomorrow", or specific date)
- Task description from the system
Scheduling Process: When you drag a compliance task to the calendar:
- The system creates a new visit linked to the compliance task
- The visit type is automatically determined based on the task type (e.g., HHA_SUPERVISORY_VISIT → creates an HHA Supervisory Visit)
- The system validates that the selected clinician has the correct discipline to perform this task
- Once scheduled, the compliance task status changes from PENDING to SCHEDULED
- The task remains linked to the visit throughout its lifecycle
Completion: When the visit is checked in, completed, and the visit note is approved:
- The compliance task status changes to COMPLETE
- If it's a recurring task type (like HHA supervisory visits), a new compliance task is automatically created with the next due date
Discipline Restrictions: Some compliance tasks can only be performed by clinicians with specific disciplines:
- OASIS Assessments → RN or PT (depending on agency configuration)
- HHA Supervisory Visit → RN case manager or qualified RN
- LPN Supervisory Visit → RN only (cannot be assigned to the LPN being supervised)

Creating Visits Manually

Create Manual Visit Modal

When to Create Manual Visits

You should create manual visits when:

A patient needs an ad-hoc visit outside the Plan of Care
A clinician reports the need for an additional assessment
You need to schedule a communication note or coordination visit

How to Create a Manual Visit

Step 1: Open the Modal

Click the blue "+" button in the top-right corner of any clinician column in the calendar
Or click an empty time slot on the calendar

Step 2: Fill in Visit Details

The modal shows the following fields:

Field	Description	Required?
Patient	Select the patient for this visit. The dropdown shows all active patients with their current care order dates displayed in parentheses (e.g., "Abe bela (MRN: 43829 • 2025-11-01 → 2026-01-30)").	Yes
Visit Type	Select the type of visit. Only visit types appropriate for the selected patient's care order are shown. Note: OASIS visit types (SOC, Recert, Discharge, Transfer, Death) are NOT available here because they must be created through proper care order workflows to ensure regulatory compliance.	Yes
Date	The date for the visit. Must be within the patient's current care order period. Cannot be in the past.	Yes
Time	Select a time slot from 6:00 AM to 10:00 PM in one-hour increments.	Yes
Clinician	Select the clinician to assign this visit to. Only clinicians whose discipline matches the selected visit type are shown (e.g., if you select "PT Evaluation", only Physical Therapists appear in the list).	Yes
Notes	Optional internal notes about this visit (not shown to the patient).	No

Step 3: Validate and Create

The modal validates that the selected date falls within the care order's certification period
If the selected time slot is already occupied by another visit for that clinician, you'll see an error
Click "Create Visit" to schedule the visit

What Happens After Creation:

The visit is created with status Scheduled
It immediately appears on the calendar at the specified time and clinician column
The clinician is notified (if notifications are enabled)
The visit appears in the clinician's mobile app schedule
The patient list in the left sidebar updates to reflect the new visit count

Scheduling Compliance Tasks

Schedule Visit Modal

Compliance tasks have a special scheduling flow that differs from regular visits.

How to Schedule a Compliance Task

Step 1: Find the Task

Click on a patient card in the left sidebar to expand their unscheduled items
Compliance tasks are visually distinct and show the task description (e.g., "HHA Supervisory Visit required for patient. First HHA visit completed.")

Step 2: Choose How to Schedule

You have two options to schedule a compliance task:

Option A: Drag and Drop

Click and drag the compliance task card from the sidebar
Drop it onto a time slot in a clinician's column on the calendar
The system validates discipline restrictions and shows an error if the clinician is not qualified

Option B: Click to Schedule

Click the "Schedule" button on the compliance task card
A modal opens showing:

Schedule Visit Modal Fields

Field	Description	Restrictions
Patient & task	Read-only display showing patient name and task description	Cannot be changed
Date	Date picker for the visit. Defaults to the current selected date on the calendar.	Cannot be in the past
Time	Dropdown with time slots from 6:00 AM to 10:00 PM	-
Clinician	Dropdown showing only clinicians who are qualified to perform this task type. The system automatically filters based on discipline requirements.	Critical: If a compliance task requires a specific clinician (e.g., assigned case manager), only that clinician appears in the list. For discipline-specific tasks (e.g., LPN Supervisory Visit), only RNs are shown.

Step 3: Validation

The system performs several validations when you schedule a compliance task:

Discipline Check: Ensures the selected clinician has the correct discipline
- Example: HHA Supervisory Visit can only be assigned to RNs
- Example: OASIS assessments can only be assigned to RNs or PTs (depending on settings)
Visit Type Mapping Check: The system automatically determines which visit form template to use based on the compliance task type:
- OASIS_ASSESSMENT → oasis-soc form
- OASIS_RECERTIFICATION → oasis-recert form
- HHA_SUPERVISORY_VISIT → hha-supervisory-visit form
- etc.
Slot Availability: Confirms the time slot is not already occupied
Care Order Status: Verifies the patient's care order is in the correct status for this task

Step 4: System Actions

When you click "Schedule", the following happens:

Visit Creation: A new visit record is created with:
- status: "Scheduled"
- scheduledAt: The date and time you specified
- clinicianId: The selected clinician
- complianceTaskId: Linked to the compliance task
- visitTypeMappingId: Automatically determined based on task type and clinician discipline
Compliance Task Update: The compliance task record is updated:
- status: Changes from PENDING to SCHEDULED
- visitId: Set to the newly created visit ID
- This linkage ensures the task and visit stay connected throughout the workflow
Calendar Update: The visit immediately appears on the calendar at the scheduled time
Sidebar Update: The compliance task is removed from the "Needs Scheduling" sidebar since it's now scheduled

Understanding the Patient List in Detail

Patient List Expanded

Patient Card Information

When you expand a patient card in the left sidebar, you see:

Visit Cards (Regular Unassigned Visits)

Visit type as the header (e.g., "HHA Visit", "RN Evaluation")
Due date - Shows "Today", "Tomorrow", or the specific date
Status indicator - Color-coded:
- Red border = Urgent (due today or tomorrow)
- Normal = Due in the future
Draggable - Can be dragged to any clinician column (system validates discipline match)

Compliance Task Cards

Special visual styling - Distinct from regular visits
Task description - Auto-generated by the system (e.g., "Complete New Admission OASIS for patient")
Due date with urgency indicator
Schedule button - Opens the schedule modal
Cancel button (X icon) - Allows cancelling the task if it's no longer needed
Cannot be manually edited - Description and due date are system-controlled

Grouping by Visit Type

When a patient has multiple visits of the same type, they're grouped together:

Click the expand/collapse arrow to show/hide visits of that type
The count badge shows how many visits of that type exist
Helpful for patients with recurring visits (e.g., 5 HHA Visits scheduled over the next two weeks)

Patient Card Badges

Badge	Color	Meaning
Number badge (e.g., "5")	Blue	Total count of unscheduled visits + compliance tasks
"X compliance" (e.g., "2 compliance")	Red	Number of compliance tasks needing scheduling

Search Functionality

Type in the search bar at the top of the patient list
Searches by patient name and MRN
Results update in real-time as you type
Matching patients remain visible, others are filtered out

Drag-and-Drop Scheduling

How Drag-and-Drop Works

Step 1: Select an Item

Click and hold on a visit card or compliance task card in the left sidebar
The item becomes highlighted and follows your cursor
A semi-transparent preview appears

Step 2: Drag to Calendar

Move your cursor over the calendar grid
The calendar shows valid drop zones (time slots for each clinician)
Time slots that are already occupied are visually indicated (you cannot drop on them)

Step 3: Drop on a Time Slot

Release the mouse button to drop the item
The system immediately performs validation:
- Slot Availability Check: Is this time slot already taken?
- Discipline Check: Does this clinician have the right qualification for this visit type?
- Compliance Check: If it's a compliance task with a required assignee, does the drop target match?
- Date Check: Is the drop date within the patient's care order period?

Step 4: Validation Results

If validation passes:

The visit card appears on the calendar at the dropped location with a loading spinner
An API call is made to assign/create the visit
The loading spinner disappears once confirmed
The item is removed from the "Needs Scheduling" sidebar

If validation fails:

An error modal appears explaining why (e.g., "This time slot is already occupied")
The item returns to the sidebar
No changes are made

Rescheduling Existing Visits

You can also drag already-scheduled visits on the calendar to reschedule them:

When You Can Reschedule:

The visit status is Scheduled (not In Progress, Completed, Missed, or Cancelled)
The visit is not starting within the next 2 hours (to prevent late cancellations)
You have the EDIT_VISIT permission

How to Reschedule:

Click and drag the visit card on the calendar
Drop it on a new time slot (can be a different clinician or different time)
The system validates:
- 2-Hour Rule: Cannot reschedule a visit starting in less than 2 hours (shows "Late Cancellation" error)
- Slot availability: Destination time slot must be empty
- Discipline match: If moving to a different clinician, they must be qualified for this visit type
If valid, the visit immediately moves to the new location and the backend is updated

Using the Date Picker

Date Picker Modal

Opening the Date Picker

Click the calendar icon in the top header bar.

Date Picker Features

The modal displays a standard calendar view with:

Element	Description
Month/Year Selector	Dropdown to quickly jump to a different month
Previous/Next Arrows	Navigate month by month
Today Highlight	Current date is highlighted in blue
Selected Date	The currently viewed date on the schedule is shown with a filled blue circle
"Today" Button	Quickly jump back to today's date

Selecting a Date

Click any date on the calendar
The Schedule Center immediately loads that day's schedule
The date picker closes automatically
The "Needs Scheduling" sidebar stays the same (it shows all unscheduled items, not date-specific)

Past Dates

You can view past dates to see historical schedules, but:

You cannot create new visits on past dates
You cannot drag and drop to past dates
Scheduled visits on past dates are read-only

Active Visits Drawer

What Are Active Visits?

Active visits are visits that are:

Status: In Progress - The clinician has checked in and is currently with the patient
Ready to check in - The visit is scheduled for today or earlier and the clinician hasn't checked in yet

Opening the Drawer

Click the "Active Visits" button (with play icon) in the top header bar.

Drawer Contents

The drawer opens from the right side and displays:

Visit Cards

Each card shows:

Patient Name in bold
Visit Type (e.g., "HHA Visit", "MSW Initial Assessment / Evaluation")
Status Badge - Color-coded:
- Green "In Progress" - Clinician is currently with the patient
Scheduled Time - When the visit was scheduled to start (e.g., "Scheduled: Dec 21 at 9:00 AM")
Checked In Time - When the clinician actually checked in (e.g., "Checked in: Mor started")
Clinician Name - Who is performing the visit (e.g., "Clinician: MSW Test Clinician")
Patient Address - Full address where the visit is taking place
"View Clinician Location" Button - Opens a map showing the clinician's real-time GPS location (if they've shared location in the mobile app)

Sorting

Active visits are sorted by:

Status (In Progress visits appear first)
Scheduled time (earliest first)

Use Cases for Active Visits Drawer

Scenario	Action
Track field staff	See which clinicians are currently with patients
Monitor late check-ins	Identify visits that should have started but haven't
Coordinate emergency coverage	Quickly see who is in the field and where
Verify location	Use "View Clinician Location" to ensure clinician is at the correct address
Respond to patient calls	Check if the clinician has arrived or is running late

Cancelled Visits Drawer

What Are Cancelled Visits?

Cancelled visits are visits with status: "Cancelled" that were cancelled within the past 15 days. The system keeps these visible for a short period to allow easy rescheduling if the cancellation was temporary.

Opening the Drawer

Click the "Cancelled Visits" button (with cancel icon) in the top header bar.

Drawer Contents

Each cancelled visit card shows:

Field	Description
Status Badge	Red "Cancelled" badge
Patient Name	Patient for whom the visit was scheduled
Visit Type	Type of visit that was cancelled
Original Scheduled Time	When the visit was originally scheduled (e.g., "Scheduled: Jan 13, 2026 at 3:00 AM")
Cancellation Time	How long ago it was cancelled (e.g., "Cancelled: 3 days ago")
Clinician (if assigned)	Who was assigned to perform the visit
Reschedule Button	Blue button to quickly reschedule this visit

Rescheduling a Cancelled Visit

Step 1: Click "Reschedule" The schedule modal opens with:

Patient pre-selected
Visit type pre-selected
Date/time fields empty (you choose the new date/time)
Clinician pre-selected if the original clinician is still available

Step 2: Select New Date/Time

Choose a new date (must be within the patient's care order period)
Choose a new time slot
Optionally change the assigned clinician

Step 3: Confirm

Click "Schedule"
The system creates a new visit with status: "Scheduled"
The old cancelled visit remains in the history (it is not modified)
The new visit appears on the calendar at the specified time

Why Cancelled Visits Are Useful

Reason	Benefit
Patient called in sick	Easily reschedule for later in the week
Clinician had emergency	Reassign to another qualified clinician
Wrong time entered	Cancel and reschedule with correct time
Patient wasn't home	Reschedule for next day
Accidental cancellation	Quickly restore the visit

Automatic Cleanup

Cancelled visits automatically disappear from this drawer after 15 days. They remain in the system's permanent records but are no longer shown in the "Cancelled Visits" list.

Branch-Specific Scheduling (Multi-Branch Feature)

If your agency has the Multi-Branch feature enabled:

Branch Selector

Located in the top header bar
Dropdown showing all branches plus "Head Quarter"
Selecting a branch changes the entire schedule view to show:
- Only clinicians assigned to that branch
- Only patients assigned to that branch
- Only visits for that branch context

Branch Permissions

Permission Level	What You See
User assigned to a specific branch	Can only view and schedule for your own branch. The branch selector is hidden or locked to your branch.
User with `branch:manage` permission	Can switch between all branches and Head Quarter. Full scheduling access across the entire agency.

Branch Indicators

Patient cards in the sidebar show "Branch: [Branch Name]" if multi-branch is enabled
Helps you identify which patients belong to which branch when viewing Head Quarter

Compliance Task Lifecycle: Deep Dive

Understanding how compliance tasks flow through the system helps you manage them effectively.

Phase 1: Automatic Creation

Compliance tasks are created by backend triggers when specific events occur:

Example 1: HHA Supervisory Visit Task

Trigger Event: A Home Health Aide (HHA) completes their first visit for a patient.

What Happens:

Clinician completes the HHA Visit Note in their mobile app
The visit status changes to Completed
Backend service (complianceTask.service.ts) detects this is the first completed HHA visit for this care order
A new compliance task is automatically created:
- type: "HHA_SUPERVISORY_VISIT"
- status: "PENDING"
- dueDate: 14 days from the completion date
- description: "HHA Supervisory Visit required for patient. First HHA visit completed."
- patientId: The patient's ID
- careOrderId: The care order's ID
- assignedToId: The case manager's user ID (automatically assigned)

Why 14 Days? CMS regulations require RN supervisory visits for HHAs every 14 days to ensure quality of care and compliance with the Plan of Care.

Example 2: OASIS Recertification Task

Trigger Event: Agency admin clicks "Initiate Recertification" on a care order approaching its end date.

What Happens:

Admin clicks the "Initiate Recertification" button (see Care Orders chapter)
Backend validates:
- The current episode has been active for at least 14 days
- The initial OASIS for this episode is completed
- No other recertification is already in progress
A new compliance task is automatically created:
- type: "OASIS_RECERTIFICATION"
- status: "PENDING"
- dueDate: The care order's certification end date (must be done before episode expires)
- description: "Complete OASIS Recertification for patient. Episode ends on [date]."
- assignedToId: The case manager or the selected RN clinician

Why This Matters: The recertification OASIS must be completed and approved before the episode end date, or the care order will close and billing will stop. The compliance task ensures this critical deadline doesn't get missed.

Phase 2: PENDING Status

When a compliance task is in PENDING status:

Visibility: Appears in the Schedule Center left sidebar under the patient's card
Visual Indicator: Patient card shows a red "X compliance" badge
Due Date Urgency: Changes color/style as it approaches:
- Normal (more than 1 day out) - Standard styling
- Urgent (today or tomorrow) - Red highlighting
- Overdue (past due date) - May show additional warning indicators
Assignment: Most tasks are assigned to the case manager, but some (like LPN Supervisory Visit) require specific disciplines
Actions Available:
- Schedule - Opens the schedule modal to assign the task to a clinician and time slot
- Cancel - If the task is no longer needed (e.g., patient was discharged), you can cancel it

Phase 3: Scheduling (Creating the Visit)

When you schedule a compliance task:

Backend Actions:

Visit Creation: A new visit record is created with:
- The appropriate visitTypeMappingId based on the task type and clinician's discipline
- scheduledAt set to the date/time you selected
- clinicianId set to the assigned clinician
- complianceTaskId linking it to the compliance task
- status: "Scheduled"
Compliance Task Update:
- status changes from PENDING to SCHEDULED
- visitId is set to the newly created visit ID
- This bidirectional link ensures the task and visit stay connected

What You See:

The visit appears on the calendar
The compliance task disappears from the "Needs Scheduling" sidebar
The patient's badge count decreases

Phase 4: SCHEDULED Status

When a compliance task is in SCHEDULED status:

Visibility: It's no longer in the "Needs Scheduling" sidebar (because it has a scheduled visit)
Linked Visit: The visit appears on the calendar at the scheduled time
Mobile App: The clinician sees this visit in their schedule in the mobile app
Rescheduling: If you need to change the date/time:
- Drag the visit card on the calendar to a new slot, OR
- Click the visit card and edit the scheduled time
- The compliance task remains in SCHEDULED status, and its visitId link is maintained
Cancellation: If you cancel the scheduled visit:
- The visit status becomes Cancelled
- The compliance task status reverts to PENDING
- The task reappears in the "Needs Scheduling" sidebar
- You must reschedule it

Phase 5: IN_PROGRESS Status

When the clinician checks in to the visit using the mobile app:

Visit Status: Changes from Scheduled to In Progress
Compliance Task Status: Automatically changes from SCHEDULED to IN_PROGRESS
Active Visits Drawer: The visit appears in the Active Visits drawer
Real-time Tracking: If the clinician shares their location, administrators can see their GPS position

Phase 6: COMPLETE Status

When the clinician completes the visit and the visit note is approved:

Trigger: The clinical document (visit note) for this visit is approved in the QA Center.

Backend Actions:

Visit Status: Changes to Completed
Compliance Task Status: Changes from IN_PROGRESS to COMPLETE
Recurring Task Creation (if applicable):
- For HHA Supervisory Visits: A new HHA_SUPERVISORY_VISIT task is automatically created with dueDate = 14 days from completion
- This creates a continuous cycle ensuring supervisory visits happen every 14 days as long as the patient receives HHA care

What You See:

The visit shows as completed on the calendar
The compliance task no longer appears in the Schedule Center (it's complete)
If it's a recurring type, a new task appears in the sidebar for the next cycle

Phase 7: CANCELLED or OVERDUE Status

CANCELLED Status

If a compliance task is manually cancelled:

How: Click the "X" button on the task card in the sidebar
Confirmation: A modal asks for confirmation
Effect:
- Task status becomes CANCELLED
- If a visit was scheduled, it's unlinked (visitId set to null)
- The visit itself is NOT automatically cancelled (you must cancel it separately if needed)
- The task disappears from the sidebar

When to Cancel:

Patient was discharged and the task is no longer relevant
The task was created in error
The requirement changed (e.g., patient no longer receives HHA services)

OVERDUE Status

Compliance tasks automatically become OVERDUE if the due date passes and they're still in PENDING or SCHEDULED status
Overdue tasks may trigger alerts or notifications (depending on agency settings)
They remain in the sidebar and can still be scheduled

Discipline-Based Filtering for Compliance Tasks

When you schedule a compliance task, the system automatically restricts which clinicians can be assigned based on discipline requirements. This ensures regulatory compliance and proper skill matching.

How Discipline Filtering Works

Step 1: Task Type Determines Required Form The compliance task's type field maps to a specific visit form template:

Task Type	Form Template Key	Discipline Requirement
`HHA_SUPERVISORY_VISIT`	`hha-supervisory-visit`	RN only
`LPN_SUPERVISORY_VISIT`	`lpn-supervisory-visit`	RN only
`OASIS_ASSESSMENT`	`oasis-soc`	RN or PT (agency setting)
`OASIS_RECERTIFICATION`	`oasis-recert`	RN or PT (agency setting)
`OASIS_DISCHARGE`	`oasis-discharge`	RN or PT (agency setting)
`PHYSICIAN_SIGNATURE`	`communication-note`	Any (usually RN/case manager)

Step 2: System Queries Visit Type Mappings The backend looks up the visitTypeMapping table to find a mapping that matches:

The required form template key (e.g., hha-supervisory-visit)
The clinician's discipline (e.g., RN)

Example:

Query: formTemplateKey = "hha-supervisory-visit" AND discipline = "RN"
Result: VisitTypeMapping { id: "abc123", visitType: "HHA Supervisory Visit", discipline: "RN" }

If no mapping exists, an error is shown: "No visit type mapping found for [discipline] with form [form key]. Please configure visit types in Clinical Settings."

Step 3: Clinician Dropdown Filtered When the schedule modal opens, only clinicians with the matching discipline appear in the dropdown:

Example for HHA Supervisory Visit:

Shown: All clinicians with discipline: "RN"
Hidden: PT, OT, SLP, HHA, MSW, LPN (even if they're active clinicians)

Special Case: Assigned Clinician Restriction

Some compliance tasks are hard-assigned to a specific clinician and cannot be reassigned:

Example: LPN Supervisory Visit

When an LPN completes a visit, the task is created and assigned to the RN case manager of that patient
In the schedule modal, only that case manager appears in the clinician dropdown
You cannot assign it to a different RN
This ensures continuity of care and proper supervision chain

How to Tell:

If the compliance task has assignedToId set, the schedule modal will only show that clinician
If assignedToId is null, the modal shows all clinicians with the required discipline

Conflict Detection and Error Handling

The Schedule Center includes robust validation to prevent scheduling conflicts and errors.

Time Slot Collision Detection

What's Checked:

When you drag/drop or manually schedule a visit, the system checks if another visit already exists at that time for that clinician

Validation Logic:

Is there any existing visit where:
  - clinicianId matches the target clinician
  - scheduledAt time slot matches the target time
  - date matches the target date
  - status is "Scheduled" or "In Progress" (not "Cancelled" or "Completed")

Error Message: "This time slot is already occupied."

Resolution:

Choose a different time slot, OR
Choose a different clinician

2-Hour Late Cancellation Rule

What's Checked:

When you try to reschedule an already-scheduled visit by dragging it on the calendar

Rule: If the visit is scheduled to start within the next 2 hours, it cannot be rescheduled without cancelling first.

Why This Exists:

Clinicians may already be en route to the visit
Late rescheduling disrupts the patient's expectations
CMS considers rescheduling within 2 hours as a late cancellation, which can affect agency metrics

Error Message: "Late Cancellation: Cannot reschedule a visit starting in less than 2 hours."

Resolution:

Cancel the visit through the proper cancellation flow (which logs it as a late cancellation)
Create a new visit for the rescheduled time

Care Order Date Validation

What's Checked:

The selected visit date must fall within the patient's care order certification period

Example:

Care Order: Jan 1, 2026 → Feb 29, 2026
Valid visit date: Jan 15, 2026 ✅
Invalid visit date: Mar 5, 2026 ❌

Error Message: "Visit date must be within the care order period."

Resolution:

Choose a date within the care order period, OR
Extend the care order period (requires initiating recertification or resuming from hold)

Visit Status Restrictions

What's Checked:

Visits can only be rescheduled or edited if they're in Scheduled status

Rule:

In Progress - Cannot reschedule (clinician has already checked in)
Completed - Cannot reschedule (visit is done)
Missed - Cannot reschedule (must create a new visit)
Cancelled - Use the "Reschedule" button in the Cancelled Visits drawer

Error Message: "This visit is [status] and cannot be edited."

Resolution:

For In Progress: Wait for the clinician to complete the visit, then create a follow-up visit if needed
For Completed: This is a historical record; create a new visit if needed
For Cancelled: Use the reschedule function in the Cancelled Visits drawer

Discipline Mismatch

What's Checked:

When assigning a visit (regular or compliance task), the selected clinician's discipline must match the visit type's discipline requirement

Example:

Visit Type: "PT Evaluation" (requires discipline = "PT")
Selected Clinician: RN
Result: ❌ Error

Error Message: "No visit type mapping found for [RN] with form [pt-evaluation]. Please configure visit types in Clinical Settings."

OR (for compliance tasks): "Compliance Violation: This task must be performed by [required discipline name]."

Resolution:

Select a clinician with the correct discipline, OR
If no clinicians with that discipline exist, onboard a new clinician or configure visit type mappings in Clinical Settings

Best Practices for Effective Scheduling

1. Monitor Compliance Task Due Dates Daily

Why: Compliance tasks have regulatory implications. Overdue OASIS assessments can prevent billing. Overdue HHA supervisory visits can result in CMS deficiencies.

How:

Check the "Needs Scheduling" sidebar each morning
Look for patients with red "compliance" badges
Prioritize tasks marked as "Today" or "Tomorrow"
Schedule OASIS tasks well before their due dates to allow time for completion, QA review, and corrections

2. Balance Clinician Workloads

Why: Overloaded clinicians may rush visits, leading to poor documentation or patient dissatisfaction. Underutilized clinicians waste agency resources.

How:

Review the calendar daily to see how many visits each clinician has
Aim for 6-8 visits per day per field clinician (adjust based on visit types and travel distance)
Use the drag-and-drop feature to move visits between clinicians if one is overbooked
Consider travel distance: assign patients in the same geographic area to the same clinician on the same day

3. Schedule High-Priority Visits Early in the Day

Why: If a clinician encounters delays or emergencies, later visits may get missed. Critical visits (OASIS assessments, supervisory visits) should happen when the clinician is fresh and has buffer time.

How:

Schedule OASIS assessments in the 9:00 AM - 12:00 PM time slots
Reserve afternoon slots for routine visits or follow-ups
Avoid scheduling compliance tasks at 10:00 PM (late slots are for emergencies only)

4. Use the Active Visits Drawer for Real-Time Coordination

Why: Patient emergencies, clinician no-shows, or unexpected issues require quick response.

How:

Keep the Active Visits drawer open during peak field hours (9 AM - 3 PM)
If a visit shows as "In Progress" for longer than expected, call the clinician to check in
If a clinician hasn't checked in 15 minutes after scheduled start time, contact them
Use "View Clinician Location" to verify they're at the correct address (helps catch incorrect patient address issues)

5. Review Cancelled Visits Weekly

Why: Cancelled visits represent lost revenue and may indicate problems (frequent cancellations by a patient, clinician reliability issues, incorrect scheduling).

How:

Check the Cancelled Visits drawer every Friday
Identify patterns: Are specific patients cancelling frequently? Is one clinician cancelling more than others?
Reschedule any cancelled visits that were temporary (patient was sick, clinician had emergency)
For persistent cancellers, contact the patient to discuss barriers to care

6. Plan Ahead for Recertifications

Why: Recertification compliance tasks often have tight deadlines (must be done before episode end date). If delayed, the care order closes and billing stops.

How:

When a recertification task is created, schedule the OASIS assessment immediately (don't wait)
Schedule it at least 10 days before the episode end date to allow time for:
- Clinician to complete the visit
- QA review of the OASIS
- Corrections if QA returns it
- Physician signature if required
- CMS submission
Communicate with the case manager: "Recert OASIS for [patient name] is due by [date]. Please complete by [date]."

7. Coordinate HHA Supervisory Visits

Why: HHA supervisory visits must occur every 14 days while the patient receives HHA care. Missing this requirement is a CMS compliance violation.

How:

As soon as the HHA_SUPERVISORY_VISIT task appears, schedule it for a date within the next 14 days (don't wait until day 14)
Schedule it for a day when the case manager RN is already seeing nearby patients (reduces travel time)
When the supervisory visit is completed, a new task is auto-created—schedule it immediately
Track the cycle: HHA visit → 14 days → supervisory visit → 14 days → supervisory visit → ongoing

8. Use Filters and Search Effectively

Why: Large agencies may have hundreds of unscheduled visits. Finding the right patient quickly saves time.

How:

Use the patient search bar to find specific patients by name or MRN
Sort patients by earliest visit date to see who needs scheduling soonest
If multi-branch is enabled, switch branch context to focus on one branch at a time
Collapse visit type groups you're not working on to reduce clutter

Common Scenarios and Solutions

Scenario 1: Compliance Task Shows "No Eligible Clinicians"

Symptom: You open the schedule modal for a compliance task, and the clinician dropdown says "No eligible clinicians."

Cause: No clinicians in the system have the required discipline for this task type.

Example:

Task: HHA Supervisory Visit (requires RN)
Your clinicians: 3 HHAs, 2 PTs, 1 MSW
No RNs exist in the system

Solution:

Onboard an RN clinician through the Clinicians module
Ensure their discipline field is set to "RN" (not "Skilled Nursing" or other variations)
Once the RN is added, return to the Schedule Center and try again
The RN should now appear in the dropdown

Scenario 2: Dragging a Compliance Task Shows "Compliance Violation" Error

Symptom: You drag a compliance task to a clinician's column, and an error appears: "Compliance Violation: This task must be performed by [clinician name]."

Cause: This compliance task is hard-assigned to a specific clinician (usually the case manager) and cannot be reassigned.

Example:

Task: LPN Supervisory Visit (assigned to RN case manager "Jane Doe")
You try to assign it to a different RN ("John Smith")
Error appears

Solution:

Only assign this task to the designated clinician (Jane Doe in this example)
Drag it to Jane Doe's column, or use the schedule modal and select Jane Doe
If Jane Doe is unavailable (on vacation, resigned), you must:
1. Go to the patient's Care Order
2. Change the case manager to a different RN
3. The compliance task will automatically reassign to the new case manager
4. Return to Schedule Center and assign it

Scenario 3: Cannot Schedule Visit on a Specific Date

Symptom: When you try to schedule a visit on a specific date, the date picker shows that date as disabled (grayed out).

Cause: The selected date is outside the patient's care order certification period, or it's in the past.

Solution:

Check the care order dates:
- Go to Care Orders → select the patient → view certification start and end dates
Choose a date within the certification period
If the episode is about to end and you need to schedule beyond the end date:
- Initiate a recertification (see Care Orders chapter)
- The new episode extends the certification period
If the date is in the past:
- You cannot create visits on past dates (to prevent backdating)
- Create the visit for a current or future date

Scenario 4: Drag-and-Drop Shows "Time Slot Already Occupied"

Symptom: You drag a visit to a clinician's time slot, and an error appears: "This time slot is already occupied."

Cause: Another visit is already scheduled for that clinician at that time.

Solution:

Choose a different time slot for the same clinician
OR choose a different clinician (if they're qualified for this visit type)
If the existing visit in that slot is no longer needed, cancel it first, then reschedule the new visit

Scenario 5: Compliance Task Doesn't Disappear After Scheduling

Symptom: You schedule a compliance task (the visit appears on the calendar), but the task card remains in the "Needs Scheduling" sidebar.

Cause:

The backend successfully created the visit but failed to update the compliance task status to SCHEDULED
Or there's a frontend caching issue

Solution:

Refresh the page (F5 or Ctrl+R)
If the task still appears, check the backend logs:
- Look for errors related to complianceTask.update in the server logs
- Common issue: Transaction rollback due to validation failure
If the issue persists, contact your system administrator
As a workaround, manually cancel the task (click the X button) since it's effectively scheduled

Scenario 6: Clinician Has Too Many Visits in One Day

Symptom: A clinician's column shows 12 visits scheduled for a single day, which is not feasible.

Cause:

Multiple users scheduled visits to this clinician simultaneously
Automatic scheduling (via integrations) didn't check workload limits
The clinician is the default assignee for all tasks of a certain type

Solution:

Identify which visits can be rescheduled:
- Look for non-urgent visits (not compliance tasks, not today/tomorrow)
- Check for visits that can be performed by other qualified clinicians
Drag visits to other clinicians' columns to balance the workload
For compliance tasks assigned to this clinician, check if they can be reassigned:
- If the task allows any RN, reassign it
- If it's hard-assigned to this clinician, you must reschedule to a different day
Communication: Let the clinician know about the schedule change

Scenario 7: Visit Appears on Calendar but Clinician Says They Don't See It

Symptom: You scheduled a visit and it appears on the Schedule Center calendar, but the clinician reports it doesn't show in their mobile app.

Cause:

Mobile app hasn't synced yet (mobile apps sync every 5-15 minutes)
The clinician is logged into a different account
The visit is assigned to a different clinician than expected
The clinician has filtered their view (e.g., showing only "Today" visits, but the visit is tomorrow)

Solution:

Ask the clinician to pull-to-refresh in the mobile app
Verify the visit is assigned to the correct clinician:
- Click the visit card on the calendar
- Check the "Clinician" field
- If wrong, reassign it
Check the visit date:
- Mobile app may only show "Today" by default
- Ask clinician to change the date filter
If still not showing, log out and log back in on the mobile app
Last resort: Contact technical support (possible sync issue)

Permissions and Access Control

Different user roles have different capabilities in the Schedule Center.

Required Permissions

Action	Required Permission	Notes
View Schedule Center	`VIEW_SCHEDULE`	Without this, the Schedule Center menu item is hidden
View clinician list	`VIEW_USER`	Without this, no clinician columns appear on the calendar
Create manual visits	`CREATE_VISIT`	"+" button is hidden if user lacks this permission
Assign unassigned visits	`EDIT_VISIT`	Cannot drag visits from sidebar to calendar without this
Reschedule visits	`EDIT_VISIT`	Cannot drag visits on the calendar to new time slots
Cancel visits	`CANCEL_VISIT`	Cannot access the cancel visit function
Schedule compliance tasks	`EDIT_COMPLIANCE_TASKS`	Without this, compliance task "Schedule" buttons are hidden
Cancel compliance tasks	`EDIT_COMPLIANCE_TASKS`	Cannot click the X button on compliance task cards
Switch branches	`branch:manage`	Branch selector is hidden for users assigned to a specific branch

Role-Based Access Examples

Agency Administrator (Full Access)

Permissions: All permissions
Can Do:
- View entire agency schedule across all branches
- Create, assign, reschedule, and cancel visits
- Manage compliance tasks
- Switch between branches
- View active and cancelled visits

Branch Manager (Branch-Specific)

Permissions: All permissions except branch:manage
Can Do:
- View schedule for their assigned branch only
- Create, assign, reschedule, and cancel visits within their branch
- Manage compliance tasks for their branch patients
- View active and cancelled visits for their branch

Office Coordinator (Limited)

Permissions: VIEW_SCHEDULE, VIEW_USER, CREATE_VISIT
Can Do:
- View the schedule
- Create new manual visits
Cannot Do:
- Assign unassigned visits
- Reschedule existing visits
- Cancel visits
- Manage compliance tasks

Clinician (Read-Only)

Permissions: VIEW_SCHEDULE, VIEW_USER
Can Do:
- View the schedule to see their assignments
- See which patients other clinicians are visiting
Cannot Do:
- Create, edit, or cancel visits
- Manage compliance tasks
- Note: Clinicians typically manage their schedule through the mobile app, not the Schedule Center

Troubleshooting Common Issues

Issue: Calendar is Empty / No Clinicians Showing

Possible Causes:

No clinicians are onboarded in the system
User lacks VIEW_USER permission
Selected date has no scheduled visits
Branch filter is excluding all clinicians

Solutions:

Check Clinicians module to ensure clinicians exist and are active
Verify user permissions in User Roles & Permissions
Try selecting a different date (use the date picker)
If multi-branch: switch to "Head Quarter" to see all clinicians

Issue: Patient Has Compliance Task But Can't Schedule It

Possible Causes:

User lacks EDIT_COMPLIANCE_TASKS permission
No clinicians with required discipline exist
Backend validation error (e.g., care order is closed)

Solutions:

Verify user permissions
Check if clinicians with the required discipline are onboarded
Check the patient's care order status (must be Active or ON_HOLD, not Closed)
Check browser console for error messages

Issue: Compliance Task Keeps Reappearing After Completion

Possible Causes:

For HHA/LPN supervisory visits: New tasks are auto-created after completion (this is intentional)
Backend failed to mark task as complete

Solutions:

If it's a supervisory visit, this is expected behavior—a new task is created for the next cycle
If it's a one-time task (like OASIS), check if the visit note was actually approved in QA Center
Verify the compliance task's status in the database (should be COMPLETE)

Issue: Visit Shows in Schedule Center But Not in Mobile App

Possible Causes:

Mobile app hasn't synced
Visit is assigned to wrong clinician
Visit date filter in mobile app

Solutions:

Pull to refresh in mobile app
Verify clinician assignment in Schedule Center
Check date filter in mobile app (expand to see more days)
Log out and log back in on mobile app

Integration with Other Modules

The Schedule Center is tightly integrated with other parts of the system:

Care Orders Module

Link: Visits are always linked to a care order
Impact: When a care order is closed (discharged), all scheduled visits are automatically cancelled
Flow: Initiating recertification or discharge in Care Orders creates compliance tasks that appear in Schedule Center

QA Center Module

Link: When a visit note is approved in QA Center, the linked compliance task (if any) is marked as complete
Impact: OASIS assessments scheduled via compliance tasks won't be considered "complete" until the OASIS document is approved in QA

Clinicians Module

Link: Clinicians must be onboarded and have the correct discipline field set
Impact: If a clinician's discipline changes, they may lose eligibility for certain compliance tasks they were previously assigned to

Patient Module

Link: Patients must have an active care order to have visits scheduled
Impact: If a patient's care order is On Hold, you can only schedule OASIS ROC (Resumption of Care) visits

Mobile App

Link: All visits scheduled in Schedule Center sync to the mobile app for clinicians
Impact: Clinicians check in, complete visit notes, and mark visits complete via mobile app, which updates the Schedule Center in real-time

Performance Tips for Large Agencies

If your agency has 50+ clinicians and 500+ active patients, the Schedule Center can feel slow. Use these tips to improve performance:

1. Use Branch Filtering

If multi-branch is enabled, switch to a specific branch instead of viewing "Head Quarter" (which loads all clinicians and patients)

2. Navigate by Date, Not Range

The Schedule Center loads data for a single day at a time
Don't try to view multiple days simultaneously (use the date picker to jump between days)

3. Collapse Unused Visit Type Groups

When a patient card is expanded, collapse visit type groups you're not currently scheduling
This reduces the number of DOM elements rendered

4. Use Patient Search

Instead of scrolling through hundreds of patients in the sidebar, use the search bar to filter

5. Schedule in Batches

Assign all visits for one patient before moving to the next
This reduces sidebar refreshes