PA Service Configured Weekly Limit

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

This feature lets clinic staff define an optional weekly cap, expressed in units, for each CPT line inside a client’s PA Service. When a value is configured, the system uses it to validate weekly note submissions for that PA Service and to feed weekly availability metrics in reporting, ensuring that providers do not exceed the authorized weekly volume agreed with payers. This feature is currently available.

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

• Users who can edit a client profile can configure the weekly limit on each CPT line of any PA Service.
• Providers logging notes are subject to the limit when it is configured.
• Designated users can bypass the limit when justified.

Required permissions used by this feature path:

• update_clients: required to enter edit mode in the PAs section of the client profile and to save the field.
• ignore_weekly_units_limit: allows a user to save RBT or BCBA notes that would otherwise exceed the configured weekly limit for the PA Service.

3. Business Rules & Enforcements

• Rule 1: The field is optional and stored per CPT line of a PA Service, not per PA Service header.
• Rule 2: Allowed value is a whole number greater than or equal to 1. Empty is treated as “no weekly cap configured”.
• Rule 3: When configured, the system aggregates RBT and BCBA notes pinned to the same PA Service for the calendar week (Sunday through Saturday) of the session date.
• Rule 4: If the aggregated weekly units, plus the units projected for the note being saved, exceed the configured limit, the note is rejected with the message: “This note exceeds the weekly units limit configured for this PA Service. Please review and adjust.”
• Rule 5: When editing an existing note, that note’s current units are excluded from the running weekly sum to avoid double counting.
• Rule 6: Users with the ignore_weekly_units_limit permission can save notes that exceed the limit. The configured value is preserved on the PA Service.
• Rule 7: When the field is empty, no weekly note-level enforcement applies. Weekly availability values fall back to an average computed from remaining units and remaining weeks of the PA Service.
• Rule 8: Changes to this field are tracked in the PA Service activity log (pa_services) under weekly_units_limit.
• Rule 9: The configured value also drives the Prior Authorizations report’s weekly availability columns. See the cross-reference in the Prior Authorizations Report doc for the reporting impact.

4. UI Placement

• Configuration entry path:

1. Medical > Clients list.
2. Open client profile.
3. PAs section.
4. Click the edit (pencil) action to enter edit mode for the PAs section. This requires update_clients.
5. Click “Add PA Service” or open an existing PA Service for editing.
6. In the PA Service modal, locate the “Weekly Units Limit (optional)” field next to Number of Units, Spent Units, and the date range.

• Enforcement entry points:

1. RBT note creation/edit screen (saving the note evaluates the weekly aggregate against the configured limit for the selected PA Service).
2. BCBA note creation/edit screen (same evaluation as RBT, contributing to the same weekly aggregate).

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

Scenario A: Configure a weekly limit for a CPT line

1. Open the client profile under Medical > Clients.
2. Scroll to the PAs section and click the edit (pencil) action.
3. Open an existing PA Service or click “Add PA Service”.
4. In the modal, enter a value of 1 or higher in “Weekly Units Limit (optional)” for the CPT that needs a weekly cap.
5. Confirm the rest of the fields (CPT, total units, dates, insurance) and click “Update” or “Add PA Service”.
6. Save the PAs section. Future notes posted to this PA Service will be validated against the cap.

Scenario B: Leave the weekly limit empty (no cap)

1. Open the PA Service modal as in Scenario A.
2. Leave the “Weekly Units Limit” field blank. The helper tooltip reads: “Leave empty to use the average derived from total units and date range.”
3. Save the PA Service. Notes will not be capped by week, and weekly metrics in reporting will be derived from remaining units over remaining weeks.

Scenario C: A provider hits the weekly cap while saving a note

1. The provider logs an RBT or BCBA note for the affected client, selects the PA Service, and enters the session time.
2. On save, the system sums all RBT and BCBA units already logged against that PA Service for the same Sunday–Saturday week and adds the units projected for the new note.
3. If the total exceeds the configured weekly limit, the save is blocked and the message “This note exceeds the weekly units limit configured for this PA Service. Please review and adjust.” is displayed.
4. The provider must reduce the session time, choose another PA Service, or escalate to a user who can bypass the limit.

Scenario D: Authorized user bypasses the limit

1. A user with ignore_weekly_units_limit attempts to save the same note from Scenario C.
2. The weekly check is skipped and the note is saved normally.
3. The configured weekly limit on the PA Service is not changed by this action.

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

• Q: What happens to notes that were already logged before a weekly limit was configured?
  • A: Past notes are not affected. They continue to count toward the weekly aggregate for any week in which they fall, but the system does not retroactively reject them.
• Q: What if a note is moved to a different PA Service?
  • A: The weekly aggregate is computed per PA Service. Moving a note changes which PA Service’s weekly total it contributes to. The new PA Service’s weekly cap is evaluated at save time.
• Q: Does the limit apply across RBT and BCBA notes together?
  • A: Yes. RBT and BCBA notes attached to the same PA Service share the same weekly bucket; both are summed before comparing to the configured limit.
• Q: What if the configured limit is lower than the units already logged for the current week?
  • A: New note saves for that week will fail until the week rolls over or units are reduced. Existing logged notes are not modified.