Onboarding OneRoster® API providers in SDS and Grade Sync

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

Action URL Required Filter Properties Examples
getAllAcademicSessions /academicSessions schoolYear, status /academicSessions?filter=schoolYear='2019' AND status='active'
getAcademicSession /academicSessions/{academicSession_id}
getAllUsers /users status, dateLastModified /schools?filter=status='active' AND dateLastModified>'2018-01-25T03:22:03.297Z'
getUser /users/{user_id}
getAllSchools /schools status, dateLastModified /users?filter=status='active' AND dateLastModified>'2018-01-25T03:22:03.297Z'
getSchool /schools/{school_id}
getClassesForSchool /schools/{school_id}/classes status, dateLastModified /schools/{school_id}/classes?filter=dateLastModified>'2018-01-25T03:22:07.209Z'
getStudentsForSchool /schools/{school_id}/students status, dateLastModified /schools/{school_id}/students?filter=dateLastModified>'2018-01-25T03:22:07.209Z'
getTeachersForSchool /schools/{school_id}/teachers status, dateLastModified /schools/{school_id}/teachers?filter=dateLastModified>'2018-01-25T03:22:07.209Z'
getEnrollmentsForSchool /schools/{school_id}/enrollments status, 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 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 customer 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 2 customers successfully complete their pilot deployments of the solution, 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. Implement OAuth2.0 (Client Credentials Grant)

  4. 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 a number of 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.

Action URL Methods
Students for a Class /classes/{class_id}/students GET
Teachers for a Class /classes/{class_id}/teachers GET
All Grading Periods /gradingPeriods GET
All Teachers /teachers GET
Classes for a Teacher /teachers/{teacher_id}/classes GET
All users /users GET
All Categories /categories GET
All Line Items for a Class /classes/{class_id}/lineItems GET
Results for a single Line Item /classes/{class_id}/lineItems/{li_id}/results GET
Results for a single Student in a specific Class /classes/{class_id}/students/{student_id}/results GET
Update/Delete specific Line Item /lineItems/{id} PUT, DELETE
Update specific result /results/{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.

Implement OAuth2.0

implement OAuth2.0 Bearer Token / Client Credentials Grant. This is recommended by both SDS and IMS Global, but required by Grade Sync. This is because we need to choose one authentication scheme that can scale to all of our customers' needs. This is the most secure authorization flow and the one we've selected to standardize upon.

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: This includes appropriate communications to your community to help us generate excitement about the launch.

All of our customers succeed when we work together.