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

Import Students and Note Fields

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

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.

Leftover CSV values (and any fields you add by hand) go in a table under ## Additional fields. Any ## … fields heading is read the same way (for example an older ## 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 additional 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 additional 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.