Roster import

The roster importer is the path for getting a roster into Lyra when you’ve already exported it from your SIS. This page covers running one: preparing your files, uploading them, and reading what came back.

The column-by-column contract for the files themselves — what each column accepts, what a blank means, and every error the importer can report — is in Roster import formats. For where your roster should come from in the first place (your SIS, not your old ILS), see Migrating patrons.

What the importer is

A single upload that carries as many files as you have, each holding one of five things: students, faculty, homerooms, homeroom teachers, or community patrons. Every kind is independently optional, and whatever you upload is processed together as one import. A faculty-only refresh is a one-file upload; a start-of-year full sync usually covers the first four.

You drop the files on one target and Lyra works out what each one holds, from its columns and its name. It says so on every file before anything is imported, and you can correct it there — see What Lyra reads each file as.

Files may be .csv, .xlsx or .xls, mixed freely in one import. A workbook with a sheet per kind counts as several files: each sheet is read on its own.

Nothing stops you splitting one kind across several files. Students exported per grade import as one set of students.

The importer is generic: it doesn’t care which SIS produced the files, and it recognizes column headings in several vendors’ vocabularies as well as its own. A file in anything but Lyra’s own column names goes through a mapping step where you confirm what each column holds.

Getting to the importer

Go to School level navigation path: Roster then Imports, then select button: Import roster. Before the first import it sits in the panel headed card: Import your roster. that stands in for the table; after that it is in the page header. Importing is a roster edit, so it’s admin-only; Standard and Limited staff can view the imports history but don’t see the button: Import roster button in either place.

Roster imports are school-scoped. A single import populates the patron and homeroom records that all libraries in your school share.

Choosing which files to upload

Pick whichever combination fits the job:

Start-of-year full sync. All four files. Lyra reconciles every record in your school against what you uploaded.
Faculty refresh. Just Faculty. Updates and (in Replace mode) prunes teachers without touching students or homerooms.
Mid-year new students. Just Students in Update mode. Adds the new patrons, leaves everything else alone.
New homeroom plus its teacher. Homerooms + Homeroom teachers. The new homeroom is created; the new teacher assignment is attached.
Volunteers before the book fair. Just Community. Adds parent volunteers, substitutes or anyone else who borrows without being on your roster, as community patrons, each with an optional affiliation saying who they are to the school.

Start from a blank template if you’ve never run the importer:

roster-templates.xlsxEvery roster template, one sheet each. Fill in what you need — a blank sheet is ignored.

Or one template at a time, as a CSV:

Each sheet is the exact header row Lyra expects and nothing else. Fill in the sheets you need and leave the rest blank; an untouched sheet is ignored rather than read as an empty file, so it removes nothing even in Replace mode. The column-by-column contract for each is in Roster import formats.

You don’t have to rename your SIS’s columns to match. Upload the export as it is and pick what each column holds in the mapping step; Lyra fills in what it can from the headings it recognizes, listed in Column names Lyra recognizes.

For a filled-in example, download the sample roster; its sample-students.csv shows real-looking rows, including guardian_emails for students who have no email of their own.

Preparing your files

Reconstructing homerooms from your SIS

Most SISes don’t store homerooms the way Lyra does, so turning your export into the two homeroom files is usually the fiddliest part of preparing an import. Lyra carries a homeroom as its own object (a stable identifier, a readable name, and one or more teachers), and each student points at a homeroom — not directly at a teacher — through homeroom_identifier. So you need to end up with, for each student, the identifier of the homeroom they belong to, and separately, for each homeroom, which teacher or teachers lead it.

How you get there depends on where your SIS keeps the link:

A homeroom-teacher value sits on the student record. You’re close: use that teacher’s stable identifier as the basis for the homeroom files. Build one homeroom per distinct teacher, give it a stable identifier you choose and a readable name, and link the teacher to it in the Homeroom teachers template.
Homeroom is only a class or section. Derive the mapping from enrollment data instead. Pull a class roster filtered to your homeroom classes, one row per student–teacher pairing, and join it back to your students by identifier. This is the longer path, and it’s where most of the time goes.

If your school is part of a diocese or district on a shared SIS tenant, confirm you’re exporting your own school’s records (using the per-school login, not a district gateway) so you don’t pull the whole district’s roster.

Filling in class year

Lyra stores class_year as the four-digit graduation year and works out the current grade from it, so grades roll over on their own each year. If your SIS export has graduation year populated, use it as-is.

