OneRoster Roster Sync

This guide is for schools whose SIS exposes a OneRoster v1.1 endpoint and want Lyra to keep its patron list in sync automatically instead of re-uploading a roster file every term. Two things to keep an eye on as you go: parent emails are not part of the OneRoster spec (so if you rely on Lyra to email parents about overdues or holds, you’ll still need a roster-import path on top of this sync), and the OAuth credentials must come from your SIS admin or diocesan IT, they aren’t self-service.

Who this guide is for?

Schools whose SIS exposes a OneRoster v1.1 feed. Lyra’s roster source picker recognizes FACTS, Blackbaud, Veracross, PowerSchool, Alma, Rediker, and ClassLink by name, and there’s an Other option for any system that exposes a /ims/oneroster/v1p1 endpoint. Choosing your provider lets Lyra handle the ways its feed differs from the others. If anything doesn’t connect or sync the way you expect, get in touch and we’ll sort it out with you. Being listed doesn’t mean the feed is already turned on: most providers sell OneRoster as a paid add-on or need an IT admin to set up credentials. If your SIS isn’t here and doesn’t expose OneRoster, Roster import covers the manual path.

Terminology

OneRoster’s vocabulary is worth flagging upfront. sourcedId is its universal identifier; Lyra stores it as the patron’s identifier and matches every subsequent sync against it. classType is OneRoster’s tag for what kind of class a record represents (homeroom, scheduled, course); Lyra treats homerooms as the kind that maps to a Lyra homeroom. Enrollment is the join record between a user and a class; Lyra records every teacher enrollment on a synced homeroom, preserving each enrollment’s primary flag as the status: Primary marker on that membership. OAuth 2.0 client credentials is the auth mode: your SIS admin issues a client ID and secret, and Lyra exchanges them for a bearer token at sync time.

Overview

Lyra’s sync pulls users, classes, and enrollments from your SIS’s OneRoster v1.1 endpoint, transforms them into Lyra’s student/teacher/homeroom shape, and applies the result atomically: all or nothing per run. After the first connection it runs daily at a time you choose, and a button: Sync now button lets you trigger an immediate run from the dashboard.

Plan for about thirty minutes if you already have OneRoster credentials in hand. Plan for a week or more if you don’t; getting them issued is usually a paid-integration request to your SIS vendor or a ticket to your diocesan IT office.

Confirm OneRoster is available and get credentials

Three things to nail down before you open the wizard: that your SIS exposes OneRoster v1.1, the OAuth credentials, and how you’ll handle parent emails.
Open the sync setup wizard

Go to School level navigation path: Roster then Sync, then select button: Connect roster source.
Authenticate and pick schools

Wizard steps 1 and 2: paste the base URL and credentials, test the connection, then tick the schools you want to sync.
Choose homerooms and faculty roles, then review and connect

Wizard steps 3 through 5: confirm which OneRoster classes count as homerooms and which user roles import as Lyra faculty, then review the summary, say what happens to the roster you already have, and connect.
Verify the first sync, then settle into a schedule

Three quick post-sync checks, then edit the daily schedule to a time that fits your school’s timezone.

Chapter 1: Confirm OneRoster is available and get credentials

Three things to nail down before you open the wizard.

Whether your SIS actually exposes OneRoster v1.1. Most major SISes do, but not always by default. Provider notes:

