OneRoster 101

What is OneRoster?

OneRoster is a set of specifications established by the IMS Global Learning Consortium. Campus created our OneRoster API based on these specifications.

The OneRoster API allows third-party systems (such as an LMS) to retrieve data from Campus, if the system has been given the correct credentials. The data that can be gathered through this API includes roster and section data, as well as assignments, grades, and scores, if enabled. This API allows districts to more simply integrate their third-party program with Campus.

Campus does not own the OneRoster specifications; we created the OneRoster API based on those specifications to allow third-party systems to communicate with Campus. Fields in Campus are mapped to fields in OneRoster.

Getting Started

It is important to understand that the OneRoster API allows third-party systems to request information from Campus and send it back; Campus does not make requests, it only receives them. Thus, there is no interface in Campus through which users interact with OneRoster. The external system is responsible for making all requests for data, either to receive section data or to send posted grade information. If the OneRoster API were a telephone, Campus would only be able to receive calls, not make them.

In order for the third-party system to make these requests, they must be given credentials to Campus through the Learning Interoperability tool. After these credentials are created, the district is responsible for communicating important fields with the third-party system. The Implementing OneRoster section below explains this process and the fields used by the third-party system to connect to Campus.

Type of OneRoster Connections

There are three types of connections available, Roster Sync, Grade Book Sync, and Assessments Sync. Connections are managed in the Learning Interoperability tool.

Roster Sync

Allows third-party vendors to request section and roster data from districts.
Available as part of the 1.1 and 1.2 versions of the IMS Global Specification.

Grading Services Connections

Allows third-party vendors to request section and roster data from districts and send assignment, score, and grade data.
Available as part of the 1.1 and 1.2 versions of the IMS Global Specification.
Only available to districts who have opted in to Campus Learning.

Assessment Sync

Allows third-party vendors to return assessment and assessment score data from districts.
Available as part of the 1.2 versions of the IMS Global Specification.

Note: OneRoster data is scoped to the active school year.

Available Content

The following sections and articles provide a deeper understanding of the OneRoster API works.These articles can be shared with third-party systems using the article's URL.

Necessary Information
Learning Interoperability	This tool allows admins to manage OneRoster connections (as well as LTI connections). Connections must be enabled to allow vendors to access Campus data.
Implementing a Roster Sync or Grade Book Sync Connection	These sections explain the initial process of implementing a connection to OneRoster that include Roster Sync and Grade Book Sync, including creating credentials and sharing them with third-party systems.
Configuring OneRoster Connections	This article walks through enabling OneRoster connections, including Roster and Grade Book Sync, and covers differences between the 1.1 and 1.2 versions of the specification.
OneRoster API Consumer Guidelines	Because of the retrieving data from Campus can be taxing on the system, this article provides recommendations for external parties to optimize performance. Districts are responsible for ensuring that vendors conform to any recommended guidelines.
Helpful Information
External LMS Exclude Hierarchy	Throughout Campus, the 'External LMS Exclude' checkbox prevents various records from being retrieved by third-party systems. This sections explains the hierarchy of these checkboxes (For example, marking a Course as Exclude also excludes its sections.)
REST Documentation Client	The REST Documentation Client allows users to review the data that can be retrieved through the OneRoster API. The link to the Documentation Client is provided with the OneRoster and Grading Services credentials and should be shared with districts. This article explains using the Documentation Client.
Teacher Tasks (Grade Book Sync)	Teachers must select categories and grading alignments for assignments received through a grading services connection so that scores and grades can be correctly reported in Campus. This article explains how to make those alignments.
Data Models Documents	Data Models articles describe each endpoint in the specification and map fields to locations in the Campus UI and database: OneRoster 1.1 Data Models OneRoster Assessments 1.2 Data Models

OneRoster version 1.0 has been deprecated by IMS Global. Campus will not support issues with the 1.0 connection after 12/31/19. No action is required from districts at this time; vendors should have implemented or be working towards OneRoster version 1.1 or the upcoming 1.2. As vendors move to new versions, districts will need to provide the v1p1 or upcoming v1p2 API Base URLs.

Implementing OneRoster 1.1 - Roster Sync

At the beginning of the school year, districts should not sync with vendors until student scheduling is finalized. Syncing prior to finalizing scheduling may cause incorrect data in the vendor system.

To implement a OneRoster Provisioning connection, a district must first verify that their third-party vendor conforms to the OneRoster API specifications, such as by being OneRoster certified, which indicates that the system can communicate through the OneRoster API.

If the third-party system meets these specifications, a Campus administrator would then use the Learning Interoperability tool to create credentials for it. The administrator is responsible for communicating those credentials and URLs to the third-party, including the following information:

The Consumer Key and Consumer Secret: the username and password the third-party program uses to access Campus.
The OneRoster (1.1) Base URL: the URL the third-party system uses to access Campus.
The Rest Documentation Client: the documentation of the API, which the third-party or the administrator can use to review and verify data. See the REST Documentation Client article for more information about this tool.
Performance recommendations to optimize the data sharing process.

Using those credentials and URLs, the external system can then make requests for data from Campus.

Once the third-party program has received this information, they can make requests using the API Host Name URL and the endpoints provided in that link.

Districts are responsible for ensuring that vendors conform to any recommended guidelines.

Implementing OneRoster 1.1 - Grade Book Sync

Third-party vendors must be part of the Infinite Campus Digital Learning Partner Program for Grade Book Sync to be available, which verifies that the vendor meets the necessary technical and security requirements.

System administrators use the Learning Interoperability tool to create credentials allowing the vendor to connect to their district's instance of Camps. The administrator is responsible for communicating those credentials and URLs to the vendor, including the following information:

