Missing Notes Notifications

1. What does this feature do? (High-Level Overview)

Missing Notes Notifications automatically alert providers who have scheduled appointments with clients but haven’t yet added the required clinical notes for those sessions. This helps ensure timely documentation and compliance with billing and clinical standards by sending email and/or SMS reminders to providers.

2. Who is this for? (Roles & Permissions)

• Superadmin: Can configure missing notes notification settings for any location.
• Admin: Can configure missing notes notification settings for locations they manage.
• Owner: Can configure missing notes notification settings for their own locations.
• Providers (Recipients): RBTs, BCBAs, and other clinical staff who log session notes receive these notifications when they have incomplete documentation.

Required Permission: Access to location settings for configuration

3. Business Rules & Enforcements

• Rule 1: Notifications are sent per location - each location’s settings control whether its providers receive alerts.
• Rule 2: Only providers who have scheduled appointments with 0 units (no notes logged) are notified.
• Rule 3: Email and SMS channels are mutually exclusive in the UI - enabling one automatically disables the other (though both can be technically enabled via API).
• Rule 4: If neither email nor SMS is enabled, no notifications are sent and a warning is displayed in the location settings.
• Rule 5: SMS notifications require a valid phone number (at least 10 digits) - providers without valid phones are skipped.
• Rule 6: Notifications filter by CPT code (default: 97153 for RBT services) to ensure only relevant services trigger alerts.
• Rule 7: Notifications are sent based on the current date (or specified date in command) - typically run daily.
• Rule 8: The system only sends notifications in production environments - non-production runs automatically use dry-run mode.

4. UI Placement

Configuration Interface

Location: Admin View > Locations > Edit Location Route: /location/list/edit/:id Section: “Missing Notes Notification Settings” Position: Located in the location edit form, after basic location information

Configuration Fields

Email Notification Toggle:

• Field ID: missing_notes_email_enabled
• Label: “Send Email Notifications”
• Description: “Send email alerts when providers don’t add notes”
• Default: Enabled (true)
• Type: Checkbox toggle

SMS Notification Toggle:

• Field ID: missing_notes_sms_enabled
• Label: “Send SMS Notifications”
• Description: “Send SMS alerts when providers don’t add notes (requires valid phone)”
• Default: Disabled (false)
• Type: Checkbox toggle

Warning Message: When both toggles are disabled, a warning appears:

“No notification channels enabled. Providers will NOT be notified about missing notes.”

5. How-To Guide (Step-by-Step)

Scenario A: Enabling email notifications for missing notes

1. Navigate to Admin View > Locations
2. Find the location and click Edit
3. Scroll to the Missing Notes Notification Settings section
4. Ensure the Send Email Notifications toggle is ON (enabled)
5. The Send SMS Notifications toggle will automatically turn OFF
6. Click Save to apply the changes
7. Providers at this location will now receive daily email reminders for missing notes

Scenario B: Switching from email to SMS notifications

1. Navigate to the location edit page
2. Locate the Missing Notes Notification Settings section
3. Click the Send SMS Notifications toggle to ON
4. The Send Email Notifications toggle will automatically turn OFF
5. Click Save to apply the changes
6. Providers with valid phone numbers will now receive SMS alerts instead of emails

Scenario C: Disabling all missing notes notifications

1. Navigate to the location edit page
2. In the Missing Notes Notification Settings section
3. Turn OFF both the email and SMS toggles
4. A warning message will appear indicating no notifications will be sent
5. Click Save to confirm
6. No missing notes notifications will be sent for this location

Scenario D: Understanding the notification content

Email Content:

• Subject: Reminder about missing notes
• Body: Lists all clients with missing notes, including:
  • Client names
  • CPT codes with 0 units
  • Date of the missing notes
  • Location name

SMS Content:

• Personalized message with provider name
• Number of clients with missing notes
• Date and location
• Example: “Hi John Smith, you have 3 clients with missing notes for 2026-04-03 at Main Clinic. Please complete your documentation.”

6. What happens if…? (Edge Cases / FAQ)

• Q: What happens if a provider has no email address on file and email notifications are enabled?

  • A: The system will skip that provider and log a warning. The command output will show “Provider ID X not found or has no email.”