Veracross: supports OneRoster v1.1. Your school’s Veracross admin issues the credentials. Creating an API integration in Veracross requires the OAuth_App_Admin security role, so even a system administrator may need it assigned first. Veracross issues tokens from its own accounts host, so once you enter the base URL Lyra fills in the matching field: Token URL for your school, along with the field: Scopes Veracross asks for.
FACTS: your school enables OneRoster from System → Configuration → SIS Integrations → OneRoster → API Export and submits FACTS’s signup form, and a FACTS integration specialist follows up with credentials. FACTS may charge for API access; ask FACTS about cost.
Blackbaud Education Management: supports OneRoster v1.1 with OAuth 2.0. Credentials are created under Core → Settings → Integration settings → OneRoster settings by a user with the Integration Manager role. Blackbaud’s token endpoint is on a different host from its API, so choosing Blackbaud fills in its field: Token URL and the field: Scopes it requires.
PowerSchool, Alma, Rediker: OneRoster v1.1 is supported by the vendor; availability and setup vary by deployment. Ask your SIS admin for the base URL and OAuth credentials.
ClassLink: rostering middleware rather than an SIS; it normalizes a school’s underlying SIS into a OneRoster-shaped feed. Lyra treats it as a OneRoster v1.1 source. Your IT admin issues the credentials from the ClassLink admin console.
Other: anything that exposes a /ims/oneroster/v1p1 endpoint and OAuth 2.0 client credentials should work; the Other option in the dropdown lets you label it.

The OAuth 2.0 client credentials. You need three things from whoever administers your SIS: a base URL (the OneRoster v1.1 root), a client ID, and a client secret. Some sources also give you a token URL and one or more scopes: copy them in if they do. Without a token URL, Lyra requests its token from /token at the root of the base URL. The base URL is the path up to oneroster/v1p1; Lyra appends the resource path itself. If you only see one combined URL (e.g. ending in /orgs), trim it back to the OneRoster root. If your SIS only offers OAuth 1.0a, the sync won’t connect; Lyra requires OAuth 2.0 client credentials. Use the manual roster import instead.

Whether parent emails matter to your library notices. OneRoster doesn’t carry parent contacts in a form Lyra can use for notices. If your school uses Lyra to email parents about overdues or holds, you still need a parent-email roster import on top of the OneRoster sync. Plan for both, not OneRoster alone.

Chapter 2: Open the sync setup wizard

Path: School level navigation path: Roster then Sync.

Connecting and configuring roster sync is a roster edit, so it’s admin-only. Standard staff can open the Sync page and read its status and run history, but the button: Connect roster source, button: Edit, button: Sync now, and button: Disconnect controls are shown only to admins; Limited staff don’t see the Sync section at all.

If no sync is connected, the page shows an empty state explaining what the feature does and a button: Connect roster source button. Select it to open the five-step wizard. The button: Read the setup guide link beside it opens this page.

The wizard remembers your progress only as far as the current step; closing it before selecting button: Connect in step 5 discards everything you entered. Plan to do steps 1–5 in one sitting; the slowest piece is usually step 1 if your SIS admin hasn’t confirmed the credentials yet.

Chapter 3: Authenticate and pick schools

This is wizard steps 1 and 2.

Step 1, Authenticate. Pick your roster source from the dropdown (or Other + a name field if your provider isn’t listed: “Senior Systems”, “Gradelink”, whatever you call it internally). Enter the base URL, paste your client ID and client secret, and select button: Test connection. field: Token URL and field: Scopes are optional. Lyra fills them in for sources that publish them, and you can type over either; leave them blank if your source didn’t give you any. The test reads the OneRoster /orgs and /schools endpoints with your credentials, then each school’s /schools/{id}/students to count its students (or /enrollments, for a source that doesn’t serve per-school students), so your client’s OAuth scope must allow them; on success you’ll see message: Connection successful and the wizard lets you advance. If it fails, the message says which half to check: message: Lyra could not find a roster source at that base URL. Check the URL and test again. means Lyra found nothing at the base URL (it may include too much, so trim it to /ims/oneroster/v1p1), and message: The roster source refused these credentials. Check the client ID and secret with your roster admin, then test again. means the source refused the client ID and secret (look for leading or trailing whitespace from a paste, or a client whose OAuth scope doesn’t include the OneRoster resources). Lyra trims spaces from either end of the base URL for you.

Step 2, Choose schools. The wizard fetches your /schools list and shows each school with a checkbox, identifier, and student count. Tick the schools you want Lyra to sync: only students and faculty the source places in a ticked school are imported, by their school or by a class there. Tick exactly one (your own). Diocesan deployments where one Lyra library serves multiple parishes can tick several, but be aware OneRoster sourcedIds aren’t guaranteed unique across separate SIS tenants, so if you’re aggregating across schools, namespace your patrons on the SIS side first to avoid collisions.

