Transition to OneRoster: Administrator guide Follow

In this article:

• Overview
• Before you begin
• SIS compatibility checklist (OneRoster)
• Steps to follow
• Technical considerations (teacher impact)
• School codes
• Google Groups created by Hāpara (per school)
• Getting help

Overview

This article helps Admins plan and complete a safe migration from other integrations to a OneRoster sync in Hāpara, with clear steps and teacher-impact notes.

Moving from a different integration to OneRoster changes how classes and memberships are created in Hāpara. Plan the cutover between terms. You’ll update school codes, configure the OneRoster connection, and archive already-synced classes. Communicate teacher-facing impacts (classes, Drive folders, scheduled sessions, and linked Workspaces).

Before you begin

• Target a term break (e.g., semester or summer) so new, clean rosters can be created.
• Notify stakeholders (tech leads, school admins, instructional coaches, teachers) of the timeline and impacts.
• Confirm you have Hāpara Admin Console access and access to your SIS / OneRoster export or vendor.

SIS compatibility checklist (OneRoster)

Admins should confirm SIS/vendor compatibility before scheduling the cutover. At minimum, verify:

• OneRoster version: Supports OneRoster 1.1 (data model and endpoints).
• Integration method: Supports REST API (preferred). If REST isn’t available, confirm your vendor’s OneRoster alternative and contact implementation@hapara.com to validate compatibility.
• Auth & security: API key or OAuth2 credentials available; can provide base URL; IP allowlisting if required.
• Core endpoints/data present: orgs (schools), academicSessions (terms), courses, classes (sections), enrollments, users — with teacher/student roles.
• Identifiers align: orgSourcedId (or equivalent) for schools matches the Hāpara school code; user records include primary emails used for Google accounts.
• Data completeness: Start/end dates for terms and classes; active/withdrawn status; multiple teachers per class if applicable.
• Operational limits: Pagination supported; vendor rate limits known; recommended sync cadence (e.g., nightly) agreed.

Quick check: Does your SIS support OneRoster 1.1 and a REST API? If yes, proceed to setup. If not, email implementation@hapara.com to review options.

Steps to follow

1. Archiving
   • Default recommendation: Archive all existing classes at cutover so OneRoster can create fresh classes.  This task will be completed by Hāpara Implementation team.
   • Archiving removes classes from teacher view but preserves historical records.

2. Check and align school codes

   • In Hāpara Admin Console → Schools, note each Hāpara school code (one per school).
   • In your SIS / OneRoster source, set each school’s identifier to match the Hāpara school code.
   • A school’s identifier can’t be changed to match, so add the school as new in Hāpara with the correct code (then remove the old one after verifying there are no active classes).

   Common SIS fields used as the OneRoster school identifier (confirm with your SIS admin):

   SIS	Typical field used	Notes
   Infinite Campus	orgs.orgSourcedId / Source ID	Often called Source ID in exports. Confirm in your OneRoster feed.
   Aeries	orgs.code / Code	Districts often map School Code here.
   PowerSchool	orgs.identifier or school_number	Naming varies by exporter; align to the value Hāpara expects.

   Tip: After adding new schools, you may remove the old school only if it no longer shows any classes.

3. Set up the OneRoster sync
   • Follow How to set up your OneRoster integration (credentials, endpoints, scopes, sync cadence).
   • Run an initial test sync against a small subset (one school) when possible.
4. Plan teacher‑visible changes
   • Prepare messaging for teachers about what they will see on day one (see Technical considerations below).
   • Provide the date when old classes disappear and new ones appear.
5. Cut over and verify
   • On your planned date, disable previous sync, archive already-synced classes, and enable OneRoster sync.
   • Verify for each school: classes created, teachers enrolled, students enrolled.
   • Spot‑check in Highlights that students appear Online and class tiles look correct.
6. Clean up school Google Groups (optional)
   • When a school is added, Hāpara creates school‑scoped Google Groups: td.administrators.SCHOOLCODE and td.users.SCHOOLCODE.
   • If you remove a school from Hāpara, you may also remove the corresponding Groups from the Google Admin Console after confirming they’re no longer used.
7. Communicate completion & support
   • Send teachers a quick “what changed” summary and where to get help.

Technical considerations (teacher impact)

These changes typically occur when migrating to OneRoster. Share them with teachers in advance.

• Classes: All classes will be archived to make room for new OneRoster‑synced classes.
• Class Google Drive folders (if previously created via Hāpara sync): legacy folders will be archived. OneRoster class Google Drive folders will NOT be created.
• Scheduled templates & recurring sessions (Highlights): items linked to all classes will be deleted.
• Workspaces linked to all classes: these links will be deleted. (The underlying Drive files remain; teachers can relink Workspaces to new classes.)

Suggestion for teacher comms: “On xx/xx/xxxx, your old classes will be archived and new OneRoster classes will appear. If you had scheduled Highlights sessions or linked Workspaces, please recreate or relink them in your new classes.”

School codes

• OneRoster syncing relies on a matching school code between Hāpara and your OneRoster orgs data.
• View codes at Hāpara Admin Console → Schools. Ensure each OneRoster school’s identifier matches the Hāpara school code exactly.

• If Hāpara and OneRoster do not match, add the school as new with the correct code, confirm no classes exist in the old school, then remove the old school.

Google Groups created by Hāpara (per school)

• td.administrators.SCHOOLCODE
• td.users.SCHOOLCODE

To review role mappings, see Admin Console → Users → Roles. If you remove a school from Hāpara, you can remove Groups that reference its old school code from the Google Admin Console.

Getting help

• For implementation assistance, email implementation@hapara.com.
• Include your district name, target cutover date, and SIS/OneRoster provide.