BIP Import Data

Note: This document reflects the current frontend workflow and backend behavior validated in May 2026.

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

This feature lets staff import weekly BIP data from an Excel file instead of typing it manually one value at a time. It helps teams load large amounts of plan data faster while still forcing a review of unmatched plan names and conflicting values before anything is saved.

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

• Users with manage_bips and access to the patient: Can load an Excel file, review matching results, resolve conflicts, and approve the final import.
• Current configured roles that typically qualify: Superadmin, Admin, Owner, Manager, and BCBA, as long as they also have access to the patient record. Users without patient access can still be blocked by the backend.
• Clinical supervisors or other staff responsible for BIP maintenance: Can use this workflow when they need to update weekly data for existing plans in the BIP.

3. Business Rules & Enforcements

• Rule 1: The feature is split into five import areas: Maladaptives, Replacements, Caregiver, Teacher, and RBT.
• Rule 2: Each import is section-specific. A file loaded under one section only applies to that section’s plan category.
• Rule 3: The user must choose a file in the import modal and click Process Data before the system starts validation.
• Rule 4: Current modal validation accepts only .xlsx files for preview/process. If the file is empty, the import is blocked.
• Rule 5: The file picker UI suggests .xlsx, .xls, and .xlsm, but the current frontend parser enforces .xlsx only.
• Rule 6: There is currently no explicit frontend size gate in the modal; file-size rejection is backend-driven when applicable.
• Rule 7: The import uses a weekly workbook structure across all sections. The main weekly data sheet is weeks, column A contains the plan name, row 1 contains weekly dates, and later rows contain weekly values.
• Rule 8: The backend reads the weeks sheet as the primary source for weekly values, not whichever sheet happens to be open in Excel.
• Rule 9: The category is not read from the Excel file. It is sent separately by the application based on the section the user chose.
• Rule 10: For the weekly sheet, the system reads the first column as the plan name and interprets the remaining valid date columns as weekly values.
• Rule 11: The import modal supports a Match mode selector (Normalized or Exact) and sends that mode to backend check validation.
• Rule 12: The system automatically tries to match each imported plan name to an existing plan in the same BIP section.
• Rule 13: Matching in Normalized mode ignores case, accents, spaces, and punctuation differences when comparing plan names.
• Rule 14: If any imported plan names do not match automatically, the user must manually map each one to an existing plan before moving forward.
• Rule 15: Plans already matched automatically are removed from the manual selection list so the same plan is not assigned twice during the unmatched-name step.
• Rule 16: If conflicts are found between the file and existing data, the user must choose Existing or New for every conflict before continuing.
• Rule 17: If there are no conflicts, the section moves directly to the final approval stage.
• Rule 18: Blank Excel cells do not clear existing stored values. In the final import, blank cells are ignored.
• Rule 19: The final confirmation warns that the import will overwrite existing information, but the overwrite is limited to the matched plan and the resolved week being imported.
• Rule 20: If the imported week does not already exist, the system can create a new weekly report automatically for that matched plan and week.
• Rule 21: The system blocks the final import if any selected plan does not belong to the available plans for that BIP section.
• Rule 22: If the same plan and week appear more than once in the prepared dataset, the system consolidates them before saving. Conflict-reviewed values take priority over regular imported values.
• Rule 23: Imports are currently not blocked by backend plan status, so inactive or discontinued plans may still be updated if they belong to the same BIP and category.
• Rule 24: The user can clear a section at any time, which removes the imported preview, matching work, conflict decisions, and confirmation state for that section.
• Rule 25: The same selected file is preserved from preview to processing and final import for each section, unless the system rebuilds the file after conflict decisions.
• Rule 26: Request scope must include exactly one of bip_id or patient_id; this is an enforced backend contract.
• Rule 27: Structural validations specific to Maladaptive import files are backend-owned. Frontend does not authoritatively validate Maladaptive business structure.

4. UI Placement

1. Patient Record > BIP: Open the patient’s Behavior Intervention Plan.
2. Import Data tab: Open the Import Data tab inside the tabbed BIP experience.
3. Section Import Button: In the desired section, click Import Data.

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

Scenario A: Import data for one section when the file matches cleanly