Chapter 4: Choose homerooms and faculty roles

This is wizard steps 3 through 5, the rest of the wizard, ending in the review-and-connect step.

Step 3, Select homerooms. The step opens with setting: Limit sync to selected classes: leave it off to import everyone in the schools you ticked, or turn it on to sync only the students and faculty enrolled in the classes you select here. Below it, Lyra pre-checks every class with classType: "homeroom" from your selected schools. Each row badges the class type it came in as — status: Homeroom, status: Scheduled, or status: Other for anything else, including course. If your SIS uses scheduled for advisory groups, or mislabels homerooms as course, untick the wrong ones and tick the right ones. The list is filterable by school and by name; counts on each row tell you roughly how many students each class holds. Selections refresh on every sync, so you can revisit this in the dashboard later when your school adds or renames homerooms.

A note on what “homeroom” means in Lyra: a Lyra homeroom can have one or more teachers. Every teacher enrollment on a synced homeroom is recorded on the homeroom, with each enrollment’s primary flag preserved as the status: Primary marker. Co-taught and team-taught homerooms come through with all their teachers attached. Students are assigned to at most one homeroom per sync; if a student is enrolled in multiple selected homerooms in the OneRoster feed, Lyra picks the first one deterministically.

Step 4, Faculty roles. OneRoster carries seven user roles: student, teacher, administrator, aide, proctor, parent, guardian. Lyra always imports student as student patrons; for faculty patrons, you pick which roles count. Default is teacher, administrator, and aide. Add proctor if your high school uses it; uncheck any of the defaults you don’t want. You can also tick parent or guardian, but Lyra ignores parent contact info on the backend; ticking them creates patron records for the parents themselves, which is rare but useful in the few schools that issue library cards to parents.

Step 5, Review and connect. The final step summarizes what you’re about to import: your source, how many schools and students are included, how many homerooms you picked, the faculty roles, the roster scope, and the daily sync schedule with the timezone it runs in (your school’s). Review it, then select button: Connect. The first sync runs immediately and usually finishes in under a minute for a small school, a few minutes for a large one.

If you already have patrons in Lyra, the step carries one more block — card: Your existing roster — and button: Connect stays disabled until you answer it. From the moment you connect, your source is the authority on who is a student and who is faculty, so the question is field: What happens to patrons it doesn’t list?:

Keep them as community patrons converts them to community patrons on the first run — only the ones your source turns out not to list, which is not knowable until that run has fetched its users. They keep their barcode, loans, holds and history, and the sync never touches them again. Grade, homeroom, class year, guardian emails and the OPAC PIN belong to a student record, so those do not carry over.
Remove them deletes them, except anyone holding a copy — see Removed patrons below.

A patron whose identifier matches a sourcedId your source issues is matched either way: the first run updates them in place and everything on the record survives, guardian emails and PIN included. Only the patrons your source never names are converted or removed.

The block also counts the homerooms your source doesn’t list, because the first sync removes those whichever option you pick, and their students are re-placed from your source’s enrollments.

The question is asked once, at connect time. From then on your source is the authority and a student or teacher it stops listing is removed.

Chapter 5: Verify the first sync, then settle into a schedule

The sync dashboard now shows a connected state with three count cards (students, faculty, and homerooms), a “Last sync” line, and a card: Recent Syncs list. Three checks worth doing right after the first sync:

Patron count. Lyra’s totals should match your SIS’s student count plus faculty count (filtered to the roles you ticked), within a handful of rows. Larger gaps mean you ticked the wrong schools in step 2 or the wrong faculty roles in step 4.
Homeroom assignments. Pick three homerooms you know. Open each in Lyra (School level navigation path: Roster then Homerooms) and confirm the right teacher and roughly the right number of students. This is where the most reconstruction happens, so it’s where surprises hide.
A test patron. Find one student you know personally; confirm name, email, grade, and homeroom teacher all look right. If one record is right, the same mapping produced the rest, so they should be too.

