OneRoster

Introduction

Microsoft School Data Sync can synchronize identity and roster information from any system that implements the IMS OneRoster® API standard in an inbound data stream. Grade sync also uses the IMS OneRoster® API however this is an Outbound flow back to the SIS from Teams. This document is intended to help any new providers of OneRoster® APIs to successfully integrate with School Data Sync and Grade Sync. The following onboarding process defines the steps required by the API provider before they can be added into the School Data Sync portal.

API Guidance for SDS integration

  1. Complete the form on the SDS Partner Signup Form.
  2. Implement the OneRoster API® endpoints required by School Data Sync.
  3. Verify School Data Sync works with your OneRoster API endpoints.a. Test your APIs using Postman collection.b. Test with SDS engineering against a sandbox environment.c. Configure a full sync in SDS to validate the solution E2E.
  4. Pilot the solution with 2 production customers.
  5. Make your connector Generally Available in SDS for all Office 365 EDU tenants.

Getting Started

About School Data Sync

  • If you’d like to learn more about SDS, go to the SDS Product Site.
  • For technical information regarding SDS, including deployment videos and admin guidance, go to the SDS Docs site.
  • For more information on using SDS with OneRoster API®, go to the SDS OneRoster page.
  • If you’d like to integrate your system with School Data Sync and Office 365, please complete the SDS Partner Signup Form.

Useful Resources

If you are newly developing the OneRoster® APIs, please follow the OneRoster API 1.1 specification for Core Rostering here.

A sample implementation in ASP.NET MVC using C# is here.

We suggest certification of the provider with the IMS Global, but do not require it. 

Required API Endpoints for School Data Sync

ActionURLRequired Filter PropertiesExamples
getAllAcademicSessions/academicSessionsschoolYear, status/academicSessions?filter=schoolYear=’2019′ AND status=’active’
getAcademicSession/academicSessions/{academicSession_id}
getAllUsers/usersstatus, dateLastModified/users?filter=status=’active’ AND dateLastModified>’2018-01-25T03:22:03.297Z’
getUser/users/{user_id}
getAllSchools/schoolsstatus, dateLastModified/users?filter=status=’active’ AND dateLastModified>’2018-01-25T03:22:03.297Z’
getSchool/schools/{school_id}
getClassesForSchool/schools/{school_id}/classesstatus, dateLastModified/schools/{school_id}/classes?filter=dateLastModified>’2018-01-25T03:22:07.209Z’
getStudentsForSchool/schools/{school_id}/studentsstatus, dateLastModified/schools/{school_id}/students?filter=dateLastModified>’2018-01-25T03:22:07.209Z’
getTeachersForSchool/schools/{school_id}/teachersstatus, dateLastModified/schools/{school_id}/teachers?filter=dateLastModified>’2018-01-25T03:22:07.209Z’
getEnrollmentsForSchool/schools/{school_id}/enrollmentsstatus, dateLastModified, role/schools/{school_id}/enrollments?filter=role=’student’/schools/{school_id}/enrollments?filter=dateLastModified>’2018-01-25T03:22:28.204Z’ AND role=’teacher’
getClass/classes/{class_id}
getEnrollment/enrollments/{enrollment_id}
getStudent/students/{student_id}
getTeacher/teachers/{teacher_id}
getTerm/terms/{term_id}

Helpful Notes and Tips

  1. The endpoints always come after https://{server_URL}/ims/oneroster/v1p1
  2. {school_id} and {term_id} correspond to the sourcedId property of each school or term that was selected in profile creation.
  3. All endpoints must support paging, i.e., limit and offset parameters (ex: limit=10&offset=20).
  4. Some endpoints have requirements on filter parameter support to allow filtering by status, or to enable delta sync. Those are included in the table.
  5. SDS leverage a filter on the dateLastModified property for delta sync / incremental sync processing, and is required for integration with SDS.
  6. Providers must choose to implement either OAuth1(a) or OAuth 2.0 (Client Credentials Grant) authentication scheme. OAuth 2.0 is preferred.
  7. During development you can verify your endpoints with our Postman Collection.
  8. If authentication protocol supported is “OAuth 2” – Client Credentials Grant type, School Data Sync would send the credentials in “Authorization” Header. SDS does not support sending the credentials in request body.

Testing the APIs

Test your APIs using Postman collection

Postman is a well-known tool to run and manage REST APIs. We have created OneRoster® API collection to invoke and test the OneRoster APIs required by SDS. Download and run the OneRoster® postman collection available here. Running the collection invokes all the APIs required by SDS and runs simple tests against the data returned.

Test with SDS Engineering against a sandbox environment

Create a sandbox environment for the OneRoster® APIs and share the credentials with your designated SDS engineer. Together, we will run a deeper set of tests to ensure integration is successful.

