Preparing Your Patient Notes Data for Upload to Brim: Common Gotchas and How to Fix Them

Brim expects a very specific CSV structure. Clinical notes data is especially tricky because the text of notes often contains commas, line breaks, and quotation marks — the same characters that give a CSV file its structure. This guide walks through the most common issues and how to resolve them before uploading.

Here's what Brim expects:

The data CSV has one document per row, and should be formatted as described below. Note that the field name must be in the CSV header.

Each row must have a unique pair of NOTE_ID and PERSON_ID fields in order to be successfully imported.

Note: The alphanumeric identifier for the Patient may be specified using either PERSON_ID or PATIENT_ID as the header. Both formats are accepted and treated equivalently. The alphanumeric identifier for Note may be specified using either NOTE_ID or DOCUMENT_ID. Both formats are accepted and treated equivalently.

Common Gotchas

Here are some common reasons you may be having issues with your file:

Gotcha 1: Opening the CSV in Excel — and then saving it. When Excel opens a CSV and you save it, Excel silently:

• Reformats dates (2023-01-15 09:30:00 → 1/15/2023 or worse) and strips time components from timestamps
• Truncates note text longer than 32,767 characters with no warning
• Adds or removes quotes in ways that break field boundaries
• Converts numeric NOTE_IDs or PERSON_IDs to scientific notation (e.g., 1234567890 → 1.23457E+09)

Fix: Do not open your final CSV in Excel. Use Notepad/TextEdit in plain text mode. If you must use Excel, export to CSV only from its original source — never re-save a CSV that Excel has opened.

Gotcha 2: Line breaks inside note text. Clinical notes almost always have line breaks — "Chief Complaint:" on one line, the actual complaint on the next. In a CSV, an unquoted line break is read as a new row, so one note becomes 10 rows and the entire file falls apart. Fix: The note text fields must be wrapped in double quotes AND any internal line breaks must be preserved inside those quotes.

Gotcha 3: Commas inside note text or titles. A note saying "Patient has hypertension, diabetes, and hyperlipidemia" contains commas. If the field isn't properly wrapped in double quotes, Brim reads those commas as column separators and the row breaks. Fix: Wrap all NOTE_TEXT and NOTE_TITLE fields in double quotes.

Gotcha 4: Quotation marks inside note text. A note might contain a quote: Patient reported "no pain". In Brim's CSV format, that quote needs to be doubled: Patient reported ""no pain"". A single unescaped quote inside a quoted field will corrupt everything from that point forward in the file. Fix: Find-and-replace all " with "" inside text fields before wrapping them in outer quotes.

Gotcha 5: Wrong or mismatched column headers. Brim's column names must be exact. These will fail: Note ID, NoteID, text. Fix: Double-check headers match exactly: NOTE_ID, PERSON_ID, NOTE_DATETIME, NOTE_TEXT, NOTE_TITLE.

Gotcha 6: Duplicate NOTE_ID + PERSON_ID pairs. If the same note appears twice for the same patient (e.g., from a data export that joined tables incorrectly), Brim will reject those rows. Fix: Before uploading, check for duplicates.

Gotcha 7: File encoding issues. Excel on Windows saves CSVs in Windows-1252 encoding by default, not UTF-8. Clinical notes often contain smart quotes, em dashes, and other characters that get garbled when the encoding is wrong. You might see characters like “ instead of ". Fix: When saving from Excel, choose "CSV UTF-8 (Comma delimited)" from the Save As format dropdown (not just "CSV").

Gotcha 8: Multiple Notes Concatenated in One Row. If your file has multiple notes combined into a single row, Brim will treat the entire contents as one note rather than separate documents. For example, you might expect a patient to have 10 individual documents in Brim, but instead see only one  this means all of that patient's notes were concatenated into a single row before upload.

Important: Brim will not show an error. The file will upload successfully, making this easy to miss.

Fix: This cannot be corrected by reformatting the file. Go back to your data source and re-export, ensuring the file is structured with one note per row before uploading.

Gotcha 9: Empty values in required fields. If your file contains one or more rows with an empty value in a required column, the file will fail to upload. For example, a row without a value in NOTE_DATETIME will cause the upload to fail. Fix: Ensure every required column has a value for each row, then re-upload.

Gotcha 10: Empty NOTE_TEXT fields are silently skipped. If a row has no value in the NOTE_TEXT column, Brim will not show an error — the file will upload successfully, but that row will be quietly dropped and the note will not appear in Brim. You won't know a row was skipped unless you compare your expected document count against what actually loaded. Fix: Before uploading, filter your data to ensure every row has a value in NOTE_TEXT. If some notes genuinely have no text, go back to your data source and investigate before uploading.

Before You Upload — Common Things to Check For:

• File is saved as .csv, not .xlsx
• Headers are exactly NOTE_ID, PERSON_ID, NOTE_DATETIME, NOTE_TEXT, NOTE_TITLE
• NOTE_DATETIME is YYYY-MM-DD HH:MM:SS  .Other formats that are  also accepted areMM/DD/YYYY HH:MM:SS   and MM/DD/YYYY . When in doubt, use the recommended format to avoid ambiguity.
• Note text fields are wrapped in double quotes.
• Quotation marks inside note text are doubled ("")
• No line breaks outside of quoted fields
• No duplicate NOTE_ID + PERSON_ID combinations
• File saved as UTF-8 encoding

Brim Error Message Decoder