How to deploy School Data Sync by using OneRoster CSV files

Note: 

You can use OneRoster Comma Separated Value (CSV) files with School Data Sync (SDS) to import and synchronize your Student Information System’s (SIS) student, teacher, school, section, and roster information with Office 365. To deploy SDS using this sync method, export CSV files in the OneRoster format from your SIS, convert them into School Data Sync’s required format using our toolkit, and then upload the files into School Data Sync and Azure AD.

In this topic:

Before you get started

Before you start synchronizing with SDS using CSV Import, read the Overview of School Data Sync and Classroom.

To complete this process, you must install the Microsoft School Data Sync 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 Microsoft School Data Sync Toolkit.

Make sure you meet the following prerequisites:

  • An Office 365 for Education tenant.

  • Global Admin Permissions

  • The CSV files cannot contain any characters shown in this list of invalid characters.

  • The CSV files cannot contain more than 500,000 rows of data. If any of the CSV files exceed the 500K row limit, split off the additional rows into another set of 6 CSV Files, and create an additional sync profile to upload and sync those additional objects and attributes.

If you are configuring School Data Sync for a tenant which is synchronized from on-premises Active Directory through AADConnect, you may notice an increase in the number of Disconnectors shown in your miisclient. This is a result of Office 365 Group being unable to synchronize back to the AADConnect Metaverse and on-premises Active Directory. These warnings do not have any negative impact on your current AADConnect deployment, and only provide an informational note on the resultant sync failure. You should expect these warnings in AADConnect after enabling sync in SDS, as one O365 Group is created for each class synchronized through SDS.

Note: The data that you provide through School Data Sync 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.

Import your CSV files to create your profile

