How to deploy School Data Sync by using OneRoster® 1.1 API

OneRoster® is an Industry Standard format for exchange of Student Information System (SIS) data, and the OneRoster® REST APIs are the means by which we can sync objects from SISes that provide OneRoster® APIs to O365 through the SDS service. Using this sync method, you can connect directly to your SIS using the REST-based OneRoster 1.1 APIs provided by the SIS, and synchronize data directly instead of using CSV files. Using the OneRoster® API to ingest the data categories below enables you to light up core SDS capabilities for provisioning. It also allows you to enhance experiences for the Microsoft 365 (M365) products and features listed below.

core capabilities table for OneRoster API

To set up SDS using the OneRoster® Sync method, follow the instructions detailed in this article.

In this article:

Prerequisites

Before you start synchronizing with SDS using the OneRoster® Sync method, read the Overview of SDS and make sure you meet the following prerequisites:

  • An Office 365 for Education tenant

  • Global Admin Permissions

  • School Data Sync (Plan 1) enabled

    Note

    The data that you provide through SDS may be accessible to third party application providers through their apps, so you should sync only the data that you want to make available to these third parties.

Watch the Video

SDS Access and First Time Login

  1. To access the SDS Admin Portal launch a private web browser, navigate to sds.microsoft.com, and then sign in using your O365 Global Admin account.

Create a Sync Profile and Sync your SIS Data

  1. After logging in, click +Add Profile in the left hand navigation to create a sync profile.

Add profile

  1. On the Choose Connection Type page, choice OneRoster API and then choose your SIS integration provider from the “Choose your provider” drop-down menu. Once complete, select Start.

Choose Connection type

  • Name this profile - Enter a name for your sync profile. This name will be used to identify the sync profile in the SDS Dashboard, and cannot be changed once the profile setup is complete.
  • Choose your sync method - Choose between the available sync methods shown. If you're syncing using OneRoster, select Connect via an API sync method, and then select OneRoster 1.1 API for the service selection.
  1. On the Sync Options page, select the appropriate option to create new users or sync existing users. Then complete your selections on the page as appropriate.

Note

If running with option for creating new users and wish to adopt V2.1 CSV, we will be releasing tooling that will help you prepare to support V2.1 CSV format as part of your transition for back to school. Watch for follow-up announcements and postings to the SDS Docs repository at https://aka.ms/sdsoverview.

Sync options

  • Existing Users - Select this option if you already have user accounts created within your O365 tenant for each of the students and teachers contained within OneRoster.

  • New Users - Select this option if you want SDS to create user accounts for each of your students and teachers contained within OneRoster.

  • Web Access URL - This is the base URL for your PowerSchool SIS which is Internet accessible.

  • client Id - This is the client Id recorded in the Install the REST API plug-in for PowerSchool section of this article.

  • client secret - This is the client secret recorded in the Install the REST API plug-in for PowerSchool section of this article.

  • Select schools to sync - This option allows you to select the school you want to sync from OneRoster.

  • School properties - After uploading your CSV files, the attributes contained within your School.csv will be auto selected. You should validate the attributes selected here are the same attributes contained in your School.csv

  • Section Properties - After uploading your CSV files, the attributes contained within your Student.csv will be auto selected. You should validate the attributes selected here are the same attributes contained in your School.csv

  • Filter inactive properties - Checking this box will only sync active records.

  • Team Creation Option – Checking this box will ensure SDS creates both the Microsoft 365 Group and Class Team for each class synced. If you leave the box unchecked, SDS will only create the Microsoft 365 Groups.

  • Replace unsupported characters - Checking this box will automatically replace unsupported characters with supported ones.

  • Sync option for Section Group Display Name - Checking this box will allow teachers to control the section display name after the first sync, and prevent SDS from overwriting Section DisplayName changes made by teachers.

  • Sync to Insights - If you do not see the “Sync to Insights” option when creating your sync profile, you have not performed the setup as part of SDS for Insights. You will need to complete the setup for enabling “Sync organizational data (preview)" to sync the user metadata, roles, classes, and organizational hierarchy with Education Insights Premium. To do so, click on the link that says “To continue setup and monitoring navigate to SDS for Insights.”

Note

Sync to Insights is pending support for SIMS and Infinite Campus providers.

Note

At this time, single tenant with mixed formats (i.e. having V1 and V2 sync profiles actively running and both set to 'Sync to Insights') will not work.

  • Delay Student Access - Enabling this option will allow you to set a future date for students to view their classes. Disable this option to allow students to view their classes immediately.
  • When should we stop syncing this profile? - You will typically want to do this at the end of the school year. Once we stop syncing this profile, you will have the option to retire the classes associated with this profile.
  1. On the Teacher options page, select the appropriate identity matching options, confirm the teacher properties are selected, then click Next.

teacher options

  • Primary Key (Target Directory) - This is the user attribute in Azure AD used for SDS identity matching. Watch the identity matching video for additional information on how to select the appropriate target directory attribute, and properly configure the identity matching settings for the teacher.
  • Domain (optional) - This is an optional domain value that you can add to the selected source directory attribute to complete your teacher identity matching. If you need to match to a UserPrincipalName or Mail attribute, you must have a domain included in the string. Your source attribute must either include the domain already or you can append the appropriate domain to the source attribute using this dropdown menu.
  • Primary Key (Source Directory) - This is the teacher attribute in OneRoster used for SDS identity matching. Watch the identity matching video for additional information on how to select the appropriate source directory attribute, and properly configure the identity matching settings for teacher.
  1. On the Student options page, select the appropriate identity matching options, confirm the student properties are selected, and then select Next.

Student options

  • Primary Key (Source Directory) - This is the student attribute in OneRoster used for SDS identity matching. Watch the identity matching video for additional information on how to select the appropriate source directory attribute, and properly configure the identity matching settings for teacher.
  • Primary Key (Target Directory) - This is the user attribute in Azure AD used for SDS Identity Matching. Watch the Identity Matching video for additional information on how to select the appropriate target directory attribute, and properly configure the identity matching settings for the student.
  • Domain (optional) - This is an optional domain value that you can add to the selected source directory attribute to complete your student identity matching. If you need to match to a UserPrincipalName or Mail attribute, you must have a domain included in the string. Your source attribute must either include the domain already or you can append the appropriate domain to the source attribute, using the dropdown menu.
  1. On the Review page, ensure you have made the appropriate selections. If no additional changes are needed, click Create Profile.

Review page

Filtered State of OneRoster API

  • Students and enrollments – SDS syncs some students based on school association and status.

    • Synced
      • Active
    • Not synced
      • To be deleted
  • Teachers – SDS syncs some students based on school association and status.

    • Synced
      • Active
    • Not synced
      • To be deleted
  • Classes - SDS syncs some classes based on school association, and staff type.

    • Synced
      • Active
    • Not synced
      • To be deleted
  • Schools– SDS syncs some schools based on school association, and staff type.

    • Synced
      • Active
    • Not synced
      • To be deleted

    changes-to-filtering-powerschool.PNG

Video: How to match source and target attributes for sync

For various examples of matching logic success and failure for sync, watch the identity matching video:

Overview of SDS