Out of Projection Settings

Out of Projection Settings

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

The Out of Projection Settings feature allows administrators to control two independent aspects of the “Out of Projection” functionality on a per-location basis:

1. Projection Warnings in RBT Notes: Controls whether clinical staff see warning alerts when recording behaviors (maladaptives/replacements) that fall outside their expected projection ranges
2. Projection Report Access: Controls whether users can access the “Out of Projection” report for a specific location

Each location can independently enable or disable these features, giving organizations flexibility to tailor clinical workflows to their specific needs without affecting other locations.

Key Benefits

• Flexible Clinical Workflows: Locations can choose whether to use projection-based warnings
• Customizable Reporting: Control report visibility per location
• No Impact on Other Locations: Settings are isolated per location
• Backward Compatible: Defaults to enabled for all existing locations
• Independent Controls: Warnings and reports can be enabled/disabled separately

---

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

Roles & Permissions

Who can configure these settings?

• Administrators with manage_locations permission
• Super Admins (global role)

Who is affected by these settings?

• RBT/Clinical Staff: See or don’t see projection warnings when creating notes
• All Users with Report Access: Can or cannot access the Out of Projection report based on their current location

Permission Requirements:

• Configure Settings: Requires manage_locations permission (typically Admin/Super Admin only)
• View Warnings: No permission required - controlled solely by location setting
• View Reports: Requires view_projection_report permission AND location must have reports enabled

---

3. Business Rules & Enforcements

Default Behavior

When the feature was implemented, all existing locations were automatically configured with:

• ✅ Projection Warnings: ENABLED (true)
• ✅ Projection Reports: ENABLED (true)

This ensures no disruption to existing workflows - everything continues working as before until explicitly changed.

New Locations

When creating a new location, if settings are not specified:

• Both toggles default to ENABLED (true)
• Ensures consistent behavior across the system

Setting Rules

1. Independent Controls: The two settings are completely independent

   • You can disable warnings while keeping reports enabled
   • You can disable reports while keeping warnings enabled
   • You can disable both
   • You can enable both (default)

2. Location-Scoped: Settings apply only to the specific location

   • Each location has its own configuration
   • Changing one location doesn’t affect others

3. Permission + Setting Check: For report access, BOTH conditions must be met:

   • User must have view_projection_report permission
   • User’s current location must have reports_enabled: true

4. Admin View Override: When in Admin View mode, report access is always allowed regardless of location settings

Data Integrity

• Database Constraint: Settings cannot be NULL - database enforces NOT NULL
• Required Fields: Both warnings_enabled and reports_enabled are required when saving
• Type Safety: Values must be boolean (true/false)

---

4. UI Placement

Location Settings Form

Path: Locations > Add/Edit Location

The Out of Projection Settings appear as a dedicated section in the location form.

RBT Note Warnings (When Enabled)

Path: Notes > RBT Note > Maladaptives / Replacements Section

When warnings are disabled: The same form appears but without the alert box.

Report Access

Path: Reports > Clinical Tab

When reports are enabled for current location:

• “Out of Projection” report card is visible in the Clinical tab
• Clicking the card navigates to the report

When reports are disabled for current location:

• “Out of Projection” report card is hidden from the list
• Direct URL access is blocked with an error message

---

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

Configuring Out of Projection Settings

Creating a New Location with Custom Settings

1. Navigate to Location Form

   • Go to Locations
   • Click “Add Location” button

2. Fill Basic Information

   • Enter required fields:
     • Location Title
     • Address
     • City, State, ZIP
     • Contact information

3. Scroll to “Out of Projection Settings” Section

   • Located after “Missing Notes Notification Settings”
   • Contains two checkboxes

4. Configure Projection Warnings

   • Checkbox: “Enable Projection Warnings in RBT Notes”
   • Default: ✅ Checked (enabled)
   • Effect: When enabled, RBT staff see warning alerts when behaviors are out of expected projection ranges

   To Enable:

   • ✅ Keep checkbox checked

   To Disable:

   • ☐ Uncheck the checkbox

