Install the School Data Sync Toolkit

Article
02/21/2023
8 minutes to read

Note

This toolkit will be deprecated soon. We suggest you upload your CSV files using the SDS Flow Connector. Detailed instructions can be found at CSV File Sync Automation. Also, this toolkit will not work with V2.1 CSV files.

You can use the School Data Sync Toolkit to validate your CSV files and check for errors, perform a manual CSV sync from PowerShell, and automate the CSV sync process to meet your needs.

In this article:

Install the Microsoft School Data Sync Toolkit

Download the tool from Microsoft School Data Sync Toolkit
Double-click the tool to run the wizard.
On the Welcome page, choose Next.
Accept the license agreement > select Next, choose an installation path, and then choose Next.
Choose Install > Finish.

Capabilities of the School Data Sync Toolkit

After you've installed the toolkit and your initial profile has been created in the School Data Sync Portal, you can use the following script to upload more CSV files on a regular or as-needed basis. The installer allows you to run several cmdlets from an admin PowerShell session on your computer, to help you deploy School Data Sync successfully. See the following sections for a description and use case for each cmdlet.

Note

You will need to install a specific version of AzCopy for the file uploads to work. The link to the AZCopy installer is here.

Use the School Data Sync Toolkit to validate CSV file data (Pre-sync)

To use the toolkit to validate CSV files before you upload the files for synchronization, open PowerShell as an Administrator and use the Start-CsvFilesValidation cmdlet as described by the following syntax and examples.

Start-CsvFilesValidation syntax

Use the Start-CsvFilesValidation cmdlet to validate CSV files for a given sync profile.


Start-CsvFilesValidation -CsvFolderPath <String> -ProfileName <String> -UserName <String>

Parameter	Description
CsvFolderPath	Path to the folder containing the CSV files.
ProfileName	Name of the profile you've created in School Data Sync for the CSVs you want to validate.
UserName	User name of the admin account with Global admin rights for the Office 365 tenant.

The following example performs client-side validation of CSV files located in the c:\temp directory of the local computer, for a profile called "School 1", using the global admin account of admin@contoso.com.

Start-CsvFilesValidation -CsvFolderPath "c:\temp" -ProfileName "School 1" -UserName admin@contoso.com

Use the School Data Sync Toolkit to sync CSV files

To upload and sync CSV files with School Data Sync, open PowerShell as an Administrator and use the Send-CsvFiles cmdlet as described by the following syntax and example.

Send-CsvFiles syntax

Use the Send-CsvFiles cmdlet to upload and sync CSV files for a given sync profile.


Send-CsvFiles -CsvFolderPath <String> -ProfileName <String> -UserName <String>

Parameter	Description
CsvFolderPath	Path to the folder containing the CSV files.
ProfileName	Name of the profile you've created in School Data Sync for the CSVs you want to validate.
UserName	User name of the admin account with Global admin rights for the Office 365 tenant.

The following example uploads and syncs a set of CSV files located in the c:\temp directory of the local computer, for a profile called "School 1", using the global admin account of "admin@contoso.com.


Send-CsvFiles -CsvFolderPath "c:\temp" -ProfileName "School 1" -UserName "admin@contoso.com"

Use the School Data Sync Toolkit to configure automated CSV sync

You can schedule unattended automated syncs between your CSV files stored locally and your SDS Sync Profile in Office 365. To do this, open PowerShell as an Administrator and use the Add-CsvFileSyncTask cmdlet as described by the following syntax and examples. After the scheduled task is complete, you can monitor the progress and history of these automated syncs by reviewing the newly created scheduled task in Task Scheduler. This scheduled task will run daily at midnight, unless you modify the start time using the parameter below.

When you run this command, you'll be prompted to authenticate. The first authentication prompt will require your Global Admin credentials and will already contain the username you specify in the command below, under the username parameter. After you enter your password and select Enter, you'll then receive a second, basic authentication prompt. Here you should enter the local administrator username and password, which will be the credentials used to run the scheduled task, each time it starts daily. If you include the StoreCredentials parameter, the local administrator account credentials will be stored in Credential Manager, and continue to work as long as the password remains unchanged. If you don't specify the StoreCredentials parameter, you'll be granted an auth token, which has a maximum lifetime of 90 days. This will require that you run the command again after the auth token expires and is no longer able to authenticate while running the scheduled task.

Add-CsvFileSyncTask syntax

Use the Add-CsvFileSyncTask cmdlet to upload and sync CSV files for a given sync profile.


Add-CsvFileSyncTask -CSVFolderPath <path to csv file location> -ProfileName <name of sync profile in SDS> -LogPath <path to store logs> -UserName <global admin account> -Validate -RedirectOutput

