OneRoster SIS Sync Setup Guide

Get started by reviewing the OneRoster FAQ to learn about what the sync does and if it will meet your needs. Setting up a sync takes a bit of effort, so it's best to understand what it can and can't do before you dive in.

Read each of the steps below before beginning the process. This will help insure you have the 'big picture' before you get too far.

Not all SISs are capable of producing the data file needed for a OneRoster based sync with Echo. Before taking any other steps, determin what is required to produce the OneRoster compliant upload file that will be used by the sync. The upload file will be a single .zip file containing the following seven files.

• manifest.csv   (defines what will be synced)
• academicSessions.csv   (defines the school year and terms)
• classes.csv    (defines the classes/sections/periods that teachers and students will be enrolled in)
• courses.csv   (defines the courses or subjects that are listed in the SIS)
• enrollments.csv   (associates a student or teacher with a course)
• orgs.csv   (defines the district and schools)
• users.csv   (defines the student, teacher or parent accounts)

NOTE: All seven files must be included in the OneRoster .zip file for the sync to run (even if they are not used and only include the headers). The .zip file should not contain any other files. Each .csv file must have the required headers according to the OneRoster specification, but the data rows may be empty if some data is not to be shared with Echo. The header fields must be provided in the correct order and are case sensitive. Refer to CSV Format for more details.

To learn more about the required .csv files, visit the IMS OneRoster: CSV Tables website. To see what data is used by the sync, see the Echo to OneRoster field map. To help you get started, you can download an example of the import file below. Also see Additional OneRoster SIS Sync Technical Information.

Before the sync is run in your live production environment, it is critical to test the sync in a temporary sandbox domain first. It is rare that the sync will work exactly as desired on the first run. It is much easier to wipe out a sandbox domain and start over than try to fix the damage to live data in a production domain.

Contact the Echo Support team (1) requesting a sandbox domain to run tests against, (2) identifying the person or persons who will be testing the sync.

You will be provide the following information:

• URL for the new sandbox domain
• Instructions for logging into the sandbox

..

The sandbox domain mimics your district domain in Echo. Because your sandbox empty, the first time the sync runs, it will create new subdomains for each school, new user accounts, new base and derivative courses and new enrollments. Although the ultimate goal is to automate the sync, during the first test, it's best to manually upload the data so that you can quickly verify it is accurately reflecting what you desire. If necessary, you can delete all imported data and run it again.

1. Configure the sync settings in the sandbox domain. If you have questions about the various configuration options, submit a support request through the Echo Help Desk.
2. Using the OneRoster export you created in Step Two, manually upload the OneRoster .zip file.
3. In Echo, verify the data.
   • Confirm subdomains were created for each school (no extra schools being synced). Adjust your orgs.csv file as needed.
   • Confirm teacher, student, and parent accounts are created in the correct domain(s). Parent accounts should be associated with the district organization so that their accounts are created in the district domain. Adjust users.csv file as needed.
   • Confirm users are granted appropriate permissions. Adjust sync settings as needed.
   • If courses are synced, confirm courses are created in the correct domains with correct start and end dates. Check to see that base courses are created and that the derivative classes are associated with the correct base course. Adjust sync settings, courses.csv, or classes.csv as needed.
   • If enrollments are synced, the correct students are enrolled in each course with the correct permissions and the correct enrollment start and end dates. Adjust enrollments.csv as needed.

NOTE:  It is very common to see issues when importing the data for the first time. Often, student information systems contain data not meant to be synced (old user accounts, unused placeholder courses, etc.). Echo is going to replicate everything that is shared with it through the .csv files in the OneRoser .zip file. You will likely need to clean up data in your SIS and/or make adjustments to what is exported by your SIS.

...

Once you are confident the data is syncing accurately with Echo, you may want to test the automated sync by configuring your student information system to use the FTP upload. You can find the FTP address in your SIS sync settings control panel.

In some cases, your SIS will have a built in FTP feature. In other cases, your will need to use a third party tool to upload the files to Echo's FTP site. To use FTP to upload, use the following:

• Open the district's domain URL
• Use the unique OneRoster account provided to you by the Echo team (userspace/username).
• Use the password provided by the Echo team for the OneRoster account.
• Use the FTP location/URL found in the SIS Sync tool

You can quickly confirm when the sync has ran by looking at the Status tab in the SIS Sync tool.

Although it is possible to enable the sync at anytime, we strongly recommend that you only do so between school years. By updating the existing user's External ID and then letting the sync create the new courses and enrollments, you can me more assured of a smooth implementation and users would still have access to prior courses.

To prepare your live environment for the sync:

1. Submit a support request to the Echo team for the following:
   • Update the External ID for the district and schools to match what was imported into the sandbox.
   • Update the SIS sync settings in the district domain to match what you configured in your sandbox domain.
   • Create a new OneRoster sync account in the district domain and grant it full Administrator permissions. This is important to prevent a disrupting in case the EA leaves the school and their account is deleted.
2. Update the External ID for all users to match what was imported into the sandbox. The sync will create new accounts for any students in your SIS that are not already in Echo.
3. If syncing to existing courses and enrollments, update the External ID for all courses and enrollments to match what was generated in the sandbox domain. NOTE: This is a lot of work and we don't recommend it. Better to wait until the new school year and allow the sync to create all new courses and enrollments.

As a final check, have the Echo Team conduct a review to confirm fields have been updated properly and that the sync is ready to run against production.

...

When existing data has been updated and verified by NTN to match imported data ...

1. Log into the district domain using the OneRoster Admin credentials provided by the Echo Team.
2. Update your SIS settings using the FTP address found in the SIS Sync control panel. They should match the configuration you set in the sandbox domain to insure it behaves the same as your testing.
3. Wait for the sync to run and verify the data (see Step Four for checklist).

...