BCBA Note Error and Warning Messages

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

This feature gives BCBA note users clear warnings, blocking errors, and validation feedback while they create or update a note. It helps prevent incomplete, non-compliant, or incorrectly timed documentation before the note is saved.

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

• BCBA/Analyst: Sees warnings and validation messages while documenting BCBA sessions and must resolve blocking errors before saving.
• Admin / Owner / Manager / Superadmin: Sees the same messages when creating or editing BCBA notes for operational review or correction.
• Users with manage_notes: Can manage broader note workflows, including selecting rendering providers and supervisors where the UI allows it.
• Users with ignore_time_limits: Can bypass daily/weekly hour limits, backdating limits, and CPT daily unit limits, but still see and must respect base validation, overlap, and required-field errors.
• Users with ignore_weekly_units_limit: Can bypass PA Service weekly unit limit validation, but not the rest of the BCBA note validations.

3. Business Rules & Enforcements

• Rule 1: The form displays an informational reminder that session times use military time.
• Rule 2: The form warns when session time appears outside standard school hours or before 6:00 AM, so users can review the time and POS before saving.
• Rule 3: The form blocks normal creation for BCBA note types that require a BIP when the patient does not have an associated BIP.
• Rule 4: The selected DOS must fall within an active primary PA service for a non-97153 BCBA CPT. If not, the user receives a PA range warning and the selected date is cleared.
• Rule 5: The save action blocks incomplete notes and displays a consolidated list of missing required fields, including patient, DOS, time, rendering provider, supervisor, POS, CPT, summary note, and CPT-specific fields.
• Rule 6: If POS 99 is selected, the user must choose the POS 99 description.
• Rule 7: When the insurance requires telehealth classification, the user must answer Is this note Telehealth?.
• Rule 8: For 97151, telehealth POS values show a warning reminding the user to confirm telehealth compliance.
• Rule 9: For 97151, if there is no prior qualifying note in the configured window and the first-note subtype rule is violated, the backend returns HTTP 422 with: Cannot create first BCBA note 51: the first BCBA note must be an observation/parent interview.
• Rule 10: For 97156, caregiver or teacher goal documentation is only allowed for POS values configured on the patient’s insurance. If the selected POS is not allowed, the UI displays a danger message and the save is blocked.
• Rule 11: The Name Of The Person/Persons Present This Session field must contain specific names. Generic labels such as role names or family labels are rejected by the UI.
• Rule 12: Custom environmental change text is limited to 255 characters.
• Rule 13: For 97155, the form requires participants, environmental changes, at least one maladaptive value, at least one replacement value, at least one protocol modification, protocol modification narratives, progress compared to the previous session, and RBT goal percentages when an RBT was present.
• Rule 13: For 97155, the two protocol modification narrative fields must contain meaningful text of at least 25 characters.
• Rule 15: For 97156, the form requires participants, environmental changes, progress compared to the previous session, and at least one caregiver goal value when the selected POS allows caregiver goals.
• Rule 16: The backend rejects future session dates, future session times for the patient’s location timezone, invalid time order, overlapping schedules, missing CPT limit configuration, exceeded daily/weekly limits, exceeded PA weekly units, and invalid BIP/goal references.
• Rule 17: Some limit validations can be bypassed by authorized permissions, but overlap, required fields, future dates/times, POS requirements, and data integrity validations remain enforced.
• Rule 18: If the backend returns validation errors, the UI displays them in the error modal so the user can correct the exact issue.

4. UI Placement

1. BCBA note creation screen: /note-bcba/:patient_id and appointment-based /note-bcba/:patient_id/:appointment_id.
2. BCBA note edit screen: /note-bcba/edit/:patient_id/:id.
3. Top of the form: Edit-mode information and missing-BIP blocking warning.
4. Time section: Military-time reminder, school-hours warning, before-6:00-AM warning, and session length totals.
5. DOS/CPT/POS area: PA range warning, CPT-specific type requirements, POS warnings, caregiver POS restriction, and telehealth required message.
6. Clinical details area: Environmental changes length message and specific-names validation for people present.
7. Save action: Missing required fields modal, protocol narrative errors, and backend validation errors.

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

Scenario A: Resolve missing required fields before saving

1. Open the BCBA note creation or edit screen.
2. Complete the patient, DOS, time, rendering provider, supervisor, POS, CPT, and summary note fields.
3. Click Save.
4. If the Missing Required Fields modal appears, review the listed items.
5. Complete each listed field in the form.
6. Click Save again.

Scenario B: Handle PA, BIP, and POS warnings

1. Select the DOS.
2. If the PA range warning appears, confirm whether the selected date is correct.
3. If no valid PA exists for that date, contact the office before continuing.
4. Select the CPT and POS.
5. If a BIP warning appears, create or attach the patient’s BIP before creating the note type that requires it.
6. If a caregiver POS or telehealth warning appears, correct the POS or telehealth answer before saving.

Scenario C: Correct backend validation errors after save

1. Click Save.
2. If the system returns an error modal, read the message shown in the modal.
3. Correct the related field, such as time order, overlapping time, future time, CPT units, PA weekly units, or invalid goal reference.
4. Save again after the error condition is resolved.

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

• Q: What happens if the user has ignore_time_limits? A: Daily/weekly hour limits, backdating limits, and CPT daily unit limits are bypassed, but overlap, required-field, future date/time, POS, and integrity validations still apply.

• Q: What happens if the selected POS is not allowed for 97156 caregiver training goals? A: The UI displays the allowed POS values configured for the insurance and blocks saving until the POS is corrected.

• Q: What happens if the frontend does not catch a problem before save? A: The backend still validates the request. Any returned validation errors are shown in the error modal for the user to correct.

• Q: What exact error appears when the first 97151 note rule is violated? A: The API responds with HTTP 422 and: Cannot create first BCBA note 51: the first BCBA note must be an observation/parent interview.