The Key and Secret: the username and password the third-party vendor uses to access Campus.
The OneRoster (1.1) Base URL: the URL the third-party vendor uses to access Campus.
The Rest Documentation Client: the documentation of the API, which the vendor or the administrator can use to review and verify data. See the REST Documentation Client article for more information about this tool.

Using those credentials and URLs, the vendor can request data from Campus and send assignment, score, and grade data back.

Note that Grading Services connections apply to a district as a whole. Data for the district is sent to the vendor, but the data sent back from the vendor is dependent on the vendor's setup. For example, data for all schools may sync to the vendor, but if the vendor only sends data back for one school, only those teachers (who also have accounts in the vendor program) will receive synced data. Districts may exclude data from being sent to vendors on a school-by-school basis using the External LMS Exclude checkbox on the School tab. In the 1.2 version of the OneRoster specification, users have the option of scoping OneRoster connections by school.

Caching OneRoster Data

Historically, all data sent through the OneRoster API was live data. However, beginning in the spring of 2021, some data elements were updated to cache data to improve performance.

Cached data can be updated manually at any time by clicking Refresh OneRoster Cache in the Learning Interoperability tool.

Class Data	Student Data
Class-related records are cached and updated nightly (refresh started at 4:10 am local time). Examples of these changes include: Creating, deleting, or updating a section. Changes to an External LMS Exclude checkbox that affects the section (Section, Course, Calendar, or School Level)	Student-related records are cached and updated hourly from 6:00 AM to 6:00 PM and once overnight at 4:10 AM (local time). The specific time each refresh is triggered is dependent on the system restart time for the district. On non-production environments (sandbox, staging, and training) the cache is updated only nightly. Examples of these changes include: Creating or deleting a student's Person record. Creating, deleting, or updating a student's User Account. Creating or deleting an Enrollment in the active year for a student. Updating the following data for a student: Student Number, State ID, Grade Level, or Username. Changes to a student's enrollment status, whether by creating, deleting, or updating an existing enrollment or the status of an enrollment changing based on Start and End Dates. Changes to an External LMS Exclude checkbox that affects the student (Enrollment, Grade Level, Calendar, or School).
Additionally, both the Student cache and the Class cache are updated if any of the following actions are performed: Active year is changed. External LMS Exclude checkbox is modified for a calendar, course, section, enrollment, or grade level. Any of the listed fields in the following records are created, deleted, or updated: Enrollments: Grade Level or No Show Courses: Active, Homeroom, Name, Number, Subject, Core Subject, SCED Subject Area, SCED Course ID Section: Number, Room, Teacher Display Name User Account: Disabled, Homepage, Username, Expiration Date

Class Data

Student Data

Class-related records are cached and updated nightly (refresh started at 4:10 am local time).

Examples of these changes include:

Creating, deleting, or updating a section.
Changes to an External LMS Exclude checkbox that affects the section (Section, Course, Calendar, or School Level)

Student-related records are cached and updated hourly from 6:00 AM to 6:00 PM and once overnight at 4:10 AM (local time). The specific time each refresh is triggered is dependent on the system restart time for the district. On non-production environments (sandbox, staging, and training) the cache is updated only nightly.

Examples of these changes include:

Creating or deleting a student's Person record.
Creating, deleting, or updating a student's User Account.
Creating or deleting an Enrollment in the active year for a student.
Updating the following data for a student: Student Number, State ID, Grade Level, or Username.
Changes to a student's enrollment status, whether by creating, deleting, or updating an existing enrollment or the status of an enrollment changing based on Start and End Dates.
Changes to an External LMS Exclude checkbox that affects the student (Enrollment, Grade Level, Calendar, or School).

Additionally, both the Student cache and the Class cache are updated if any of the following actions are performed:

Active year is changed.
External LMS Exclude checkbox is modified for a calendar, course, section, enrollment, or grade level.
Any of the listed fields in the following records are created, deleted, or updated:
- Enrollments: Grade Level or No Show
- Courses: Active, Homeroom, Name, Number, Subject, Core Subject, SCED Subject Area, SCED Course ID
- Section: Number, Room, Teacher Display Name
- User Account: Disabled, Homepage, Username, Expiration Date

Comparing Data in Campus and OneRoster

Because Campus and OneRoster store data differently, elements in Campus are mapped to elements in OneRoster. The following table describes mappings that are not self-evident.

OneRoster Element	Campus Equivalent
Academic Session	Term Schedules for a school Calendar.
Class	Section
Enrollments	Students - Roster records Teachers - Section Staff History records
Line Item	Standard/Task + Term + Section
Category	Posted Grade
Org	District & School
Result	Grading Score (including comments)

To be included in OneRoster, users must have user accounts.

External LMS Exclude Hierarchy

Throughout Campus, records can be excluded from being sent to an External LMS through this API. Marking the External LMS Exclude checkbox indicates that records are not relevant to the LMS. The following types of records can be excluded:

System Administration > Resources > School
System Administration > Calendar > Calendar > Calendar, Grade Levels, Schedule Structures
Scheduling > Courses > Course, Section
Student Information > General > Enrollments
Grading & Standards > Course Master > Course Master Info
Census > People > District Assignments
Grading & Standards > Grading Tasks, Standards Bank

Marking this checkbox for a record also applies to records below it in the hierarchy. For example, marking Exclude for a Course also excludes all Sections within that Course, although the checkbox is not automatically marked on each Section. The hierarchy is as follows:

School
- Calendar
  - Course
    - Section
  - Schedule Structure
    - Grade Level
    - Enrollment
- Course Master
- District Assignment
Grading Task/Standard

OneRoster API