5. Configure Projection Reports

   • Checkbox: “Enable Out of Projection Reports”
   • Default: ✅ Checked (enabled)
   • Effect: When enabled, users can access the Out of Projection report for this location

   To Enable:

   • ✅ Keep checkbox checked

   To Disable:

   • ☐ Uncheck the checkbox

6. Review Settings

   • Verify both toggles are set as desired
   • Common configurations:
     • ✅ ✅ Both enabled (default - full functionality)
     • ☐ ✅ Warnings off, Reports on (data collection without alerts)
     • ✅ ☐ Warnings on, Reports off (alerts without report access)
     • ☐ ☐ Both off (projection features completely disabled)

7. Save Location

   • Click “Save” button
   • System validates that both settings are provided
   • Location is created with specified settings

Editing Existing Location Settings

1. Navigate to Location

   • Go to Locations
   • Find the location you want to edit
   • Click “Edit” button or click on the location name

2. Scroll to “Out of Projection Settings”

   • Section is pre-populated with current values
   • Both checkboxes show current state

3. Modify Settings

   • Check or uncheck boxes as needed
   • Changes are independent - you can change one without changing the other

4. Save Changes

   • Click “Save” button
   • Changes apply immediately
   • No need to recreate notes or reports

Configuration Scenarios

Scenario 1: Disable Projection Features Completely

Use Case: Location doesn’t use projection-based clinical methodology

Steps:

1. Edit the location
2. ☐ Uncheck “Enable Projection Warnings in RBT Notes”
3. ☐ Uncheck “Enable Out of Projection Reports”
4. Save

Result:

• No warnings appear in RBT notes for this location
• Report card is hidden for this location
• Other locations are unaffected

Scenario 2: Keep Data Collection But Remove Visual Warnings

Use Case: Location finds warnings distracting but wants report access

Steps:

1. Edit the location
2. ☐ Uncheck “Enable Projection Warnings in RBT Notes”
3. ✅ Keep checked “Enable Out of Projection Reports”
4. Save

Result:

• No warnings in RBT notes
• Report remains accessible
• Data is still tracked and available in reports

Scenario 3: Show Warnings But Restrict Report Access

Use Case: Want clinical alerts but limit report visibility for privacy/compliance

Steps:

1. Edit the location
2. ✅ Keep checked “Enable Projection Warnings in RBT Notes”
3. ☐ Uncheck “Enable Out of Projection Reports”
4. Save

Result:

• Warnings still show in RBT notes
• Report is hidden and inaccessible
• Clinicians get real-time feedback without report access

Scenario 4: Re-Enable Features After Disabling

Use Case: Location previously disabled features but wants to re-enable

Steps:

1. Edit the location
2. ✅ Check “Enable Projection Warnings in RBT Notes”
3. ✅ Check “Enable Out of Projection Reports”
4. Save

Result:

• Features immediately re-enabled
• Warnings start showing in new notes
• Report becomes accessible again
• No data loss - historical data is preserved

How Projection Warnings Work in RBT Notes

Projection Warnings are visual alerts that appear in RBT notes when recording behaviors that fall outside their expected projection ranges.

Warning Display Rules

1. Maladaptive Behaviors (Yellow Warning)

   • Trigger: Recorded occurrence count is outside expected range
   • Range: Based on projection policy for the behavior
   • Color: Yellow (warning)
   • Message: “This value is outside the expected range [min - max]”

2. Replacement Behaviors - Below Range (Yellow Warning)

   • Trigger: Recorded value is below expected minimum
   • Range: Based on projection policy for the replacement
   • Color: Yellow (warning)
   • Message: “This value is below the expected range [min - max]”

3. Replacement Behaviors - Above Range (Green Success)

   • Trigger: Recorded value is above expected maximum
   • Range: Based on projection policy for the replacement
   • Color: Green (success)
   • Message: “Great! This value exceeds the expected range [min - max]”
   • Rationale: Replacements exceeding projections is positive progress