1. Open the patient’s BIP.
2. Open the Import Data tab.
3. Go to the section you want to update, such as Maladaptives, Replacements, Caregiver, Teacher, or RBT.
4. Click Import Data.
5. In the modal, choose the desired Match mode (Normalized by default).
6. Click Load Data and choose an Excel file (.xlsx required by current frontend validation).
7. Review the preview shown in the modal.
8. Click Process Data.
9. If all plan names match and no conflicts are found, review the confirmation notice.
10. Click Approve and Save.

Scenario A.1: When the section is Maladaptives

1. Follow the same flow as Scenario A.
2. Use the backend-approved Maladaptive template/format.
3. For new Maladaptive creations, the file must include all required additional metadata fields:

• Topographical Definition
• Setting Event/Antecedent
• Hypothesized Functions

4. If any required Maladaptive metadata is missing, the row is marked as blocking and cannot continue to conflicts/import until corrected.
5. If a missing-required-fields case reaches final import, backend can still cancel the import as incomplete.
6. Frontend-only checks (file selected, non-empty, extension) are not sufficient to guarantee Maladaptive acceptance.

Scenario B: Resolve imported names that do not match existing plans

1. Load the file and click Process Data.
2. Review the list of rows shown in the unmatched-name table.
3. For each unmatched row, choose the correct existing plan from the dropdown.
4. Repeat until every unmatched row has a selected plan.
5. Click Continue.
6. The system will then move to the conflict review step.

Scenario C: Resolve value conflicts before saving

1. Review the conflict table for the section.
2. For each row, compare the Existing value and the New value from the file.
3. Choose which value should win for that row.
4. If the same choice should be used everywhere, use Apply Existing to all or Apply New to all.
5. Click Continue after every conflict has a selection.
6. Review the confirmation notice.
7. Click Approve and Save.

Scenario D: Discard the current import for one section

1. In the relevant section, click Clear.
2. The current preview, matching results, conflict review state, and final confirmation for that section are removed.
3. Start over by clicking Import Data again if needed.

Scenario E: Import a new week that does not yet exist

1. Open the patient’s BIP and go to Import Data.
2. Import a file that contains a valid plan match and a valid week that is not already stored for that plan.
3. Complete any unmatched-name mapping or conflict review that appears.
4. Click Approve and Save.
5. The backend can create the missing weekly report automatically for that plan and week.

6. Upload Considerations (May 2026)

• The upload input allows selecting .xlsx, .xls, or .xlsm, but the current modal parser validates .xlsx only.
• The modal validates that a file is selected and non-empty before processing.
• Frontend preview and process should use the weeks tab as the primary weekly sheet, because that is the workbook tab the backend expects for weekly values.
• Section category is always determined by UI context, not by workbook content.
• When the user clicks Process Data or Approve and Save, the system uses the selected section and patient/BIP context to validate and apply the import correctly.
• If something fails, the user sees a clear message in that section indicating where it failed (initial validation, conflict review, or final save) so they can take action.

6.1 Maladaptive Required Fields (Business View)

For Maladaptive imports, backend enforces additional required metadata when a row needs to be created or completed as a Maladaptive plan.

Mandatory additional fields:

• Topographical Definition
• Setting Event/Antecedent
• Hypothesized Functions

How the user experiences this in the workflow:

• During Process Data, rows with missing required Maladaptive metadata appear as blocking rows and list the missing field names.
• While blocking rows exist, the section cannot move forward to conflict resolution/import for those rows.
• If unresolved missing required fields are still present at final save, backend may reject the import as incomplete.

6.2 Ideal Excel Workbook Example (Recommended Business Template)

The safest workbook structure is a multi-sheet Excel file where each required data type has a clear place. This is the format the current backend is configured to understand.

Recommended workbook tabs:

• weeks
• baselines
• Topographical Definition
• Setting Event Antecedent
• Hypothesized Functions

How each tab should look:

Tab 1: weeks This is the main sheet used to import weekly values.

Example:

A	B	C	D	E	F	G	H	I
Plan	Baseline Date	Baseline Level	Topographical Definition	Setting Event/Antecedent	Hypothesized Functions	2026-01-03	2026-01-10	2026-01-17
Following instructions						95	97	90
Compliance with activities schedule						81	82	80

