BIP Import Data

Note: This document reflects the current frontend workflow and the backend clarifications received on March 30, 2026. Supporting backend notes are summarized in the companion file bip-import-data-follow-up-questions.md.

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: The official supported file formats are .xlsx and .xls, and the file cannot exceed 10 MB.
• Rule 5: The import uses a single weekly template across all sections: column A is the plan name, row 1 from column B onward contains dates, and later rows contain weekly values.
• Rule 6: The backend reads only the active sheet of the Excel file.
• Rule 7: The category is not read from the Excel file. It is sent separately by the application based on the section the user chose.
• Rule 8: The system reads the first column as the plan name and interprets the remaining valid date columns as weekly values.
• Rule 9: The system automatically tries to match each imported plan name to an existing plan in the same BIP section.
• Rule 10: Matching ignores case, accents, spaces, and punctuation differences when comparing plan names.
• Rule 11: If any imported plan names do not match automatically, the user must manually map each one to an existing plan before moving forward.
• Rule 12: 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 13: If conflicts are found between the file and existing data, the user must choose Existing or New for every conflict before continuing.
• Rule 14: If there are no conflicts, the section moves directly to the final approval stage.
• Rule 15: Blank Excel cells do not clear existing stored values. In the final import, blank cells are ignored.
• Rule 16: 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 17: If the imported week does not already exist, the system can create a new weekly report automatically for that matched plan and week.
• Rule 18: The system blocks the final import if any selected plan does not belong to the available plans for that BIP section.
• Rule 19: 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 20: 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 21: The user can clear a section at any time, which removes the imported preview, matching work, conflict decisions, and confirmation state for that section.

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, click Load Data and choose a supported Excel file.
6. Review the preview shown in the modal.
7. Click Process Data.
8. If all plan names match and no conflicts are found, review the confirmation notice.
9. Click Approve and Save.

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. What happens if…? (Edge Cases / FAQ)

• 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: 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 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.