RBT Note Error and Warning Messages

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

This feature guides users while creating or updating RBT notes by showing clear warnings and errors when required clinical, scheduling, authorization, or billing-related information is missing or invalid. It helps prevent incomplete notes, invalid session times, unsupported PA usage, and records that could cause compliance or billing issues.

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

• RBT/Analyst (or any role with create_notes_rbt): Can create RBT notes and receives the same form-level warnings and save-blocking validation messages.
• Admin / Owner / Manager / Superadmin (or any role with manage_notes): Can create or update RBT notes on behalf of providers and may also handle operational corrections.
• Users with ignore_time_limits: Can bypass time-limit, backdating, CPT daily limit, and transition-time checks where configured, but still receive required-field, chronology, future-date/time, overlap, PA weekly unit, and clinical data validation messages.
• Users with ignore_weekly_units_limit: Can bypass the PA Service weekly unit limit, while other validations still apply.

Required permission context:

• create_notes_rbt
• manage_notes
• ignore_time_limits
• ignore_weekly_units_limit

3. Business Rules & Enforcements

• Rule 1: Missing setup warnings appear before saving. If the patient has no BIP, the form warns the user and the create-mode save action is disabled. If no BCBA supervisor or Clinical Director is available, the user is blocked from creating the note and returned to the previous screen.
• Rule 2: PA Service date warnings appear when the selected DOS is outside the patient’s primary RBT PA range for CPT 97153. The form clears the DOS and tells the user that no PA is available for the service date.
• Rule 3: Required form fields are checked before save. The user sees a “Missing Required Fields” modal listing the missing items, including rendering provider, DOS, PA range, time period, POS, POS 99 description, supervisor, maladaptives, replacements, interventions, participants, environmental changes, antecedents, summary note, next session date, client appeared, as evidenced by, and caregiver modeling.
• Rule 4: AI summary generation has its own warning. The user must complete required maladaptive and replacement data before the AI summary can be generated.
• Rule 5: Informational time warnings do not block saving. The form warns when POS is School and the time is outside Monday-Friday school hours, or when any entered time is before 6:00 AM and may have been entered incorrectly in 24-hour format.
• Rule 6: Clinical data quality warnings do not block saving. The form warns when the number of objectives or trials appears very small, and projection warnings may appear when maladaptive or replacement data falls outside the expected BIP projection range.
• Rule 7: Backend validation blocks invalid saves. The API rejects future session dates, future session times in the location timezone, invalid time order, overlapping patient/provider sessions, incompatible overlapping POS rules, exceeded daily/weekly hour limits, backdated notes outside the configured limit, missing CPT limit configuration, exceeded CPT daily units, exceeded PA Service weekly units, and invalid required replacement or maladaptive data.
• Rule 8: Authorization and state errors block the action. Users see an error when patient/location access cannot be verified, when the note is not found, when a voided note cannot be modified, when the user cannot un-void a note, or when the user cannot change the supervisor.
• Rule 9: Save failures are shown in a single error modal. If the backend returns field errors, the UI lists each returned message. If it returns a single message, the UI shows that message.

Main user-facing warning and error messages:

• Behavior Intervention Plan Missing: No BIP was found for the patient; the note cannot be saved in create mode until clinical setup is corrected.
• Unable to Create Note: No BCBA supervisor or Clinical Director is available for the patient.
• Date out of PA Service range: No PA exists for the selected service date; the user must select a valid DOS or contact the office.
• Missing Required Fields: Required note fields are incomplete.
• Missing Required Fields for AI Summary: Required maladaptive or replacement data is incomplete before AI generation.
• School-hours warning: POS School has a session time outside Monday-Friday, 8:00 AM to 3:00 PM.
• Outside normal hours warning: One or more session times is before 6:00 AM.
• Objectives/trials warning: The number of objectives or trials worked on appears very small.
• Future date/time errors: Session date or entered times are in the future.
• Overlap errors: Patient or provider already has a conflicting note time, or overlapping notes with different CPT/POS combinations do not meet the allowed rules.
• Limit errors: Daily hours, weekly hours, CPT daily units, PA weekly units, or backdating limits have been exceeded.
• Clinical detail errors: Required maladaptive occurrences, replacement trials, correct responses, or first-trial steps are missing or not allowed for that replacement type.

4. UI Placement

1. Medical > Patient list > Patient actions > Create RBT Note.
2. Create route: /note-rbt/:patient_id or /note-rbt/:patient_id/:appointment_id.
3. Edit route: /note-rbt/edit/:patient_id/:id.
4. Inside the RBT note form:
   • Setup warnings appear when patient, BIP, supervisor, and PA data loads.
   • Time warnings appear near the session time fields.
   • Required-field errors appear when the user clicks Save or requests AI summary generation.
   • Backend validation errors appear after the user clicks Save or Update.

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

Scenario A: Review and resolve a setup warning

1. Open Create RBT Note for a patient.
2. If the system shows a missing BIP warning, contact the supervisor or administrator to complete the patient’s BIP setup.
3. If the system shows that no supervisor is available, assign a BCBA supervisor or Clinical Director to the patient.
4. Reopen the RBT note form after setup is corrected.

Scenario B: Resolve required-field errors before saving

1. Complete the RBT note form and click Save.
2. Review the “Missing Required Fields” modal.
3. Complete each listed item in the form.
4. Click Save again.
5. If the backend returns additional validation messages, correct the listed time, PA, clinical, or authorization issue and retry.

Scenario C: Handle time and PA warnings

1. Select the DOS and confirm the system finds a matching PA Service for CPT 97153.
2. Enter the first session time block, and a second time block when needed.
3. Review school-hours, early-hours, small-trial, and projection warnings.
4. Correct obvious entry mistakes, or document the clinical context when the warning is informational.
5. Save the note once all blocking errors are resolved.

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

• Q: Do all warnings block saving? A: No. Missing BIP, missing supervisor, missing required fields, invalid PA range, and backend validation errors block saving. School-hours, early-hours, low-trial/objective, and projection warnings are informational.

• Q: What happens if the user has ignore_time_limits? A: The user can bypass specific time-limit, backdating, CPT daily limit, and transition-time checks, but the note can still be rejected for missing required fields, invalid chronology, future date/time, overlap, PA weekly unit limit, or clinical data errors.

• Q: What happens if the backend returns multiple validation errors? A: The form shows all returned validation messages in the error modal so the user can correct every issue before trying again.