Make sure you've exported your CSV files in the OneRoster format and they're ready to use. Then follow these steps to convert the files and create your sync profile.

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

  2. Install the School Data Sync 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.

  7. In your web browser, go to sds.microsoft.com, and sign in using global admin credentials for your Office 365 Education tenant.

  8. If this is your first time signing in and setting up a profile, you must choose to enable/disable SDS and Microsoft Classroom. To enable School Data Sync and proceed with the setup, toggle the School Data Sync switch to the On position.

    Screenshot of Settings in School Data Sync, to turn School Data Sync on or off.

    After you've enabled School Data Sync setup, choose Add Profile to create an SDS Sync Profile and begin syncing data from your SIS.

    Screenshot of Add Profile option in the menu of School Data Sync.
  9. Type a profile name in the Enter a name for your profile box.

    Screenshot of Enter a name for your profile, during Add Profile in School Data Sync
  10. In the Data Extraction section, select CSV Files in the Select data source drop-down menu.

    Screenshot of Data extraction options, during Add Profile in School Data Sync
  11. In the Data Extraction section, select either Create new users or Sync existing users.

    Screenshot of options for the profile to create and sync new uers data, or sync data for existing users, during Add Profile in School Data Sync
    • Create new users Select this option if you are not syncing identities from your on-premises Active Directory, or the users in scope for sync are not created within Microsoft Azure Active Directory already. This option will create new user accounts for users within the student and teacher CSV Files.

    • Sync existing users Select this option if you are syncing identities from your on-premises Active Directory, or the users in scope for sync are already created in Azure AD. This option will not create new user accounts for users within the student and teacher CSV Files.

  12. If you selected the Create new users option, skip this step. . If you selected the Sync existing users option, select the appropriate Identity matching options from the available drop-down menus. This is where you'll define how to match students and teachers from your CSV files to their user accounts in Office 365. Watch the Identity Matching video for additional information on how to select the appropriate source, suffix, and target values, and properly configure the identity matching settings listed below.

    Identity Matching Options - Students and Teachers

    Screenshot of three settings to sync students in School Data Sync, including source property, suffix, and target property.

    Screenshot of three settings to sync teachers in School Data Sync, including source property, suffix, and target property.

    Select source property This drop-down menu allows you to select the source property from your CSV files, to be used for Identity Matching.

    • Secondary Email Secondary Email attribute in your CSV files (ex: JohnSmith@contoso.com)

    • Student Number Student Number attribute in your CSV files (ex: 1234567)

    • Username Username attribute in your CSV files (ex: JohnSmith or JohnSmith@contoso.com)

    Select suffix This drop-down menu allows you to append a domain suffix to the source property selected. All domains added to your tenant will be listed.

    Select target property This drop-down menu allows you to select the target property within Office 365, to complete the match between source and target.

    • UserPrincipalName Logon name of the user (ex. JohnSmith@contoso.com)

    • Mail PrimarySmtpAddress of the user (ex. JohnSmith@contoso.com)

    • mailNickname Exchange Alias of the user (ex. 1234567)    

  13. After the Profile Name, Data Extraction Options, and Identity Matching Options are set in place, choose Next.

  14. On the Directory options page, select the appropriate domain for each drop-down list available. If you selected the Sync existing users option in step 11, you will only need to select the appropriate domain for Schools and Sections because all existing students and teachers already have domains associated with their respective user accounts. This domain will be used as the domain suffix for the Office 365 Group created for each section, unless policy is in place to override this domain setting. You may also assign Classroom licenses to all users within the scope of sync, by checking the Assign Microsoft Classroom licenses checkbox. If you would like to allow SDS to maintain control of the Section/Group display names in O365, do not select the Sync option for Section Group Display Name checkbox. If you prefer that SDS create the group's Display Name based on the initial SDS sync, but allow the teachers to overwrite and maintain a custom display name after the first sync completes, check the second checkbox.

    Screenshot of domain selection for the sync profile, and checkboxes to assign Microsoft Classroom licenses and Section Group Display Name in School Data Sync

    If you selected the Create new users option in step 11, you will need to select the appropriate domain for Schools and Sections, in addition to a domain for teachers, and a domain for students, as shown below. This domain will be used as the domain suffix for the user account created by SDS, for each user included in the student and teacher csv files.

    Only one domain can be entered for teachers, and one domain for students within a single sync profile. If you have objects of those types which must be spread across multiple domains, you'll have to create a separate profile for each set of users (one sync profile per domain).

    Screenshot of domain selection for schools/sections, teachers, and students in School Data Sync
  15. If you selected the Create new users option in step 11, you also must select the appropriate SKU to assign to each of the newly created Teachers and Students using the drop-down menus shown below. Each available SKU in your Office 365 tenant will be present in the list. You can also choose to license each of these users for Classroom, by checking the checkbox shown below. After you've completed this section of the setup wizard, choose Next.

    Screenshot of SKU and license selection for new users in School Data Sync
  16. On the Select properties to sync page, select each of the attributes you plan to sync (required and optional) for each CSV file. Each attribute selected on this page should correlate to each attribute header field included in your CSV files. CSV files for School Data Sync details the required attributes (in grey) and optional attributes available for sync, and the formatting requirements for each CSV file. After all of the appropriate attributes are selected on this page, choose Next.

    Screenshot of categories of properties to sync in the School Data Sync profile
  17. On the Summary page, choose Submit to create the profile.

  18. Under the Profile Collection section of the SDS Portal, select the profile you just created.

  19. Choose Upload Files so you can choose and upload your CSV files.

  20. Choose Add Files to select your CSV files to upload, and then choose Upload.

    Screenshot of dialog box to upload selected files into the sync profile.

    During the upload process, the CSV files will be validated. If there are errors, they'll be listed so you can correct them and try again.

  21. After the files are uploaded select the Start Sync option to begin syncing the CSV data to Azure AD

    Screenshot of completed profile options on dashboard of School Data Sync, including option to Start Sync

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.

Your browser does not support video. Install Microsoft Silverlight, Adobe Flash Player, or Internet Explorer 9.

See Also

Overview of School Data Sync and Classroom

CSV files for School Data Sync

School Data Sync required attributes for PowerSchool Sync

How to deploy School Data Sync by using CSV files

How to deploy School Data Sync by using PowerSchool Sync

How to deploy School Data Sync by using Clever Sync

School Data Sync errors and troubleshooting

Connect with an expert
Contact us
Expand your skills
Explore training

Was this information helpful?

Thank you for your feedback!

Thank you for your feedback! It sounds like it might be helpful to connect you to one of our Office support agents.

×