Echo supports the automated syncing of users, courses, enrollments, and observers through the IMS OneRoster specification. This article answers common questions about Echo's OneRoster SIS sync solution. For instructions on setting up a OneRoster SIS sync, see the OneRoster Setup Guide.
What is OneRoster?
OneRoster is not a software application or technology. Instead, it's a specification for standardizing data that softward and technology companies can use to make sure their software can exchange data with other software. For example, when syncing user data using CSV files, the OneRoster standard specifies the column headers (i.e. givenName, familyName, username, email, etc). The standard was created and is managed by the IMS Global Learning Consortium. The standard is often used to sync data between student information systems (SIS), learning management systems (LMS), and other learning tools. For this document, the LMS is Echo.
What actions does the OneRoster integration perform?
When enabled in Echo and your SIS, the OneRoster sync can keep Echo updated with any changes made in the SIS. What data is synced with Echo is dependent on what data the SIS has been configured to share. The sync can create, update, and delete various entities shared with Echo. Specifically, these entities include:
- Users: Students, teachers, school and district admins
- Courses: District, school, and teacher Base courses; section courses
- Enrollments: Student and teacher enrollments
- Domains: Schools, districts, states, departments, etc.
- Observers: Parents, guardians, and relatives
What if I have existing users, courses and enrollments in my domain.
When run for the first time, the OneRoster integration will create all new users, courses and enrollments UNLESS the External ID field of each is updated to match the
sourcedId found on the OneRoster .csv files produced by the SIS. Typically, this procedure would only be used for existing user accounts so that they continue to have access to prior courses and enrollments.
See "How do I preserve existing users when initiating a OneRoster sync for the first time?" for more information.
What if I delete a user, course, or enrollment from my SIS?
What happens if you delete something in your SIS depends on how the sync settings are configured. If a user, course, or enrollment was created by the SIS sync and then deleted in the SIS, the following will happen:
Users that exist in Echo but not in your SIS can either be automatically deleted, left in place, or marked inactive.
Course that exist in Echo but not in your SIS can either be deleted or left alone
Enrollments that exist in Echo but not in your SIS can either be deleted, left alone, marked as inactive, or marked as withdrawn.
If a user, course, or enrollment was created manually in Echo, it is not tied to the SIS sync and will be ignored.
Can I create users, courses, or enrollments manually in Echo when the sync is active?
Yes, any users, courses, or enrollments created manually in Echo will be ignored by the OneRoster Synce (as long as the External Id doesn't start with "or-" which flags the item as managed by the OneRoster Sync).
Will the OneRoster Sync create base courses and derivatives.
Yes, the sync can create base and derivative courses depending on the sync settings established in your Echo domain settings. By default, the sync will create:
Domain Base Course: For each course title (i.e. Physics, Language Arts 11, Health, 3rd Grade), the sync will create a base course that can be used to distribute content to each teacher's base course. The domain base course creation can be disabled in the sync settings.
Teacher Base Course: Teachers will get their own base course for each subject (course title) they teacher. The teacher base course is a derivative of the domain base course. A new teacher base course will be created for each term unless this is disabled in the sync settings.
Teacher Class Course: For each section/class the teacher has, the sync will create a course and enroll the students. The teacher class course is a derivative of the domain base course.
Can I change information created by the OneRoster integration?
No. When you change some information that is managed by the integration, it will likely be reverted the next time the sync runs. For example, if you manually change a user’s first name in Echo from “Bradley” to “Brad,” it will revert back to “Bradley” the next time the sync runs if the user’s first name is Bradley according to the OneRoster zip file.
Any changes should be managed in your school's SIS. Changes to these fields will automatically be reflected in Echo upon the next sync.
Can the OneRoster sync send grades back to the SIS?
The OneRoster standard does include specifications for sending course grades back to the student information system. However, very few student information systems have opened the application to allow this functionality. If your system allows it, please contact the Echo team for more information.
- - TECHNICAL FAQs - -
What version of OneRoster does Echo support?
Echo supports OneRoster 1.1 using CSV mode for Rostering Import Bulk.
The CSV mode is a collection of CSV files (packaged together as a OneRoster zip file). Files can be uploaded manually or using an automated FTP process from your SIS. Once uploaded to Echo, the CSV files are processed to create, update, and/or delete data from Echo.
Does my SIS natively support exporting OneRoster CSV or zip files?
You can review the tools that have been certified to support OneRoster Rostering CSV Export Bulk. However, many other SIS support this functionality even though they are not certified. Reach out to your SIS administrator to learn if your SIS can export OneRoster files.
What CSV files are required in the OneRoster integration?
- manifest.csv (defines what will be synced)
- academicSessions.csv (defines the school year and terms)
- classes.csv (defines the classes teacher and student will be enrolled in)
- courses.csv (defines the courses or subjects that are available)
- 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. 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.
How does a user upload the OneRoster zip file to Echo?
In order to upload a OneRoster zip file, the user must have Administrator permissions. The Echo team can grant you this level of permissions if needed. Administrators can upload the OneRoster zip file:
- manually through the Echo Admin app
- automatically through FTPS process from your SIS
See "How do I set up OneRoster with Student Information Systems (SIS) in Echo" for more information.
Do all of the rows need to contain values for each header field?
No. However, you are expected to provide a value for each header field that is required according to the OneRoster specification. Refer to CSV Format for more details.
For example, in the academicSessions.csv you are required to include the header field (i.e., column) parentSourcedId, but you are not required to provide a value in the corresponding rows.
Example (displayed as a table for readability):
How are the property values mapped between the OneRoster zip file and Echo?
What is a base course?
Echo allows for multiple derivative courses to be managed (e.g., settings, content) from a base course. The derivative course receives updates from the base course as long as it was not explicitly changed in the derivative course. This workflow allows for efficient curriculum development and distribution while still allowing for teachers and schools to further enhance their course.
The OneRoster integration may create organization (e.g., state, district, school) base courses, a teacher base course, and academic session base course for every course that is taught. The classes (i.e., where student enrollments exist) will be created as derivative courses of the academic session base course, or the next available base course. This means that settings or content added to the state base course will be inherited by all organization base courses and subsequently the teacher/academic session base courses and the section courses.
In the example below, there is:
- A state organization
- Two school district organizations
- Three school organizations
- Three teachers
- Two academic sessions per teacher
- A total of ten section courses (or “classes”)
The higher in the hierarchy content or changes are made, the more derivative courses that would receive the change. For example, if a new assessment were to be added to the:
- State organization base course, this assessment would appear in each distinct organization base course, school organization base course, teacher base course, academic session base course, and course section.
- School base course, it would appear in each teacher base course, academic session base course, and section course.
- Teacher base course, it would appear in each of that teacher’s academic session base courses section courses.
If the settings or content is supposed to be available to all students in the:
- state, then it should be added to the state organization base course.
- district, then it should be added to the district organization base course.
- school, then it should be added to the school organization base course.
- teacher’s courses for the current and future sections, then it should be added to the teacher base course.
- teacher’s courses for a specific academic session, then it should be added to the teacher’s academic session base course.
- specific section course, then it should be added to the section course.
Who is enrolled into the different types of courses?
- Organization base course: Nobody. Echo Administrators should manually enroll curriculum developers and other users, as necessary.
- Teacher base course: The primary teacher of the particular course. Each teacher may get their own teacher base course for each unique course they teach.
- Academic Session Base Course: The primary teacher of the particular course. Each teacher may get one or more Academic Session base course for each unique course they teach, and for each term that course is taught in.
- Section course: The teacher(s) and students of the section course.
Will Echo Administrator accounts be created automatically?
No, the OneRoster integration will not create Echo Administrator accounts automatically.
How can I tell if the user, course, or enrollment is managed by the OneRoster integration?
If the user, course, enrollment, or domain has an external ID that is prefixed with “or-”, then it will be managed by the OneRoster integration. Echo Administrators can review if the entity has an external ID by looking at the list of users, courses, enrollments, or domains in the Admin app.
How often is the OneRoster integration sync run?
The OneRoster integration sync is run soon after a OneRoster zip file is sent to Echo. It can be run as frequently as the organization desires. In general, we recommend not sending a OneRoster zip file to Echo more frequently than every 12 hours.
Where in Echo are users created?
Users are created in the domain that is associated with the first organization for the user in the user.csv file.
Where in Echo are the courses created?
Organization base courses are created in the domain that is associated with the organization. Teacher base courses, academic session bases courses, and section courses are created in the domain associated with section courses (classes.csv).
If a teacher or admin creates a course outside of the OneRoster integration, will it be changed by the sync?
As long as the course external ID does not prefix with “or-”, it will not be modified by the OneRoster integration.
How can I use an existing Echo course as a OneRoster integration managed course?
There are times that you want to use an already existing Echo course as a OneRoster integration managed course. For example, you created a course that you want to be used as a school organization base course. To do so:
- Identify the OneRoster integration managed school organization base course in Echo.
- Update the manually created course to have the same external ID as the managed school organization Base course.
- Delete the external ID from the undesired school organization base course.
The next time the sync runs, it will update all teacher base courses to point to the new school organization base course. Follow the same process for replacing any of the OneRoster integration managed courses with a manually created course.
What determines if base courses are created for a section course?
For a section course to have a base course, the section course (classes.csv) must have a course code with the associated course.csv in the OneRoster zip file.
What will happen to a user that is moved from one school to another in the OneRoster zip file?
If a user is moved from one school to another, whether due to a transfer or advancement, the OneRoster integration will move the user to the new school along with all of their past information. This will occur if the following conditions are met.
- The user’s sourcedId did not change in the OneRoster zip file (users.csv).
- The two school organizations exist in the same OneRoster zip file.