It’s often empty in K–8 schools, which don’t think about graduation years until students are high-school-bound. If the export has each student’s current grade instead, map that column to Grade (sets class year) in the mapping step and the import works out the class year from your school calendar. Otherwise derive it with the formula in Class year derivation. It’s spreadsheet-friendly: build it once in a class_year column on your students file and fill it down.

Flattening parent emails

Most SISes give each parent or guardian their own email column (Parent 1, Parent 2, and so on). Lyra wants them joined with semicolons in one guardian_emails column. In Excel, =TEXTJOIN(";", TRUE, …) across the parent columns drops blanks for you, so a student with one parent on file gets a clean single value. Lyra lowercases each address and drops empties on parse, so you don’t need to be precious about casing.

Saving as CSV

If you do export to CSV — Excel: File → Save As → CSV UTF-8 (Comma delimited) (.csv); Google Sheets: File → Download → Comma-separated values (.csv), one sheet at a time — two Excel habits are worth heading off:

Accented characters. Excel on Windows can misread names with tildes, cedillas, or umlauts when you double-click a UTF-8 CSV. Open Excel first, then Data → From Text/CSV, and select UTF-8 explicitly in the import wizard. The file itself is fine; it’s Excel’s auto-detection that fails.
Numeric identifiers. If your identifiers are integers, Excel will render 12345 as 1.2345E+04, drop leading zeros, or change the column type on save. Format any identifier column as Text before saving, or edit the file in a plain text editor.

Both go away if you upload the workbook instead: a spreadsheet carries no encoding to guess at, and Lyra reads a numeric cell as the digits it shows. The same applies to a roster you exported from Lyra to edit in bulk — upload the .xlsx, and a 0001 PIN survives the trip.

The importer works out a CSV’s encoding from the file and removes a byte-order mark, so any of the usual saves works; see value formats. Imports troubleshooting has the full list of spreadsheet gotchas.

What Lyra reads each file as

Every file you drop gets a row in the dialog naming what Lyra decided it holds. The decision comes from the file’s columns first and its name second — an honorific column makes a file Faculty, a class_year column makes it Students, an affiliation column makes it Community, and homerooms.csv settles a file that could be either. For a sheet of a multi-sheet workbook it is the sheet’s name that counts, so tabs named Students and Faculty do the same work a filename would.

One case cannot be decided from columns alone. A file of identifiers, names and emails is a valid students, faculty and community file, spelled identically. Lyra goes by the filename — volunteers.csv reads as community — and falls back to students. That is why the decision is shown rather than applied silently: if a row says the wrong thing, change it there before importing. The menu offers every kind; one the file’s columns don’t fit sends the file to the mapping step, which says what that kind still needs. Changing the kind clears any mapping you already confirmed for the file.

A file that matches no template at all isn’t refused. It says message: Columns to map on its row, and you map its columns like any other.

Mapping a file’s columns

A file imports without this step only when every column heading in it is one of Lyra’s own column names for the kind it’s read as, and it has what that kind needs (see What a file must carry). A filled-in starter template qualifies, and so does a file Lyra exported. Every other file says message: Columns to map on its row, including a OneRoster or Clever export whose headings Lyra already recognizes, so you see what Lyra decided before it changes your roster. In a workbook, each sheet is mapped on its own.

When you select the dialog’s import button, Lyra opens a dialog: Map Columns step for each file still to map, one after another, with a count such as message: 1 of 3 to map above the file name. button: Next moves on to the next file. On the last one the button is the import button again, and selecting it starts the import. button: Back returns you to the file list without importing, and keeps the mappings you already confirmed.

To map a file before you import, select button: Map columns on its row. That opens the step for that file alone, and button: Done takes you back to the list. The row then says message: Columns mapped, with button: Edit to reopen it.

The step lists each column in your file with its first value as a sample, and a menu beside it for the Lyra column it holds. Lyra fills these in for you from the headings it recognizes and the ones an SIS export commonly uses, such as Home_Room for a student’s homeroom or Section # for a homeroom’s identifier; Column names Lyra recognizes has the detail. Anything it can’t place starts as setting: Don't import, and a column left that way isn’t imported. Check each row, and change the ones Lyra got wrong.

Each Lyra column goes to one file column. Pick a Lyra column another column already has, and it moves. The column it left says so, for example message: Email moved to Student Email.
The kind’s needs come first. Until the file has the columns its kind needs, a line above the table says what’s missing, such as message: Homerooms needs an Identifier column, and a Name or Grade column., and the button stays unavailable.
field: Reading as changes the kind. Every kind is offered. Lyra keeps the choices that still fit the new kind and guesses the rest again.

