How to deploy School Data Sync (Classic) by using OneRoster 1.0 CSV files

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.

You can use Comma Separated Value (CSV) files with School Data Sync (SDS) to import and synchronize your Student Information System (SIS) data to Office 365. SDS can sync students, teachers, schools, sections, and roster information from your SIS to Microsoft Entra ID and Office 365. Using this method, you'll export or create OneRoster CSV files for School Data Sync from your SIS data, set up a synchronization profile, and upload the CSV files into SDS for processing.

In this article:

Before you get started

Before you start synchronizing with SDS using the CSV Import method, read the Overview of SDS. Also, to complete this process, you must install the Microsoft SDS Toolkit. This tool helps you to convert your CSV export, add, and update your users that are synced between SIS and Office 365, and can also be used to verify the CSV file data. For details, see Install the SDS Toolkit

Make sure you meet the following prerequisites:

  • An Office 365 for Education tenant

  • Global Admin credentials

  • 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.

Convert your OneRoster 1.0 CSV files to the SDS Format

Before you can create an SDS sync profile and import your CSV files, you must first convert your OneRoster format CSV files into the SDS format. Follow the steps below to complete this conversion process.

  1. Save your OneRoster 1.0 CSV files in your C:\temp directory.

  2. Install the SDS toolkit.

  3. Create a subfolder called c:\temp\csvs.

  4. Create a subfolder called c:\temp\sdslogs.

  5. Run the Convert-OneRosterToMicrosoftSDS command, using the syntax below:

    Convert-OneRosterToMicrosoftSDS -onerosterfolderpath "c:\\temp" -sdsfolderpath "c:\\temp\\csvs" -logpath "c:\\temp\\logs"
    
  6. Go to your c:\temp\csvs directory and verify the new SDS converted files are present.

Create a sync profile and import your converted CSV files

Follow the steps below to import your converted files and create your sync profile. A sync profile is a logical group of options and settings used by SDS to synchronize the CSV data, which you plan to upload. You can create multiple sync profiles within a single Office 365 tenant.

SDS Access and First Time sign-in

  • To access the SDS Admin Portal, launch a web browser, navigate to sds.microsoft.com, select Sign In, and then enter your Microsoft 365 Global Admin account credentials.

Create a Sync Profile and Upload your OneRoster 1.0 CSV files

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

    Add profile.

  2. On the Choose Connection Type page, complete the form as appropriate. Once complete, select Start.

    Choose Connection Type.

    Note

    There is no option for OneRoster CSV. If you are using the OneRoster file format, choose CSV files: SDS format.

  3. On the Sync Options page, select the appropriate option to create new users or sync existing users. Then select Upload Files to upload your six SDS CSV files. Once uploaded, complete your selections on the page as appropriate and select Next.

    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.

    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 your CSV files.

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

    • Upload Files button - select this button to upload your six CSV files. Upon upload SDS will perform some brief validation tests to ensure the files are formatted correctly. If the validation passes, your files will be uploaded into the sync profile.

    • 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

    • 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 special characters- Checking this box will allow SDS to automatically replace unsupported special characters while the sync is running. Special characters will be replaced with an "_", and no longer result in an error during the sync process for that object.

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

    • Delay Student Access - Enabling this option will allow you to set a date for SDS to synchronize memberships and enabled students to view their classes. Disable this option to sync students immediately.

    • When should we stop syncing? - You'll typically want to do this at the end of the school year or term. Once SDS stops syncing the profile, you'll have the option to clean up the classes associated with this profile, as appropriate.

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

    SDS will check 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.

    teacher options.

    • Primary Key (Source Directory) - This is the teacher attribute in the CSV file 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 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.

  5. On the Student options page, select the appropriate identity matching options, confirm the student properties are selected, and then select Next.

    SDS will check 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.

    Student options.

    • Primary Key (Source Directory) - This is the student attribute in the CSV file 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 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.

    • 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 this dropdown menu.

  6. On the Review page, ensure you have made the appropriate selections. If no additional changes are needed, select Create Profile. Once you create a sync profile, SDS will begin a pre-sync validation process. If any errors are found during this process, you'll have the option to fix them and re-upload files before clicking the resume sync button and starting the real synchronization process. If you receive errors and choose not to update them, you can still choose to resume sync without addressing the errors.

    Review page.

To help automate the sync process after setting up your sync profile, you can Install the SDS Toolkit. This tool helps you to create an automated sync schedule between OneRoster CSV files and Office 365, and can also be used to verify the CSV file data. For details, see Install the Microsoft School Data Sync Toolkit.

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

OneRoster CSV files for SDS

How to deploy SDS using CSV files in the CSV v2.1 format

How to deploy SDS using CSV files in the CSV V1 format

How to deploy SDS using CSV files in the CSV V2 format

How to deploy SDS by using CSV files in the Clever format

SDS Errors