Sync Parents and Guardian Contacts in SDS

Article
08/28/2024

Overview

School Data Sync (SDS) supports the ingestion of various data elements for the primary purposes of provisioning Microsoft 365 objects and entities, and for enabling and enriching Insights. One of the data elements supported for synchronization in SDS is parent and guardian data. This document describes the parent and guardian sync process, and the various use cases and considerations for syncing this data set into Microsoft 365.

Why do schools ingest parent and guardian contact data?

Parents app provides educators a list of all parent and guardian contacts for each class team they manage and sync via SDS. Parents app allows educators to reach out and communicate directly in Teams with any of the parent and guardian contacts on file with the school. To learn more, see Set up Parents app in Teams for Education.
Parents and guardians can use School Connection in Microsoft Teams to get actionable per-student overview and insights, including key callouts for assignments and monthly insights on homework turn-ins, digital activity, and reading progress. To learn more, see Set up School Connection.
When Weekly guardian email digest in assignments is enabled in Teams, the Assignments app sends emails each week to parents and guardians, containing a summary view of assignments from the previous week, and assignments for the upcoming week for each class.
Third-party app integrations: Parent and guardian contact data is available for third-party Applications via the relatedContacts API on MS Graph. Making the data available via Graph allows organizations to build and deliver their own experiences and use cases for the parent and guardian contact data.

Note

If your institution does not currentlly use SDS or have a way to supply parent and contacts data to SDS, Admins can enable educators with the capability of directly adding and updating parent information using the Parent App in Teams. See Set Up Parent Connection in Teams for EDU for additional details on the Admin steps.

What parent and guardian data is supported?

SDS supports ingesting basic contact information about parents and guardians, including:

First name
Last name
Email address
Phone number
ID
Role of the related contact
Related student ID

Where and how is the data stored in Entra ID?

SDS writes the parent and guardian data ingested to Substrate within a hidden data store on each student’s user object.
This basic contact data is NOT written as standard Mail Contacts in Exchange Online. This choice was to prevent all users in the tenant from seeing all parents and their related contact information upon SDS ingesting the data.
The data is only made available to Teams in Microsoft 365 for the first three scenarios noted previously, and also made available to third-party applications via the relatedContacts API on MS Graph. The API requires app-only permissions granted by the admin, which means end users within the tenant aren't allowed to query into MS Graph to see or access any of the parent and guardian contact data, protecting the privacy of the parents and guardians.

How do I sync parent and guardian data?

Synchronizing parent and guardian data in SDS is easy. This section explains how to sync parents and guardians based on your starting point and the sync method you use:

SDS v2.1 CSV files

If you're syncing data to SDS using the SDS v2.1 CSV format, you should include another csv file, relationships.csv. Therefore, you would need four CSV files in total: orgs.csv, users.csv, roles.csv, and relationships.csv.

The userSourcedId in the relationships.csv corresponds to the sourcedId value of the related student within the users.csv. The relationshipUserSourcedId attribute corresponds to the related parent within the users.csv file.
If you include phone number for parents and guardians, you should ingest the data within the E164 format, without any parenthesis or spaces, including the plus symbol at the front of the string. For example, format phone numbers as +[country code][area code][phone number], like +12223334444.
This format ensures the phone number is supported by School Connection (for access to parents via their phone number) and Parents app (for SMS-based invites to parents).
For any questions, contact us through Microsoft Education Support.

SDS v1 CSV Files

If you're syncing data to SDS using the SDS v1 CSV format, you should include two extra csv files, user.csv and guardianrelationship.csv.

OneRoster API

We have communicated guidance for general OneRoster API support to all current providers. You can help by following up and asking your provider to include support for including contacts data as part of their data integration. Share Onboarding Guidance for OneRoster API Providers for SDS article with your provider so they can update support and work with the SDS Deployment Engineering team to validate support and update their Profile.
To ingest via OneRoster API, based on the supported optional data capabilities from your provider, you see the toggle selected On (default) to Include contacts data.
- If the toggle is Off and unavailable to turn on, means that the provider’s profile doesn't currently support providing the optional data.
- After support is added by your provider, you can edit your configuration to select the toggle to On to include the data on the subsequent run.

Sending contact data with the Student user object

To write the contact data forward with the student user objects, you need to ensure your Manage data configuration has the Student contacts associations toggle to On to include the data on the subsequent run.

Parent and guardian roles