Configure a full sync to validate the solution E2E

When all the tests have succeeded, create an SDS sync profile on your test O365 tenant to sync data from your OneRoster endpoints, and ensure sync completed without errors. Instructions to create an OneRoster sync profile are available here. When you select the OneRoster® provider, select the “Other” option. If you see any errors or issues, please escalate to your School Data Sync Engineer.

Pilot

Once testing has completed successfully, it’s time to start piloting the solution with customers. Your System’s name will be added to the list of OneRoster® providers in School Data Sync and will be visible to “flighted” Office 365 EDU tenants which have agreed to pilot the integration. The SDS team and the OneRoster® provider team will work together to identify the appropriate pilot customers and schedule a time to deploy SDS using OneRoster® API integration. We will work closely with customers to ensure the data sync is successful and validate the results along with the provider and customers. Any final bugs identified will be addressed prior to making the solution generally available to all Office 365 Education customers.

Go Public

Once we have two customers successfully complete their pilot deployments, the partner system will be made available in School Data Sync as a certified source system. SDS will display the provider name to all the users during setup. The SDS team will also document the partner system on our OneRoster API integrated systems site. The integration will also be reflected on our SDS product site. To do this, the SDS team will need:

  • Company logo
  • Minimum Version of Software
  • Configuration Prerequisites
  • How to get Client ID, Client Secret, and URL(s)
  • Any other specific instructions
  • Who to contact for help

The SDS team will also work with the partner system team to promote the integration more broadly through various marketing channels.

API Guidance for Grade Sync Integration

  1. Finalize integration with SDS following the steps above.
  2. Implement additional OneRoster v1.1 endpoints if they are not already available.
  3. Commit to co-own this with Microsoft.

Why integration with SDS is necessary for Grade Sync

While it is true that Grade Sync is about getting assignments and grades out of Microsoft and Teams into your SIS, SDS is what brings your roster information into Microsoft. This is required as it allows Grade Sync to work seamlessly between an Office 365 Tenant and your SIS. Grade Sync relies on the identities and their sync records persisted by the Sync Profile in SDS.

Implement additional OneRoster v1.1 endpoints

While the initial integration of SIS data into SDS requires several OneRoster v1.1 endpoints, additional access is required to sync grade data. The below endpoints are required in addition to those listed earlier on this page. While the below endpoints are what is specifically required, we recommend implementing all of Table 3.1a (Rostering) and table 3.1c (Gradebook). Please visit the OneRoster API Final Specifications page for full detailed information on the endpoints.

ActionURLMethods
Students for a Class/classes/{class_id}/studentsGET
Teachers for a Class/classes/{class_id}/teachersGET
All Teachers/teachersGET
Classes for a Teacher/teachers/{teacher_id}/classesGET
All users/usersGET
All Line Items for a Class/classes/{class_id}/lineItemsGET
Results for a single Line Item/classes/{class_id}/lineItems/{lineitem_id}/resultsGET
Results for a single Student in a specific Class/classes/{class_id}/students/{student_id}/resultsGET
Update specific Line Item/lineItems/{lineitem_id}PUT
Update specific result/results/{result_id}PUT

Working with standards like OneRoster is the only way to make a feature such as Grade Sync scalable to all of our customers’ needs.

Helpful Notes and Tips

  1. {lineitem_id} and {result_id} correspond to the sourcedId property of each line item or result that is being returned.
  2. Some endpoints have requirements on filter parameter support to allow filtering by email and sourcedId.
  3. Providers must implement OAuth1(a) authorization scheme which is the only supported scheme by GradeSync currently.
  4. During development you may consider verifying your endpoints with our Postman Collection.

Testing the APIs

We have updated the OneRoster® API Postman Collection with GradeSync requirements. The updated Collection invokes all APIs for GradeSync in addition to SDS. It creates a new assignment and adds a grade to it, upon every execution. Download and run the OneRoster® V1.1-OAuth1.a Postman collection available here.

Note that the Collection calls DELETE on created Assignments and Grades for cleanup purposes. However, implementing DELETE APIs is completely optional as they aren’t currently used by GradeSync.

Commit to co-own this with Microsoft

Create an agreement with your Microsoft contact to be accountable for the following aspects of this collaboration:

  • Test environment: This includes furnishing Microsoft with a production-like test environment that will remain functional beyond launch date.
  • Co-development: This includes helping solve dev and test problems before and after launch.
  • Co-servicing: This includes helping solve critical customer issues, including having an escalation path for Severity 1 issues that has responsive parties to deal with live site issues.
  • Co-marketing and co-promotion: These include appropriate communications to your community to help us generate excitement about the launch.

All our customers succeed when we work together.

Recommended content

Show more