If something’s off by more than a rounding error, fix it in your SIS rather than in Lyra; the next sync will overwrite Lyra’s view of that data anyway.

Schedule. The card: Sync schedule box defaults to a daily run in your school’s timezone. To move it to a different hour — say your SIS’s own export job runs late at night and you want Lyra to pull fresh data after it completes — select button: Edit on the setting: Schedule row. Turn off setting: Daily sync enabled in the same dialog if you ever need to freeze syncs temporarily; Lyra keeps the existing patron data exactly as it is until you re-enable.

Manual sync. A button: Sync now button at the top of the dashboard runs an immediate sync; useful after you fix a record in your SIS and want Lyra to pick it up before the next scheduled run.

Sync history and retention

The screen: History view shows every run: trigger (Manual or Scheduled), duration, and per-run counts of records added, updated, and removed. Select a run to see the phase timeline (authenticate → fetch users → fetch classes → reconcile → apply) and a per-record diff showing exactly which fields changed.

What syncs and what doesn’t

What syncs.

Students: matched on OneRoster sourcedId → the patron’s identifier in Lyra.
Faculty: only those with a role you ticked in step 4.
Homerooms: only the classes you ticked in step 3, with every teacher enrollment recorded and each one’s status: Primary marker preserved.
Student → homeroom assignment: one homeroom per student per sync.
class_year: computed from your school calendar’s academic year and the student’s grade, and persisted on the student. The grade comes from the grades on the OneRoster user, or, for a student whose record carries none, from the grade on their homeroom class. Lyra reads the standard codes — PK, KG, and 01 through 12. UG, IT, PS, and Other describe an enrollment that isn’t a K-12 grade, so a student carrying only those — and whose homeroom carries only those too — is synced without a grade and appears under No grade in the roster’s Grade filter.

What doesn’t sync.

Parent contacts and guardian_emails. OneRoster’s parent role data isn’t sufficient for notices. Use a roster import for parent emails; see guardian emails for the format.
Library barcodes. OneRoster doesn’t carry a barcode field, so Lyra assigns each synced patron a unique barcode automatically; there’s no separate step. To use your own values instead (for example, the SIS ID printed on existing cards), import a barcode column via a roster import or set it with menu item: Edit library card….
OPAC PINs. Lyra assigns each student’s PIN, and the sync never changes it. PIN is student-only in Lyra; faculty can’t have a PIN.
Titles and preferred names vary by provider. Some SISes expose them via OneRoster, some don’t; the first sync surfaces whatever’s available and updates them on subsequent syncs as they appear.
Removed patrons. Students and faculty that disappear from your SIS feed are removed from Lyra, but only if they have no active loans; someone still holding a copy is kept, the run finishes with status: Partial, and the next sync tries again once the copy is back. This only ever reaches students, faculty and homerooms — community patrons are never removed. For someone who should stay in Lyra whatever your SIS says, make them a community patron.

What you can still change in Lyra. Your SIS owns who a student or teacher is, and Lyra owns their library card. Everything the sync writes is your source’s: the patron type, field: Identifier, names and email, plus a student’s grade and homeroom or a teacher’s honorific. A synced student or teacher therefore has no menu item: Edit patron…; change those fields in your SIS and the next sync brings them to Lyra. What you can still edit, through menu item: Edit library card…:

A synced student’s field: Barcode, field: OPAC PIN and field: Guardian emails.
A synced teacher’s field: Barcode.
Everything about a community patron, which the sync never touches.

A synced student or teacher can’t be deleted, since your source would add them back, but their circulation history can be cleared with menu item: Clear history. See Clearing a patron’s history.

Homerooms are your source’s outright, so a synced school’s homerooms are view-only: there is no button: Add homerooms button, and a homeroom’s menus drop menu item: Add students…, menu item: Rename…, menu item: Change teachers…, menu item: Set grade… and menu item: Delete. For the same reason the screen: Patrons list doesn’t offer button: Set grade or button: Set homeroom: every student’s grade and homeroom come from your source.

