Onboarding Guidance for OneRoster API Providers with School Data Sync (SDS)

  • Article

Introduction

Microsoft School Data Sync (SDS) can synchronize identity and roster information from any system that implements the 1EdTech OneRoster API (Application Programming Interfaces) standard in an inbound data stream. This document is intended to help any new providers of OneRoster APIs to successfully integrate with SDS. The following onboarding process defines the steps required by the API provider before they can be added for tenants to select and use in SDS.

About SDS

Overview

  1. Complete the form on the SDS Partner Sign-up form.

    1. Indicate that you would School Data Sync Integration assistance on the form.

    2. Registration is required to access the form - visit the Microsoft Partner Network site for more information. You must submit a separate form for SDS and Office dev resource access.

  2. Implement the OneRoster API endpoints required by SDS.

    SDS uses a filter on the dateLastModified property for delta sync / incremental sync processing and is required for integration with SDS.

  3. Verify SDS works with your OneRoster API endpoints.

    1. Assess your APIs using Postman collection.

    2. Test with SDS engineering against a sandbox environment.

    3. Configure SDS to validate the solution E2E.

  4. Pilot the solution with two production customers.

  5. Make your connector generally available in SDS for all Office 365 EDU tenants.

Getting Started

Required API endpoints for SDS

Action URL Required Filter Properties Optional / Recommended Filter Examples
GetAllAcademicSessions /academicSessions status dateLastModified /academicSessions?offset=0&limit=5000&filter=status=’active’/academicSessions?filter=dateLastModified>’{deltaDateTime}'
GetAllOrgs /orgs status dateLastModified /orgs?offset=0&limit=5000&filter=status=’active’/orgs?filter=dateLastModified>’{deltaDateTime}’
GetAllUsers /users status dateLastModified /users?offset=0&limit=5000&filter=status=’active’/users?filter=dateLastModified>’{deltaDateTime}’
GetAllClasses /classes status dateLastModified /classes?offset=0&limit=5000&filter=status=’active’/classes?filter=dateLastModified>’{deltaDateTime}’
GetAllEnrollments /enrollments status dateLastModified /enrollments?offset=0&limit=5000&filter=status=’active’/enrollments?filter=dateLastModified>’{deltaDateTime}’

Optional API Endpoints for SDS

Note

For the optional pieces of data for demographics, student contact relationships and student user flags, the ability for a customer to include this data or not will be based on the supported optional data capabilities from your provider profile that we will create. Following the testing and verification steps noted, if you choose to also support this data for your customers that are using SDS, they will see the toggle (default) selected On to include additional data. They can select the toggle to turn off if they wish. If the toggle is unavailable, shown but off and not available for interaction, this means that your provider profile does not currently support providing that data.

Action URL Required Filter Properties Optional / Recommended Filter Examples
GetAllCourses /courses status dateLastModified /courses?offset=0&limit=5000&filter=status=’active’/courses?filter=dateLastModified>’{deltaDateTime}’
GetAllDemographics /demographics status dateLastModified /demographics?offset=0&limit=5000&filter=status=’active’/demographics?filter=dateLastModified>’{deltaDateTime}’

Optional user student contact relationships

Student contact relationship may be specified for student users to enhance educator experiences for communication to student parents and guardians. Contacts are more users that are supplied with the /users and association to a student are found in the student’s user record under ‘agents’.

  • For more information, on the supported Student Contact Relationship roles supported by SDS, see Default list of values: Contact Relationship Roles.
  • familyName, givenName, and email are required for users that have contact / guardian roles.
  • Expect phone and sms to be in E.164 and + must be included. (Example: +1234567890).
  • If reverse data is provided, from a contact relationship guardian record to student in the contact users ‘agents’ field, these records are filtered out.

Optional user demographics flags

User flags may be specified for student users to indicate their participation in a program or cohort. User flags are included (when true for the user), or not included if not applicable.

Flags are specified as a metadata extension for the user, in a metadata field, following a Key|Value pair, with the key named microsoft.userFlags and must be formatted as a comma delimited list. User flags may appear in any order and aren't case sensitive.

For more information, on the default list of user flag values supported by SDS, see Default list of values: User Flags.

Example:

{ 
  "user" : { 
   … 
   … 
    "metadata" : { 
     "microsoft.userFlags" : "freeLunch,homeless,giftedOrTalented“ 
    } 
}

Data Matching and Validation Rules

For more information on data matching and validation rules, see Validation Rules and Descriptions.

Important

Per 1EdTech it is the responsibility of the provider to enforce data privacy for what data is available when a data request is made. School Data Sync make a request for active data based on the time of the request.

Helpful notes and tips

  • The endpoints always come after the https url: {server_URL}/ims/oneroster/v1p1.

  • All endpoints must support paging, that is, limit and offset parameters (ex: limit=10&offset=5000).

  • Endpoints have requirements on filter parameter support to allow filtering by status, or to enable delta sync.

  • Customers know how to enable the option 'Is Active' or how to allow only for active data to be available for the connection that is to be used by School Data Sync. This ensures that only active data for the active School Year and session is provided as the school year progresses.

  • SDS applies a filter on the dateLastModified property for delta sync / incremental sync processing and is required for integration with SDS.

  • Providers must choose to implement either OAuth1(a) or OAuth 2.0 (client credentials grant) authentication scheme, OAuth 2.0 preferred.

  • During development, you can verify your endpoints with our Postman collection.

  • If authentication protocol supported is "OAuth 2" - client credentials grant type, SDS would send the credentials in "Authorization" Header. SDS doesn't support sending the credentials in request body.

Testing your OneRoster APIs

Using Postman collection

Postman is a well-known tool to run and manage REST APIs. We have created OneRoster API Postman collection to invoke and test the OneRoster APIs required by SDS. 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 your OneRoster APIs and share the credentials with your designated SDS engineer. Together, we run a deeper set of tests to ensure integration is successful.

Configure to validate the solution

When all the tests have succeeded, your system’s name is added to the list of OneRoster providers in SDS but only visible for tenants flighted for providers profiles denoted as being ‘InPilot’ mode (not publicly available). Next, you'll onboard SDS by setting up Data Ingestion with OneRoster API in your test Microsoft 365 tenant to sync data from your sandbox OneRoster endpoints and ensure runs complete without errors. If you see any errors or warnings and need help after your self-investigation, contact your designated SDS engineer.

Customer pilot

Once testing has completed successfully, it's time to start piloting the solution with customers. Your system’s name will be visible in the list of OneRoster® providers in SDS for those “flighted” to also see providers that are ‘InPilot’ mode, having 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. We'll collaborate closely with customers to ensure the inbound flow runs are successful and validate the results together. Any final bugs identified are to be addressed prior to making the solution publicly available to all Office 365 education customers.

Go public

Once two customers have successfully completed their pilot deployments, the partner system will be available in SDS as a certified OneRoster provider source system. SDS will display the provider’s name to tenants when they're setting up Data Ingestion with OneRoster API. The SDS team will also document the partner system on our OneRoster API provider overview page in our SDS online documents.

The SDS team will need:

  • 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 coordinate with your team to promote the integration more broadly through various marketing channels.