When Warnings DON’T Appear

• ✅ Location has warnings_enabled: false
• ✅ Behavior has no projection policy configured
• ✅ Session date is outside projection policy date range
• ✅ Value is within expected range
• ✅ No occurrence value entered yet

Steps to See Projection Warnings

Prerequisites:

• Patient’s location must have warnings_enabled: true
• Behavior must have a projection policy configured
• Session date must fall within projection policy date range

Steps:

1. Navigate to RBT Note

   • Go to Notes
   • Click “Create RBT Note” or edit existing note
   • Select a patient from a location with warnings enabled

2. Fill Session Information

   • Select session date
   • Enter session duration
   • Save basic information

3. Add Behavior Data

   • Scroll to Maladaptives or Replacements section
   • Enter occurrence count or rate/percentage

4. Watch for Warnings

   • Warning appears immediately after entering value
   • Shows expected range for context
   • Updates dynamically as you change the value

5. Understanding the Warning

   • Yellow Warning (Maladaptive): Value is outside expected range
   • Yellow Warning (Replacement below): Value is below expected minimum
   • Green Success (Replacement above): Value exceeds expected maximum (good!)

6. Proceeding with Entry

   • Warnings are informational only
   • You can still save the note
   • Consider reviewing with supervisor if uncertain

How Report Access Control Works

Report Access Control allows administrators to control whether users can access the “Out of Projection” report on a per-location basis.

Location Determination

Which location is checked?

• Not the user’s assigned location
• Not the patient’s location
• Current selected location via location selector in navigation bar

Why? Reports aggregate data across multiple patients, so current context location is authoritative.

Steps to Access the Out of Projection Report

Prerequisites:

• You have view_projection_report permission
• Your current location has reports_enabled: true

Steps:

1. Select Location

   • Use the location selector in the navigation bar
   • Choose a location with reports enabled

2. Navigate to Reports

   • Click “Reports” in main menu
   • Click “Reports Access”

3. Go to Clinical Tab

   • Click “Clinical” tab
   • Look for “Out of Projection” card

4. Open Report

   • Click the “Out of Projection” card
   • Report loads with data for selected location

---

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

General Settings Questions

Q: What if I don’t specify settings when creating a location?

A: Both settings default to enabled (true).

Q: Can I set different settings for different locations?

A: Yes - each location has independent settings.

Q: Can regular users change these settings?

A: No - only users with manage_locations permission can modify settings.

Q: Will disabling features delete existing data?

A: No - data is preserved. Only visibility/access changes.

Projection Warnings Questions

Q: What if I disable warnings for a location?

A:

• ✅ RBT staff at that location will no longer see projection warning alerts when recording behaviors
• ✅ Data entry continues normally - staff can still enter any values
• ✅ Projection calculations still happen in the background
• ✅ Reports are NOT affected - if reports are enabled, they still work
• ✅ Other locations are NOT affected - their settings remain unchanged

Use Case: Location wants to remove visual clutter or has different clinical protocols.

Q: What if I enter an out-of-range value with warnings enabled?

A:

• ✅ Yellow or green alert appears below the input field
• ✅ Alert shows the expected range for context
• ✅ You can still save the note - warnings are not blocking
• ✅ Data is recorded accurately
• ✅ BCBA/Supervisor can review flagged values later

Q: What if I enter an out-of-range value with warnings disabled?

A:

• ✅ No alert appears
• ✅ Data entry looks exactly the same as in-range values
• ✅ Data is still recorded accurately
• ✅ Out of Projection reports (if enabled) still track the deviation

Q: What if a behavior has no projection policy?

A:

• ✅ No warning can appear (no expected range to compare against)
• ✅ Data entry works normally
• ✅ Location setting doesn’t matter in this case

Q: What if the session date is outside the projection policy date range?

A:

• ✅ No warning appears (projection policy not active)
• ✅ Data entry works normally
• ✅ System cannot calculate expected range for dates outside policy coverage

Q: What if I change the value from out-of-range to in-range?