button: Merge still folds a community patron into a synced one, which is how you tidy up someone you added by hand before your SIS listed them. The synced record is the one kept, and its names, email, grade and homeroom stay as your source has them; only the barcode, and a student’s PIN, are yours to pick. Two synced patrons can’t be merged in Lyra, because your SIS holds them as two people. Merge them there instead.

Editing settings later

Every row of the dashboard’s card: Configuration card has an button: Edit button.

setting: Schools: change which of your source’s schools sync. Unchecking a school drops its homeroom classes, and the next sync removes its students and faculty, holding any with loans out.
setting: Homeroom classes: re-pick which classes count as homerooms. If your school adds new advisories mid-year, this is where you tick them.
setting: Sync scope: sync everyone in the included schools, or only the students and faculty enrolled in the classes you selected as homerooms.
setting: Credentials: rotate the client ID and secret, or change the base URL, token URL or scopes. You’ll be required to re-test the connection before the new credentials are saved, which catches typos before the next sync fails on them.
setting: Faculty roles: change which OneRoster roles import as Lyra faculty.
setting: Schedule: change the daily hour, or pause syncing entirely. The hour is in the school’s timezone, which you change in School settings.

There’s also a button: Disconnect button at the bottom of the dashboard. Disconnecting stops automatic syncing but leaves all synced patrons in place. Re-connecting later resumes from a fresh first sync; Lyra still matches existing patrons by their identifier, so you won’t get duplicates as long as the credentials point at the same SIS tenant.

Common failure modes

A short troubleshooting list. If you see something not on this list, the run detail in screen: History has the failing phase and an error message.

message: The roster source refused these credentials. Check the client ID and secret with your roster admin, then test again. on button: Test connection. Wrong client ID, wrong secret, or your SIS hasn’t activated the credentials yet. Re-paste from a fresh copy and avoid trailing newlines.
message: Lyra could not find a roster source at that base URL. Check the URL and test again. on button: Test connection. The base URL is wrong (for example, it includes /orgs or another resource suffix and needs to be trimmed), the field: Token URL points somewhere with no token endpoint, or your SIS endpoint is IP-restricted. Confirm both URLs with your SIS admin.
First sync ran, but no homerooms appeared. Your SIS doesn’t tag classes as classType: "homeroom". Re-open the homerooms picker and tick the rows badged status: Scheduled or status: Other.
Teachers I expected are missing. Their OneRoster role is one you didn’t tick in step 4. Edit setting: Faculty roles from the dashboard and run a sync.
A whole sync failed. Open the run in screen: History and read the phase timeline; failures are atomic, so no partial writes happened. The likely cause is a credentials rotation that hadn’t been mirrored into Lyra yet.

Borrowers your SIS doesn’t list

Plenty of people borrow from a school library without appearing on its roster: parent volunteers, substitutes, a custodian, the parish priest, a homeschooled reader, a pre-K child your SIS doesn’t carry yet. Lyra has a third patron type for them — button: Community — and the roster sync never touches one. They are not updated from your source and never removed by it.

Once a school is connected, button: Add patron manually… creates community patrons only. Students and faculty come from your SIS, which is the point of connecting it; anyone your SIS doesn’t list isn’t a student or a staff member as far as Lyra is concerned, they’re a community borrower. A community patron can be any age — Lyra assumes nothing about that — so they borrow under your library’s default limits rather than the faculty overrides, and can sign in to the OPAC with an emailed code if you give them an email address. To add many at once — forty book-fair volunteers, say — upload a Community file through the roster importer, which still adds community patrons in a connected school.

If your SIS later starts listing someone you added by hand, and the identifier on their Lyra record matches the sourcedId your SIS issues, the next sync adopts them: the same record becomes a student or a teacher, keeping its barcode, loans, holds and history, and the run’s changes list records it as status: Adopted. Your source wins that tie, always. If the two identifiers differ you’ll end up with two records for one person — merge them from the roster page, and Lyra keeps the synced one.

The reverse happens once, on the first run, for a school that answered Keep them as community patrons on the wizard’s last step: the patrons the run finds your source does not list become community patrons, each recorded on the run as status: Moved to community.