How to deploy School Data Sync by using PowerSchool SIS API

Important

School Data Sync (Classic) experience will be replaced by the new School Data Sync experience by the end of 2024. We advise that you start planning your transition to the new experience for your next year Back to School.

PowerSchool is a Student Information System (SIS) that integrates with School Data Sync (Classic). Using the PowerSchool API sync method, you can connect directly to your SIS using REST-based APIs, and synchronize data directly instead of using CSV files. Using the PowerSchool API to ingest the data categories highlighted, it enables you to light up core SDS (Classic) capabilities for provisioning. It also allows you to enhance experiences for the Microsoft 365 (Microsoft 365) products and features listed.

Screenshot of core capabilities enabled when using PowerSchool API.

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

Prerequisites

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

  • An Office 365 for Education tenant
  • Global Admin Permissions

Watch Deployment Video

Also refer to the following video for user identity matching.

Install the REST API plug-in for PowerSchool

Before SDS (Classic) can access data from your PowerSchool SIS, you must install the application plug-in within PowerSchool and obtain OAuth credentials.

  1. On your local computer, create an XML plug-in installation file using notepad by copying the following content. Save the file as "plugin.xml".

    <?xml version="1.0" encoding="UTF-8"?>
    <plugin xmlns="http://plugin.powerschool.pearson.com"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://plugin.powerschool.pearson.com plugin.xsd"
    name="Microsoft School Data Sync"
    version="1.0.0"
    description="Plugin for Powerschool REST API for Microsoft SDS">
    <oauth></oauth>
    <publisher name="Microsoft Corp.">
    <contact email="sdshelp@microsoft.com" />
    </publisher>  
    </plugin>
    
  2. Sign in to the PowerSchool admin portal website using your System Administrator credentials.

  3. On the start page, choose System from the main menu, then go to System Settings > Plug-in Management Configuration > Install

  4. Enter or select the plug-in installation file you created (.xml), and then choose Install. The plug-in appears in the Installed Plug-ins section on the Plug-in Management Dashboard page. Make sure the plug-in is enabled. If it isn't, choose the Enable option on the Plug-in Management Dashboard page.

  5. On the Plug-in Management Dashboard page, make sure that the plug-in is enabled.

  6. Choose Data Configuration to view the OAuth credentials that were generated for the plug-in.

  7. Record the values for the Client ID and Client Secret so you can enter these credentials when you create your sync profile.

Data Accessed by School Data Sync (Classic)

Important

By connecting and making institution data available with School Data Sync (Classic), you acknowledge that you are authorized to share this data with Microsoft and commit to adhere to your organization’s data governance standards.

Following are the Microsoft URL requests and PowerSchool responses (as of June 1, 2023). These may change in the future.

Microsoft URL Request

~/ws/v1/district/school?page{1}&pageSize={100}

~/ws/v1/school/{id}

PowerSchool Response

    { 
     "school": { 
       "@expansions": "school_boundary, full_time_equivalencies, school_fees_setup", 
       "id": , 
       "name": "", 
       "school_number": , 
       "low_grade": , 
       "high_grade": , 
       "alternate_school_number": , 
       "addresses": { 
         "physical": { 
         "street": "", 
         "city": "", 
         "state_province": "", 
         "postal_code": "" 
        } 
      }, 
      "phones": { 
        "main": { 
        "number": "" 
        } 
      }, 
      "principal": { 
      "name": { 
        "first_name": "", 
        "middle_name": "" 
        } 
      } 
     } 
    } 

Make sure the REST endpoints are Internet accessible

SDS (Classic) must be able to reach your PowerSchool server. To make sure the server is accessible, open ports 80 and 443 from the Internet to your PowerSchool server.

To validate that the endpoints are set correctly, check that you can open the PowerSchool server website pages from the Internet. For example, in your browser, go to https://PowerSchool.com/public/. If that doesn't work, contact PowerSchool support.

About Microsoft Entra Connect deployment warnings