Two Lyra columns are offered only here. Full name (Last, First) reads a column of names written Smith, Mary Ann, on Students, Faculty and Community files. Grade (sets class year) reads each student’s current grade and turns it into a class year. Columns the mapping step adds covers how each is read.

Mappings aren’t saved between imports: next term’s export from the same SIS starts from Lyra’s guesses again.

Replace vs. Update

You choose setting: Replace or setting: Update under field: Import mode in the upload dialog, and that one choice applies to the whole import, every file in it. (There’s no mixing modes file by file.) A school connected to a roster source has no Replace — see In a school connected to a roster source.

Update. Adds and updates the records in your files. Anything not listed is left alone, so an Update never removes anyone.
Replace. Each file is the full list of its own kind. Any existing record of that kind that is missing from the file is removed. Kinds you didn’t upload a file for are left alone: a Replace with only a Faculty file removes teachers who aren’t in it and touches no students, homerooms or community patrons.

A Replace import that isn’t a dry run asks first. The dialog shows message: Replace the roster? and names the kinds of record it will remove and the kinds it leaves alone. Select button: Replace roster to start the import, or button: Back to change the upload.

Homeroom removal in a Replace import

In a Replace import that includes a Homerooms file, any existing homeroom not listed in that file is removed.

A homeroom removal is blocked only when the same import still points at that homeroom:

message: Students still reference homeroom: your Students file includes a student whose homeroom_identifier is the homeroom you’re trying to remove. (The conflict: the homerooms file says “delete this homeroom,” but the students file says “a student belongs to it.”)
message: Homeroom teachers still reference homeroom: your Homeroom teachers file references the homeroom you’re trying to remove.

If neither file references the homeroom, it is removed, even if students or teachers are still attached to it in the system. Attachment in the database alone doesn’t block the removal; only a reference from the same upload does.

To remove a homeroom that currently has members: omit it from your Homerooms file and don’t reference it from your Students or Homeroom teachers files. You can reassign or drop those members in the same import if you want, but you’re not required to.

What happens to a removed homeroom’s members

Removing a homeroom does not delete its students or teachers. Instead:

Students who were in the removed homeroom have their homeroom cleared (set to none), unless your Students file reassigns them elsewhere. Each cleared student is reported as an status: Updated change showing the homeroom going from its old value to empty.
Teacher assignments for the removed homeroom are removed (the teachers themselves remain). Each removed assignment is reported as a status: Removed change on the button: Homeroom teachers tab, including when you didn’t upload a Homeroom teachers file at all.

These member changes are surfaced in the import results so the side effects of a homeroom removal are visible, not silent.

Patrons that can’t be removed (active loan)

In a Replace import, a patron slated for removal (absent from the file) cannot be removed while they have an active checkout. They are reported as an error, message: Has an active loan, and are kept.

If such a kept student was in a homeroom that the same import removed, their homeroom is still cleared, so the results show two entries for that student: the failed removal (message: Has an active loan) and the homeroom-cleared update.

In a school connected to a roster source

Once your school syncs its roster through OneRoster, your source decides who is on the roster and who they are, and Lyra keeps their library card. An import still works — it’s how you fill in what your source doesn’t carry, guardian emails most often — but it can only write what the sync leaves alone.

There’s no Replace. The upload dialog offers no choice under field: Import mode; it says message: Your roster source decides who the students and faculty are, so an import updates the ones it lists and adds none. Only barcodes, student PINs and guardian emails change. A community file adds and updates community patrons in full., and every import is an Update. Your source already removes whoever it stops listing.
A Students row updates only barcode, pin and guardian_emails. A Faculty row updates only barcode — the way to assign pre-printed staff cards, since OneRoster carries no barcodes.
Every other column is skipped. Names, emails, class year, homeroom and honorific are your source’s, and its next run would overwrite them. A row that changed one of them still applies the rest, flagged message: Skipped the columns your roster source owns. A row that changed nothing else is message: Only changes what your roster source owns.
A row your source doesn’t list is refused, as message: Not listed by your roster source. A row matches on its identifier, so give each one the sourcedId your source issues. A Faculty row naming a synced student is refused the same way, and so is the reverse: your source decides which a person is.
Homerooms and Homeroom teachers files change nothing. A homeroom’s name, grade and teachers are all your source’s, so every row of either is refused as message: Homerooms come from your roster source.
A Community file works in full. Someone your source doesn’t list, and never will, belongs in Lyra as a community patron, and nothing about one is your source’s. A Community file adds and updates them with every column, and the sync leaves them alone afterwards. Without Replace it removes no one, so take a community patron off by hand.

Dry run

The upload dialog has a setting: Dry run option. With it on, Lyra parses every file, runs all validation including cross-file references, and shows you what would happen (additions, updates, removals, errors) without actually changing any patrons or homerooms.

Dry runs are useful when you’ve reshaped your export pipeline, or before a Replace import where the deletions matter. Run a dry run, confirm the numbers, then select button: Run import in the dry-run banner on the completed dry run’s detail page and confirm with button: Run import; Lyra re-runs the import with the same files and takes you to the new import so you can watch it process. It’s a fresh run: the changes are recalculated against your current roster at that moment, so the results may differ from the preview if your data changed in between.

Results

Uploading queues the import and leaves you on the roster imports list, where the new run is listed with its status — the same thing a catalog import does. Processing is asynchronous and you’re free to navigate away; Lyra emails whoever started the run when it finishes.

The importer never reports a single rolled-up number. The detail page gives each record kind its own tab — button: Students, button: Faculty, button: Homerooms, button: Homeroom teachers, button: Community — and each tab carries how many of its records the import touched, its own counts of message: Added, message: Updated, message: Removed and message: Errors, and a list of those records. Every record is listed with a change type — status: Added, status: Updated, status: Unchanged, status: Removed, or status: Error — and each tab filters by change type and searches by name or identifier. A kind earns its tab by having results, not by having a file — so a Homeroom teachers tab appears when a removed homeroom takes its teacher assignments with it, even though you uploaded no such file. An import that moved one kind of record has no tab bar. The import detail page and the completion email both show these.

status: Added — a new record was created.
status: Updated — an existing record changed. Updated rows expand to a field-level before/after diff, so you can see exactly which fields moved and from what to what. Only fields the file actually changes are listed: a column your file leaves out, or a cell Lyra couldn’t read, means the stored value is left alone and isn’t shown as a change.
status: Unchanged — the row matched what Lyra already holds, so nothing was written. This is most of a re-uploaded roster export, and it’s what lets the rows that did move stand out.
status: Removed — a record was deleted (Replace mode only).
status: Error — a row didn’t import cleanly, or a removal was blocked. Every code the importer can report is listed under import outcomes.

Errors block only the affected rows; everything else in every file is still imported. The summary shows exactly how many records were added, updated, removed, and errored; unchanged rows count toward none of those.

Two columns say what happened to a row, and they answer different questions. button: Issues is what went wrong — the reason a row didn’t apply, or, on a row that did, what the importer had to note about it. A row that was status: Updated can carry one: a returning patron whose file now has an invalid PIN or an unknown homeroom is updated and flagged, not rejected. button: Fields is what moved — the fields a re-import changed, message: New row for a patron who wasn’t there before. Expand the row for the field-level before and after.

The import detail page is titled by when the run started — Roster import Sep 2, 1:42 PM — since what identifies a run is its moment, not the file names, which sit under it: a card: Files strip listing the files that import was created from. Each one is a button: select it to download the original upload, byte for byte, under the name you uploaded it with. A roster error is a row that already didn’t apply, and there’s no way to fix one from inside Lyra — so the file is where you fix it. Download it, correct the rows, and import again. The strip is there while the import is still processing and after a failed one, not only on a completed run, and any staff member can use it. A run that failed outright says so in a banner under the strip, with button: Read the import troubleshooting guide and button: Email support beneath it. On a run that finished, the same pair is on each affected row instead: point at or tap what its button: Issues column says.

The side effects of a Replace-mode removal show up here too: see Homeroom removal and Patrons that can’t be removed for how blocked removals, cleared homerooms, and active-loan errors are reported.

When to use a roster import vs. OneRoster sync

Two paths for getting rosters into Lyra. Which to pick:

Situation	Roster import	OneRoster sync
One-time migration	Yes	Possible, but overkill
Annual start-of-year refresh	Works	Better, runs without manual upload
Mid-year corrections	Yes, with Update selected	Picks them up on the next sync
Schools without OneRoster from their SIS	Yes (only option)	Not available
Schools whose SIS exposes OneRoster v1.1	Works, but manual	Better

You can also use both. A library on OneRoster for the daily roster can still run an occasional roster import for one-off corrections that the SIS doesn’t carry (parent notice emails are one example).