SDS supports various roles for parents and guardians, as listed below. Only the roles of parent and guardian are supported for Parents app. If you ingest any users with the other roles in SDS, they are not available within Parents app. If you intend for the person to appear and be available within Parents app, do not use one of these roles:

Relative
Aide
Doctor
Other

Status- active versus inactive

When SDS adds each parent and guardian to related contact collection on each student user’s hidden substrate data store, each parent and guardian is marked as active. If you remove a parent or guardian from the data to import on the next sync, they'll then be marked as inactive. This status can be viewed within the people page for each student in SDS. Only parents and guardians with an active status is shown as available within Parents App. SDS doesn't automatically delete parent and guardian records if you stop sending data in subsequent syncs. See the next section for details on how to delete parents.

Deleting parents

SDS adds all parents and guardians to the related contact collection on each student’s user object when they're ingested. When the student’s user object is deleted, so are all corresponding contacts SDS has stored over time. If you need to remove a related contact without deleting the student’s user object, the SDS team has published a PowerShell script to assist with this process. If you need assistance running the PowerShell script, you may reach out to our support team at https://aka.ms/sdssupport. Once the contact has been successfully removed from Substrate, be sure to remove the same parent, or guardian from all subsequent uploads to avoid adding them back into the directory.

Removing parent and guardian data

Parent and Guardian data is stored in the Azure substrate store. This location is difficult to access, requires application permissions, and is also restricted so that you can't remove a single entry. To remove a single Parent or Guardian that has been synced to a student, you must remove all records and then readd the records that you want to associate with the student.

These steps help you to run the following script and remove Parent and Guardian data.

O365-EDU-Tools/SDS Scripts/Reset-Guardians.ps1 at master · OfficeDev/O365-EDU-Tools (github.com)

Important

This script uses the Microsoft.Graph PowerShell module. It will not run in PowerShell ISE.

Creating a certificate

To run the script, you need to first create an application in Microsoft Entra ID and provide a certificate to access the information. Find the steps, commands, and self-signed certificate details in this article on creating a self-signed public certificate to authenticate your application.

Open PowerShell in administrator mode.
Navigate to the location you're working from. In this example, it's C:\TEMP\Reset_Guardians_Script.
Open the following page for steps on creating the command. Enter the first command, and remember to change the certificate name. We recommend using the Copy button to get the full command easier.
In this example, we set the certificate name to parentResetScript.
Change the folder location before running the command.
In this example, we use the same folder that we’re currently in.

Creating an application

The application is how we determine the permissions and access for the script.

Navigate to the Microsoft Entra ID admin center and then Identity | Applications |App Registrations.
Select New registration to begin the creation process.
Enter a name for the application. In this example, it's Parent Reset Application. We don't need to fill out any other settings on this page.
Copy and save the Application (client) ID. It's used to run the script later.
Select API permissions under Manage.
Select Add a permission.
Select Microsoft Graph.
Select Application permissions.
Search for and select user.ReadWrite.All and EDURoster.ReadWrite.All and select Add permissions at the bottom once both are selected.
Select Grant admin consent for (tenant name) and confirm.
Navigate to Certificates & Secrets on the left side under Manage.
Select the Certificates tab and then Upload certificate.
Navigate to the certificate that we created in the first stage.
Select Add.
Lastly, copy the thumbprint.

Running the Reset_Guardians.ps1 script

To run the script, you need your tenant ID and the script that can be found here: O365-EDU-Tools/SDS Scripts/Reset-Guardians.ps1 at master · OfficeDev/O365-EDU-Tools (github.com)

To locate your Tenant ID, go to the Overview tab in Microsoft Entra ID.
Open the GitHub repository and download the script. In this example, it's downloaded to the same folder that contains the certificate.
This script can be run in several ways. If you open the script using a text editor like Notepad, you can see the different methods that can be used. In this example, we run it against all students.

To run the script, you can copy the last example and replace the fields with our new application information and tenant ID.

\Reset-Guardians.ps1 -clientId "{Application (client) ID}" -certificateThumbprint "{Certificate Thumbprint}" -tenantId "{Tenant ID}" ## Replace the field including the { }

After you hit enter, type R and hit enter. If done correctly, the script connects to Graph and begin extracting the students and begin the removal process. The more students, the longer the script takes to run.
Once all students are extracted, it asks to confirm the removal of the Parent and Guardian data. To proceed, type y.
Here's a sample of how the script appears when it's removing the data.