Parameter	Description
CSVFolderPath	Path to the folder containing the CSV files that will be regularly synced.
ProfileName	Name of the SDS Sync Profile you're syncing the CSV Files against.
UserName	UserPrincipalName of the Global Admin Account to be used with SDS.
LogPath	Path to the directory where you would like to store your validation log files.
RedirectOutput	Will allow the output of the validate parameter to be written out to the specified directory. This is required if you want to review the results of the validate parameter.
Validate	Run the validation task prior to each sync. Creates a file in the Logpath directory if the RedirectOutput parameter is also included.
TaskUserName	Username of the local administrator on the system.
TaskStartTime	Time of day the scheduled task will begin.
StoreCredentials	Creates an entry in Credential Manager to run the scheduled task. The credential remains valid and continues to work, unless the password associated with this account expires.

The following example creates an automated sync scheduled task for CSV files located in the C:\temp folder, on a sync profile called SDSSync, creates validation log files in the C:\temp\logs folder, and sets the C:\temp\SDS\Logs directory as the location for all log files generated. This command also runs the validation process for the CSVs before the sync begins and saves the validation output in the same c:\temp\logs directory.

Add-CsvFileSyncTask -CSVFolderPath "C:\temp" -ProfileName "SDSSync" -LogPath "C:\temp\\logs" -UserName admin@contoso.com -Validate -RedirectOutput

Use the School Data Sync Toolkit to convert OneRoster CSV files

You can use the Toolkit to convert OneRoster CSV Files and sync them with School Data Sync. To do this, open PowerShell as an Administrator and use the Convert-OneRosterToMicrosoftSDS cmdlet as described by the following syntax and example. After the conversion is complete, you can then sync those CSV files through SDS, following our standard CSV sync guidance.

Convert-OneRosterToMicrosoftSDS syntax

Use the Convert-OneRosterToMicrosoftSDS cmdlet to upload and sync CSV files for a given sync profile.

Convert-OneRosterToMicrosoftSDS -OneRosterFolderPath <String> -SDSFolderPath <String> -LogPath <String>

Parameter	Description
OneRosterFolderPath	Path to the folder containing the CSV files exported from OneRoster.
SDSFolderPath	Path to the folder where the converted CSV files will be created.
LogPath	Path to the folder where you want logging stored on these actions.

The following example converts a set of OneRoster CSV files located in the C:\temp\OneRoster folder, creates a new set of CSV files located in the C:\temp\SDS directory of the local computer, and sets the C:\temp\SDS\Logs directory as the location for all log files generated.

Convert-OneRosterToMicrosoftSDS -OneRosterFolderPath "C:\temp\\OneRoster" -SDSFolderPath "C:\temp\\SDS" -LogPath "C:\temp\\SDS\\logs"

Use the School Data Sync Toolkit to validate CSV file data (Post-sync)

To use the toolkit to validate CSV files after you upload and sync a set of CSV files, open PowerShell as an Administrator and use the Compare-DirectoryToCSVFiles cmdlet as described by the following syntax and examples.

Compare-DirectoryToCSVFiles syntax

Use the Compare-DirectoryToCSVFiles cmdlet to validate CSV files for a given sync profile.


Compare-DirectoryToCSVFiles -CsvFolderPath <String> -ProfileName <String> -UserName <String>

Parameter	Description
CsvFolderPath	Path to the folder containing the CSV files.
ProfileName	Name of the profile you've created in School Data Sync for the CSVs you want to validate.
UserName	User name of the admin account with Global admin rights for the Office 365 tenant.

The following example performs client side validation of CSV files located in the c:\temp directory of the local computer, for a profile called "School 1", using the global admin account of "admin@contoso.com".


Compare-DirectoryToCsvFiles -CsvFolderPath "c:\temp" -ProfileName "School 1" -UserName "admin@contoso.com"

Troubleshooting: Unable to run the Automated Sync within the School Data Sync Toolkit

Step 1. Delete the task in task scheduler.

Step 2. Open PowerShell as an administrator and run:


Add-CsvFileSyncTask -CSVFolderPath “path to csv file location” -ProfileName “name of sync profile in SDS” -LogPath “path to store logs” -UserName “global admin account” -RedirectOutput

Step 3. If errors occur, download the newest AZCopy from here.

Step 4. Attempt to run the above command again.

Step 5. After the command runs, go to the Task Scheduler, and open the task and verify within the logs.

Overview of School Data Sync

CSV files for School Data 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 CSV files in the Clever format

How to deploy School Data Sync by using OneRoster CSV files

SDS Errors

SDS Troubleshooting