A:

• ✅ Warning disappears immediately
• ✅ No need to refresh or re-save
• ✅ Angular’s reactive rendering updates in real-time

Q: Do settings apply to existing notes?

A: No - settings only affect new note creation. Existing notes are not modified.

Q: What if warnings were disabled but then re-enabled?

A:

• ✅ Warnings start appearing immediately for new note entries
• ✅ Existing notes are not modified
• ✅ Historical data remains intact

Report Access Questions

Q: What if I disable reports for a location?

A:

• ✅ Users at that location will not see the “Out of Projection” report card
• ✅ Direct URL access to the report is blocked (403 error)
• ✅ Warnings are NOT affected - if warnings are enabled, they still show in notes
• ✅ Other locations are NOT affected - their settings remain unchanged
• ✅ Admin View bypasses this - admins in Admin View mode can still access

Use Case: Location doesn’t use projection-based reporting or has privacy concerns.

Q: What if I don’t have permission but location has reports enabled?

A:

• ❌ Access Denied
• ✅ Report card does NOT appear in reports list
• ✅ Direct URL access returns permission error
• ✅ Location setting is irrelevant if you lack permission

Q: What if I have permission but location has reports disabled?

A:

• ❌ Access Denied
• ✅ Report card does NOT appear in reports list
• ✅ Direct URL access returns 403 Forbidden
• ✅ Error message: “Projection reports are disabled for this location”

Q: What if I switch locations while viewing the report?

A:

• ✅ Report page remains open (already loaded)
• ✅ If you refresh the page → 403 Forbidden
• ✅ If you navigate away and return → card is hidden

Recommendation: Close and reopen report after switching locations

Q: Can I export data if reports are disabled?

A:

• ❌ No - if you can’t access the report, you can’t export its data
• ✅ Other reports (if enabled) can still be exported
• ✅ Raw data is still in the system (just not accessible via this report)

Q: What happens to historical data when reports are disabled?

A:

• ✅ No data loss - all historical projection data remains in database
• ✅ Data is just not accessible via the report interface
• ✅ Re-enabling reports immediately restores access to historical data

Multi-Location & Impersonation Questions

Q: What if I’m an RBT at multiple locations with different settings?

Scenario:

• User has access to Location A (warnings: ON, reports: ON)
• User has access to Location B (warnings: OFF, reports: OFF)

Behavior:

• In RBT Notes: Warnings show/hide based on the patient’s location, not the user’s current location

  • Patient from Location A → warnings show
  • Patient from Location B → warnings don’t show

• In Reports: Report visibility is based on the user’s current selected location

  • User selects Location A → report is visible
  • User switches to Location B → report disappears

Q: What if I have access to multiple locations with different settings?

Scenario:

• Location A: reports_enabled: true
• Location B: reports_enabled: false
• Location C: reports_enabled: true

Behavior:

• Report card is visible (at least one location has reports enabled)
• Clicking the card: Opens report for current selected location
  • If Location A selected → report works
  • If Location B selected → 403 Forbidden
  • If Location C selected → report works

Q: What if I’m in Admin View mode?

A:

• ✅ Report Access: Admin View always allows report access regardless of location settings
• ✅ Warnings: Admin View does not affect warnings - they respect the patient’s location settings
• ✅ Use Case: Admins need full visibility across all locations

Q: What if I’m impersonating a user?

A:

• ✅ Access control uses impersonated user’s permissions
• ✅ Location settings checked based on impersonated user’s selected location
• ✅ Admin View status of impersonated user is considered

Example:

• You (admin) impersonate RBT user
• RBT is in Location B (reports disabled)
• You cannot access reports (same restrictions as RBT)

Why: Impersonation simulates the exact user experience

Special Cases

Q: What if I disable both warnings and reports?

A:

• ✅ Projection features are completely disabled for that location
• ✅ No warnings show in RBT notes
• ✅ No report access for that location
• ✅ Projection calculations are not performed (saves processing)
• ✅ Other locations continue using the features normally