• Q: What happens if SMS is enabled but the provider’s phone number is invalid or missing?

  • A: The system will skip sending SMS to that provider and display a message: “Provider [Name] has no valid phone for SMS.” Email will still be sent if that channel is also enabled.

• Q: What CPT codes trigger missing notes notifications?

  • A: By default, the system filters by CPT code 97153 (RBT services). This can be customized via the command’s --cpt_code option when running manually.

• Q: How often are missing notes notifications sent?

  • A: Notifications are sent based on the scheduled command frequency, typically once daily. The command checks for missing notes on the current date (or a specified date).

• Q: Can I test the notifications before enabling them for real?

  • A: Yes, the backend command supports a --dry-run flag that shows exactly what would be sent without actually sending emails or SMS. Contact your system administrator to run: php artisan notes:send-missing-notifications --dry-run

• Q: What happens to providers with missing notes in multiple locations?

  • A: If a provider works in multiple locations with different notification settings, they may receive multiple notifications - one for each location’s configuration. The system merges clients across locations when sending.

• Q: Are past missing notes included in notifications?

  • A: No, notifications are sent for the specific date being checked (default: today). Historical missing notes are not included unless the command is run with a specific past date using --date=YYYY-MM-DD.

• Q: What happens if the command fails to send a notification?

  • A: The system logs the failure with details (provider ID, email/phone, error message) and continues processing other providers. The command will return a failure status if any notifications fail.

---

Technical Details

Backend Command

Command: php artisan notes:send-missing-notifications

Available Options:

• --date=YYYY-MM-DD - Check specific date (defaults to today)
• --location_id=X - Check only a specific location
• --cpt_code=XXXXX - Filter by specific CPT code (default: 97153)
• --dry-run - Show what would be sent without actually sending

Example Usage:

# Check today's missing notes for all locations
php artisan notes:send-missing-notifications

# Check specific date
php artisan notes:send-missing-notifications --date=2026-04-01

# Check only location 5
php artisan notes:send-missing-notifications --location_id=5

# Dry run to preview
php artisan notes:send-missing-notifications --dry-run

How It Works

1. Query Appointments: The command queries the EmployeeHoursService to get all scheduled appointments for the specified date and location(s)
2. Filter Missing Notes: It filters for appointments where CPT code units = 0 (no notes logged)
3. Group by Provider: Missing notes are grouped by provider to send one notification per provider
4. Check Location Settings: For each location, the command checks if notifications are enabled via hasMissingNotesNotificationsEnabled() and gets active channels via getMissingNotesNotificationChannels()
5. Send Notifications: Based on enabled channels:
   • Email: Uses MissingNotesNotificationMail mailable
   • SMS: Uses NotifyreService to send SMS via external provider
6. Logging: All actions are logged including successes, failures, and skipped providers

Data Model

Location Model Fields:

missing_notes_notification_settings: array|null
// Structure:
[
    'email_enabled' => true,
    'sms_enabled' => false
]

Helper Methods:

// Check if any notifications are enabled
$location->hasMissingNotesNotificationsEnabled(): bool

// Get array of enabled channels ['email', 'sms']
$location->getMissingNotesNotificationChannels(): array

// Individual channel checks
$location->isMissingNotesEmailEnabled(): bool
$location->isMissingNotesSmsEnabled(): bool

SMS Message Structure

Built using MissingNotesSmsBuilder:

• Includes provider name
• Client count
• Date
• Location name
• Concise format to fit SMS character limits

Email Template

Uses MissingNotesNotificationMail:

• Professional HTML email format
• Detailed table of clients with missing notes
• Each client shows:
  • Client name
  • Client ID
  • CPT codes with 0 units
• Call to action to complete documentation

Logs and Audit Trail

Success Logs:

Missing notes email sent
- provider_id
- email
- client_count
- date
- location

Failure Logs:

Failed to send missing notes email/SMS
- provider_id
- email/phone
- error message

Security and Production Safeguards

• Environment Check: Automatically forces --dry-run if not in production or if APP_URL is not https://backend.pmc-app.com
• Phone Masking: Phone numbers are masked in logs (e.g., 555****89) for privacy
• Error Handling: All exceptions are caught and logged without stopping the entire process