Business meaning:

• Column A identifies the plan name.
• Date columns begin in column G.
• Columns B to F may be present for readability or fallback support, but the ideal Maladaptive template should rely on the dedicated supporting tabs below.

Tab 2: baselines This tab provides baseline date and baseline level by plan name.

Example:

A	B	C	D
Plan	2024-04-21	2024-10-20	2025-01-05
Following instructions			84
Compliance with activities schedule	0

Business meaning:

• Column A is the plan name.
• The baseline date is taken from the header of the first baseline column that has a value for that plan.
• The baseline level is taken from the matching filled cell under that date.

Tab 3: Topographical Definition

Example:

A	B
Plan	Topographical Definition
Following instructions	Does not begin the requested activity within the expected time without repeated prompting.
Compliance with activities schedule	Fails to follow the sequence of scheduled activities without redirection.

Tab 4: Setting Event Antecedent

Example:

A	B
Plan	Setting Event/Antecedent
Following instructions	Non-preferred demand presented after access to a preferred activity ends.
Compliance with activities schedule	Visual schedule change or transition from a preferred task to a required task.

Tab 5: Hypothesized Functions

Example:

A	B
Plan	Hypothesized Functions
Following instructions	Escape
Compliance with activities schedule	Escape,Tangible/access

Business meaning for the three supporting tabs above:

• Column A must contain the same plan name used in weeks.
• Column B must contain the value to import for that field.
• The plan names must match the weeks tab closely enough for the system to relate them correctly.

Practical recommendation for owners and staff:

• If the file may create new Maladaptive plans, use all five tabs above.
• If the file will only update existing weekly values for already-created plans, the weeks tab is still the primary tab, but keeping the supporting tabs is the safest operational format.
• Do not rely on whichever sheet is open in Excel when saving. The workbook should explicitly contain a tab named weeks.

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

• Q: What happens if the user uploads .xls or .xlsm from the modal?
  • A: The picker allows selecting those files, but the current modal parser rejects non-.xlsx files.
• Q: What happens if the user uploads the wrong file type or an empty file?
  • A: The modal shows an error and the import does not continue.
• Q: Is file size limited in the frontend modal?
  • A: There is no explicit frontend size limit check in the current modal. Any enforced size policy is backend-driven.
• Q: Who validates the Maladaptive-specific file structure and rules?
  • A: Backend. Frontend does not implement full Maladaptive template/business validation.
• Q: Which additional fields are mandatory for Maladaptive creation/completion?
  • A: Topographical Definition, Setting Event/Antecedent, and Hypothesized Functions.
• Q: What happens if the Excel file contains blank weekly cells?
  • A: Those blank cells do not delete anything. They are ignored during the final import, so existing stored values remain unchanged.
• Q: What is the ideal workbook format for Maladaptive imports?
  • A: The recommended workbook contains weeks for weekly values, baselines for baseline date/level, and separate tabs named Topographical Definition, Setting Event Antecedent, and Hypothesized Functions for the required creation fields.
• Q: What happens if some plan names from the file do not match anything in the BIP?
  • A: The user must manually map every unmatched name to an existing plan before the workflow can continue.
• Q: What happens if no conflicts are found?
  • A: The section skips the conflict table and goes straight to the final approval step.
• Q: What exactly gets overwritten when the user saves?
  • A: The import updates only the matched plan and the specific resolved week being imported, not the whole patient or the whole category.
• Q: What happens if the imported week does not exist yet?
  • A: The backend can create that weekly report automatically if the plan is valid, the date is valid, and the imported value is not blank.
• Q: What happens if the user clicks Clear after working on an import?
  • A: The current section is reset and any unsaved review work for that section is lost.
• Q: What happens if the selected plan does not belong to the current BIP section?
  • A: The final import is blocked and nothing is saved for that section.
• Q: What happens if the matched plan is inactive or discontinued?
  • A: The current backend does not block the import for that reason alone.
• Q: Is there a full audit trail of the import session?
  • A: There is traceability for the weekly reports that were created or updated, but not a complete single audit event for the uploaded file, manual mappings, and conflict choices together.