This article describes how to configure Echo to receive and process OneRoster files to automatically sync with your school's student information system. Before initiating a sync, please read the OneRoster Sync FAQ document to learn more about how it works and what to expect.
Steps for Initiating a OneRoster SIS Sync
- Contact Echo Support
- Decide what will by synced
- Export and format SIS data
- Configure SIS Sync Settings (Sandbox)
- Manually upload OneRoster sync data (Sandbox)
- Verify data in Echo (Sandbox)
- Prepare For Syncing Live Data (Production)
- Manually upload OneRoster sync data (Production)
- Verify data in Echo (Production)
- Automate Sync using FTP
Step 1: Contact Echo Support
The first step in setting up a OneRoster SIS Sync is letting Echo Support know you are planning to do it. In response, the Echo team will:
- Discuss what the sync will and won't do for you
- Set up a sandbox domain for testing and verifying the SIS data is coming over correctly
- Create a special Admin account in the sandbox to be used by the sync
- Create a special Admin account in production to be used by the sync
Step 2: Decide What Will Be Synced
Because the OneRoster SIS Sync is full dependent on the data uploaded from the SIS, deciding what will be shared with Echo is important.
- Schools: If only some schools in the district are using Echo, filtering data from schools that aren't using Echo will prevent unnessessary data from being shared with Echo and will ensure that your district is creating Echo users outside the license limit of the contract with NTN.
- Users: Sharing user data will automatically create new user accounts when new students, teachers, or parents are added to the SIS. Teachers still have the flexibility to create their own course structure in Echo and use course enrollment codes to easily add students to their courses.
- Courses: Sharing course data will automatically create all courses for the teachers. Teachers will lose control over things like the base/derivative structure and course naming. Enrollment codes can be used to avoid manually enrolling students.
- Enrollments: Sharing enrollment data automatically enrolls and withdraws students in courses. This requires that course sync has also be enabled.
Step 3: Export And Format SIS Data
In order to be universally compatible, the One Roster standards are specific and inflexible. In some cases, SIS have built in reporting tools that are aligned to the standards. In other cases, an SIS administrator can create custom reports that meet the standard. Echo support OneRoster v1.1
Echo requires the following .csv files to included in a .zip file for uploading.
- manifest.csv (defines the list of included files and how they will be processed)
- orgs.csv (defines the list of schools in the district)
- users.csv (defines the list of users that will be synced with Echo)
- academicSessions.csv (defines the school year and grading periods)
- courses.csv (defines the list of course offerings)
- classes.csv (defines the list of specific class sections)
- enrollments.csv (defines the staff and student enrollments)
NOTE ABOUT PARENT ACCOUNTS: If you are syncing data from multiple schools, parent/guardian accounts should be associated with the district organization. This allows parents to log into one place and view all of their student's grades even if they are in different school. This is accomplished by modifying the orgSourcedId data in the users.csv file to be the district's SourcedId.
Step Four: Configure SIS Sync Settings (Sandbox Domain)
Echo's OneRoster SIS Sync feature has several configuration options so that users, courses and enrollments are created and managed correctly for your school. If there multiple schools in your district that use Echo, these settings should be configured in the district domain.
To learn more about the configuration options and how to change them, see "How do I configure OneRoster SIS Sync Settings".
Step Five: Manually Importing OneRoster File
To test the data export and sync configurations, manually upload a OneRoster file.
- Compress the seven .csv files from step three into a single OneRoster.zip file.
- Open the SIS Sync tool
- Click CHOOSE FILE.
- Find and select the .zip file for upload.
- Click START SYNC. Your first sync should begin shortly after upload.
- Click the Status tab to check sync successes/failures and review sync history..
After the upload is complete, switch to the Status tab. Review any error messages associated with your upload. Make adjustments to the .csv files as needed.
Step Six: Verify Data
Once the test data has been processed by Echo, it is important to verify that the data in Echo matches what's in the SIS.
- If syncing multiple schools, verify that each school sub-domain was created
- Verify that users were created and that they are in the correct sub-domain. Also make sure users weren't created in schools that are not using Echo with students.
- Verify that base and derivative section courses were created
- Verify that staff and students are enrolled in the correct courses.
- Use Echo's proxy feature to verify several user's home page are correctly displaying courses (note, if enrollment start date hasn't arrived yet, courses may still be hidden).
Note: It is rare that success is achieved the during the first attempt. You will likely need to make adjustments to the export file or sync settings to get the desired results. If needed, delete all accounts and courses in Echo to start over.
Step Seven: Preparing Existing Data For SIS Sync
When first enabled, the OneRoster sync will create ALL NEW user accounts, courses, and enrollments based on the data in your SIS. In many cases, you want to preserve existing accounts. This step allows teachers and students to use their existing accounts and access prior courses.
To keep Echo and the SIS in sync, Echo relies on the External Id field. When using the OneRoster SIS Sync, all synced items will have a "or--" in External Id field. A user, for example might have a identification number of 123456789 in the SIS. In Echo, you would see or--123456789 as the user's External Id.
Items that don't have an "or--" External Id are invisible to the sync. If the sync finds a match, it will update the information. If the sync doesn't find a match, it creates a new user, course, or enrollment.
If you want to the sync to work with existing users, courses, or enrollments in your production domains, it is necessary to update the External Id data before you enable the sync. Alternatively, you can let the sync create all new users, courses, or enrollments.
Typically, schools chose to update the existing domains and users with a new External Id and allow the sync to create all new courses and enrollments. For details on how to update existing domains, users, courses, and enrollments, see How do I prepare my Echo domain for the OneRoster SIS Sync when I have existing data?
Step Eight: Manually Sync Live Data (Production)
Once the production data has been updated with new External Ids,
- Duplicate the SIS Sync settings you configured in the sandbox domain during Step Four into the production domain. If you are syncing several schools, configure the Sync in the district domain.
- Follow the same steps from Step Five to manually upload the OneRoster.zip file. If you are syncing several schools, upload the file in the district domain.
- Review the Status tab to look for errors. If you are working with existing data, it's likely that new errors will be listed. For example, the sync may try to create a new user if it's unable to find a matching External Id, but if the account already exists in Echo, it won't be able to because the username is already in use.
Step Nine: Verify the Data (Production)
Using the same approach as Step Six, verify the data in Echo. If you are trying to sync with existing data, you may find issues that weren't present in your sandbox. For example, an existing user that didn't have the correct External Id may get a duplicate account.
Step Ten: Upload using FTP
To use FTP to upload the file or upload directly in Echo, use the following:
- Your username is your userspace/username.
- Your password is your Echo password
- The FTP location/URL is found in the Data Files screen for your domain.
Echo is constantly being improved based on the feedback from users and we strive to keep our documentation up to date. If this document doesn’t match what you are seeing in Echo, please let us know.