Use Case: Location doesn’t use projection methodology at all.

Q: What happens to existing locations when this feature is enabled?

A:

• ✅ All existing locations automatically get default settings (both enabled)
• ✅ No workflow disruption - everything works as before
• ✅ No manual migration needed - system handles it automatically
• ✅ Admins can then customize settings per location as needed

Q: What if a location has no settings configured?

A: This cannot happen because:

• Database enforces NOT NULL constraint
• Migration backfilled all existing locations
• New locations get defaults automatically
• API validation requires both settings when saving

However, for backward compatibility, the code handles undefined/null gracefully:

• Missing settings default to true (enabled)
• Ensures feature works even if data issues occur

Q: What if I change settings for a location with active notes/reports?

A:

• ✅ Changes apply immediately - no need to recreate notes or reports
• ✅ Existing RBT notes are not modified - only future note creation is affected
• ✅ Report access updates in real-time when user switches locations
• ✅ No data loss - only visibility/access changes

Q: Can I bulk update settings for multiple locations?

A: Currently: No bulk update UI exists

Workaround: Update each location individually via the location form

Q: What if I bookmark the report URL?

A:

• ✅ Bookmark works only if you still have access when you use it
• ✅ Access is re-checked every time you visit the URL
• ✅ If location disables reports later → bookmark returns 403 Forbidden

Bookmarks are not a backdoor - access control is enforced on every request

Q: Do warnings still work when reports are disabled?

A:

• ✅ Yes - warnings and reports are independent settings
• ✅ You can disable reports while keeping warnings enabled
• ✅ Projection calculations still happen (for warnings)

---

7. Troubleshooting

Issue: Changes don’t seem to take effect

Check:

1. Did you click Save after making changes?
2. Are you looking at the correct location?
3. For reports: Is the correct location selected in the location selector?
4. For warnings: Is the patient from the correct location?

Solution: Refresh the page and verify settings were saved

---

Issue: I can’t see the Out of Projection Settings section

Possible Causes:

1. You don’t have manage_locations permission
2. You’re not in edit mode
3. Browser cache issue

Solution:

1. Verify you have admin/super admin role
2. Make sure you clicked “Edit” on the location
3. Clear browser cache and reload

---

Issue: Settings keep reverting to defaults

Possible Cause: Browser validation or network error

Solution:

1. Check browser console for JavaScript errors
2. Verify network connection
3. Try using a different browser
4. Contact support if issue persists

---

Issue: Warnings don’t appear for out-of-range values

Check:

1. Is the patient’s location set to warnings_enabled: true?
2. Does the behavior have a projection policy configured?
3. Is the session date within the projection policy date range?
4. Is the value truly outside the range (not at the boundary)?

Solution: Verify location settings and projection policy configuration

---

Issue: Warnings appear when I don’t expect them

Possible Causes:

1. Projection policy date range includes this session date
2. Expected range is narrower than you anticipated
3. Location has warnings enabled

Solution: Review projection policy configuration or disable warnings for location

---

Issue: Report card doesn’t appear in the list

Check:

1. Do you have view_projection_report permission?
2. Is your current location’s reports_enabled setting true?
3. Are you looking in the Clinical tab (not other tabs)?

Solution: Verify permission and location setting via admin

---

Issue: I get 403 when clicking the report

Possible Causes:

1. Location setting changed since you loaded the page
2. You switched locations after page loaded
3. Impersonation token is outdated

Solution:

1. Refresh the reports access page
2. Verify current location has reports enabled
3. If impersonating, re-impersonate to refresh token

---

Issue: Report works for some locations but not others

This is expected behavior:

• Each location has independent settings
• Some locations may have reports enabled, others disabled

Solution: Switch to a location with reports enabled using location selector

---

Issue: Admin View doesn’t bypass location restriction

Check:

1. Is Admin View actually enabled? (check UI indicator)
2. Do you have the necessary permission to enable Admin View?
3. Does your role allow Admin View mode?

Solution: Verify Admin View is active and your role supports it

---