OneRoster API Set Up Process

OneRoster is a standard set of REST APIs that enable schools to securely and reliably exchange information about rosters, course materials and grades, between multiple web services. It reduces the need to manually transfer data between systems, as well as the need to customize the format of import files for each web service.

OneRoster defines two roles, a Provider and a Consumer. Technical administrators or other users of the CSV can export from the Provider system, such as a student information system (SIS) and import to a Consumer system, such as an LMS or digital text. REST API-based products adopt the same concepts, but users are not handling files directly, since the exchange is system-to-system.

Prerequisites for OneRoster API Setup

• The setup process - The publisher creates credentials for the School District/District Admin. The OneRoster API Setup can be done by the Publisher or the District Admin. The Publisher/District Admin provides the API URL, Consumer Key and the Secret Key for OneRoster API Setup.
• Information required by Publisher from District Admin (In cases where the District Admin wants the Publisher to perform this activity on their behalf)  - API URL, Consumer Key and Secret Key for One Roster API Setup.
• Information needed by the District Admin from Publisher - The District Admin does not require anything from the publisher if they want the setup to be done at their end.

Step by step process flow for OneRoster API

1. Create a school district.

2. Add district admin for the school district.

3. Enable OneRoster for the school district.

4. Complete OneRoster API setup for the district. (Follow the below instructions)

Follow the below steps to complete OneRoster API setup

1. Log in to the portal

2. Select  "School District List" from the left-hand side menu.

3. You will see the below screen. 

4. Click on the OneRoster setting icon. 

You will be redirected to the "OneRoster" screen. Here you can see the district sync details in a card view. 

 5. Click "Create New" to initiate OneRoster for the district. You will see the below screen.

6. Select the district for which you wish to initiate OneRoster API from the drop-down list.

7. Select "OneRoster API" sync method from the options provided on the screen.

8. Select "Provider" from the drop-down list. (Currently, the platform syncs data from ClassLink and  Infinite Campus.)

9. Click "Start Configuration." This step will configure the district with sync method selected on this page. You will not be able to change the sync method once the district is already configured. (Note - In order to change the sync method for a particular district, you will have to delete the district from the card view and create OneRoster  for the district again.)

Once the sync configuration is complete, you will see the below screen. 

10. Enter "API URL."

11. Enter "Consumer Key."

12. Enter " Secret Key." 

13. Click "Test Connection." If the test connection is successful, you will receive a success message pop up on the screen and you can proceed to the next step. If test connection is unsuccessful, you will receive an error message pop up on the screen. 

You will see the below screen after clicking "Next" in the previous step.

14. In the "Select School to Sync" field, click the Edit icon. Here, you will see the list of schools in the district that are associated with the provider. Check the school to make the school selection. (Note - Once the OneRoster API sync is complete, the classes,  students and teachers from the selected school will sync and get rostered on the platform. It is mandatory to select at least one school.)

15. Select course to sync. (Check with team)

16. You can check the "Sync only active records from source directory." (Check with team)

17. Enter the "When should we stop syncing the district" date. The district will keep syncing rosters till the specified date. The district sync process will stop after this date. If there is any modification or addition of new users in the API, the data will not be synced on the platform after the specified date. (Note - It is mandatory to enter the sync expiry date. This date must be equal to or greater than the current date.)

18. Click "Next" to move to the review stage.

19. Review the district OneRoster sync details from the "Review" page.

20. You can check the "Subscribe to receive daily sync status email notifications" checkbox to allow the platform to send an email notification for daily sync status to the district admin/publisher.

21. You can check the "Subscribe to receive only sync error email notifications" checkbox to allow the platform to send only sync error email notification to the district admin/publisher.

22. If all details are correct on the "Review" stage, click "Start Sync."

You can see the sync status card view for the district on the OneRoster page. The card view will show the total record count number. You can click on the card view to see the One Roster sync information in detail along with the last sync records count. The platform will show the following sync status: 

In Progress - When sync is in process. 

Launched (in green) - When district sync is successful without errors.

Launched (in yellow) - When district sync is successful but has errors. The error count will be shown in the card view. 

Not Started - Whe the sync has not started.

Failed - When the sync is unsuccessful.

• You can also see the number of errors in the card view.
•  Download the.txt error file to know error details.