If you're configuring SDS (Classic) for a tenant, which is synchronized from on-premises active directory through Microsoft Entra Connect, you may notice an increase in the number of disconnectors shown in your misclient. This is a result of Microsoft 365 group being unable to sync back to the Microsoft Entra Connect Metaverse and on-premises active directory. These warnings don't have any negative impact on your current Microsoft Entra Connect deployment, and only provide an informational note on the resultant sync failure. You should expect these warnings in Microsoft Entra Connect after enabling sync in SDS (Classic). One Microsoft 365 group is created for each class synchronized through SDS (Classic).

Synchronize your SIS data using the PowerSchool API sync method

After you've installed the plug-in and set up access, create a sync profile in SDS (Classic) to synchronize your information.

SDS Access and First Time sign-in

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

Create a sync profile and sync your SIS data

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

    Screenshot of adding a new sync profile.

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

    Screenshot of choosing connection type screen.

    • Name this profile - Enter a name for your sync profile. This name is used to identify the sync profile in the SDS (Classic) Dashboard, and can't be changed once the profile setup is complete.
    • Choose your sync method - Choose between the sync methods shown. If you're syncing using PowerSchool API, select the Connect via an API box, and then select the PowerSchool API option.
  3. 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 have released a tool that will help you prepare to support V2.1 CSV format as part of your transition for back to school. See update anchor IDs before creating users.

    Screenshot showing sync options.

    • Existing Users - Select this option if you already have user accounts created within your Microsoft 365 subscription for each of the students and teachers contained within PowerSchool.
    • New Users - Select this option if you want SDS (Classic) to create user accounts for each of your students and teachers contained within PowerSchool.

    Note

    If a student or teacher has a username within PowerSchool, SDS (Classic) will attempt to use that to generate an account. If that username is not available then it will create one in the following format: s-<firstName>.<lastName>.<SIS ID>@<selectedDomain>

    • 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 PowerSchool.
    • School properties - Select the School attributes you would like to be included.
    • Section Properties - Select the School attributes you would like to be included.
    • Filter inactive properties - Checking this box will only sync active records.
    • Team Creation Option – Checking this box ensures 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.
    • 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'll typically want to do this at the end of the school year. Once we stop syncing this profile, you can retire the classes associated with this profile.

    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.

  4. On the Teacher options page, select the appropriate identity matching options, confirm the teacher properties are selected, then select Next.

    Screenshot showing teacher options.

    • Primary Key (Target Directory) - This is the user attribute in Microsoft Entra ID 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 the dropdown menu.
    • Primary Key (Source Directory) - This is the Teacher attribute in PowerSchool 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.
  5. On the Student options page, select the appropriate identity matching options, confirm the student properties are selected, and then select Next.

    SDS checks to ensure you're selecting attributes and options within the correct format. If matching a UserPrincipalName for example, you must select a source directory attribute, which is in the format of a UserPrincipalName (prefix@domain.com) or you must choose to append a domain to the source directory attribute to ensure proper formatting. If your selections aren't in the proper format to complete a match, you'll see a red error displayed on the page.

    Screenshot showing student options.

    • Primary Key (Source Directory) - This is the student attribute in PowerSchool 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.
    • 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.
    • Primary Key (Target Directory) - This is the user attribute in Microsoft Entra ID 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.
  6. On the Review page, ensure you have made the appropriate selections. If satisfied, select Create Profile.

    Screenshot showing review page.

Filtered State of PowerSchool SIS API

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

    • Synced
      • Pre-enrolled
      • Active
    • Not Synced
      • Graduated
      • Dropped out
      • Transferred out
  • Teachers – SDS syncs some teachers based on school association, and staff type.

    • Synced
      • Teacher
      • Substitute
    • Not Synced
      • Lunch Staff
      • Staff
      • Not Assigned
  • Classes and Schools - SDS syncs all within the selected school year.

    Screenshot showing filter options.

Video: PowerSchool API Deployment

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: