chapter-organizer/docs/instructions/student-notes-import.md

Import Students and Note Fields

Created: 2026-08-29
Last updated: 2026-08-29

Description: How /students/import creates students and merges leftover CSV columns into each student's markdown notes.

Where notes live

Each student has a system note titled #Student:{id}. It is edited on the student edit page and shown on student details. Those notes are hidden from the main Notes list.

Imported leftover values go in a table under ## Imported fields. Other markdown above or below that heading is left alone.

CSV format

Student Name,Grade,TSA year,State ID,Regional ID,National ID,Interview Time,Application,Club Permission Slip,Teacher Rec 1,Teacher Rec 2,Teacher Rec 3
"Last, First",6,1st,,,,3:20-3:35,x,x,Fuqua,Young,

• Roster (required): Student Name (Last, First or First Last), Grade, TSA year.
• Roster (optional): State ID, Regional ID, National ID.
• Every other column becomes a Field/Value row. Later files can add columns without a code change.
• A cell that is only x / X is stored as Yes. Blank stays blank.
• Rank columns 1–10, Officer, and TOTAL # OF EVENTS are ignored (use /students/event-ranking/import for rankings).

A notes-only file without Grade will not import. Put roster and leftover columns in the same CSV.

Merge rules

• New students are inserted. Existing first+last name matches are skipped for the roster (add-only).
• After students are saved, leftover columns are fuzzy-matched by name and merged into notes. Existing students still receive note updates.
• Incoming values win when a field already exists, including a blank cell that clears a previous value.
• New fields are appended. Fields not in this CSV stay. Blank cells are stored and re-imported as a no-op.
• Duplicate rows for the same student collapse into one note match; the last row wins for overlapping field names.
• Importing the same file twice adds no students and writes no note history.

Steps

1. Sign in as an Administrator.
2. Open Students and click Import, or go to /students/import. The arrow next to Import downloads a CSV template (roster columns, Students index columns, and any other imported fields already in notes). /import still opens this same student page.
3. Upload the student CSV.
4. Review new vs existing counts and leftover field names.
5. Save to Database.

Index columns

Chapter Settings → Student Index Columns lists which imported field names appear as extra columns on the Students index. The page also shows field names already present in student notes; click a chip to add or remove it from the list. Open Students again after saving; a restart is not required.