OneRoster API

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 two types of connections available, Roster Sync and Grade Book 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.


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 InteroperabilityThis 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 ConnectionThese 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 ConnectionsThis 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 GuidelinesBecause 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

Receiving Grades from an External System (Grade Book Sync)

The OneRoster API is mostly used to retrieve information about Course Sections from Campus for use in third-party systems. These systems can also send posted grades back to Campus. This section describes the conditions required for grades to be passed back.

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.

OneRoster version 1.0 is being 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:

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:

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.

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 ElementCampus Equivalent
Academic SessionTerm Schedules for a school Calendar.
ClassSection
Enrollments

Students - Roster records

Teachers - Section Staff History records

Line ItemStandard/Task + Term + Section
CategoryPosted Grade
OrgDistrict & School
ResultGrading 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:

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:

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Feedback