This method for integrating rostering data into Quaver requires that you submit a set of .csv (Comma Separated Value) files that comply with the IMS Global OneRoster (1.0 or 1.1) format. The OneRoster file set describes the relationships between schools, users, courses, academic sessions, classes, and enrollments. While the information requested by the OneRoster format exceeds Quaver’s needs, Quaver supports the OneRoster specification due to its widespread acceptance as a data interchange format. In a OneRoster CSV rostering integration with Quaver, OneRoster files will be delivered regularly via sFTP in order to ensure that all of the district’s rostering information remains up-to-date in Quaver’s system.
Quaver accepts both the OneRoster 1.0 and OneRoster 1.1 formats. If your district is producing a OneRoster export solely for Quaver, we suggest the 1.0 format as it is the simpler format to produce and provides all of the data Quaver needs to support a rostering integration.
With that in mind, the instructions presented on the following pages are intended to simplify the information provided by the IMS Global Learning Consortium in regards to producing the OneRoster 1.o format. You’ll notice that Quaver does not require many of the fields. You can also view IMS Global’s OneRoster specifications.
Remember that a rostering integration with Quaver requires that we also integrate with a Single Sign On (SSO) system used by your district.
OneRoster Format Overview
In compliance with the IMS Global OneRoster v1.0 data interchange format, the following seven files/data tables are required. Note that each data table is a .csv (Comma Separated Value) file. The breakdown for each of the files listed below can be found here.
- orgs.csv – The orgs data table describes the organizations to be included in the roster information. Typically, the organizations are schools or districts. Each row should be one organization (school or district). Note: Quaver does not collect this information but requires the header row for the table to comply with the OneRoster format.
- users.csv – The users data table describes the various users of the organization (teachers, students, administrators, IT staff). It includes the actual names of the users, as well as their email addresses, login names, and other information. Each row represents one user.
- academicSessions.csv – The academic sessions data table describes the quarters, semesters, or terms during which classes will be taught. Each row represents a term with a title and start and end dates.
- courses.csv – The courses data table establishes the course to which multiple classes may belong. Each row represents a course such as “General Music.” Note: Quaver does not collect this information but requires the header row for the table to comply with the OneRoster format.
- classes.csv – The classes data table lists the classes taught for each course, including the grade level and the title of the class. Each row represents a class, for example, “Music, 5th period.”
- enrollments.csv – The enrollments data table assigns users to their various classes. Each row designates one user belonging to one class.
- demographics.csv – The demographics data table describes the sex, ethnicity, birth date and other information of each user. Note: Quaver does not collect this information but requires the header row for the table to comply with the OneRoster format.
The format is a model onto which your organization’s data can be mapped. Do not worry if your data structure does not exactly conform to the model! The detailed specifications for each file clearly explain the information Quaver requires to create class rosters, which is a small fraction of what the format can accommodate. We will gladly help you with any questions you have about how to best map your data.
While Quaver would prefer to receive data tables that include only information related to music classes, we do not require districts to filter that data before being sent to us. Therefore, we do not create Quaver classes for a teacher in our system until both of the following are true:
- The teacher has logged into Quaver via SSO using an account that can be matched to a teacher submitted in the OneRoster users.csv file.
- The teacher has registered a valid Quaver content access code to their Quaver account. The code activates all relevant content for that teacher, and we interpret that as a signal to create the teacher’s class rosters. Teachers are usually sent their access codes via email outside of this rostering process. If teachers have questions about their access code, they should contact their supervisor or Quaver Key Account Representative. Note: Rostered student accounts do not need to enter a content access code to gain access to student content.
OneRoster Data Entry Guidelines
When to enter data in a field:
- If a field is required, you MUST include a valid value for that field in each row. Sometimes this value is not used in our system, even though it is required in the OneRoster format.
- If a field is recommended, it will be used within the Quaver program but is optional to include.
- If a field is not required, it is not used within the Quaver program, nor required by the OneRoster spec. If you are creating these files from scratch, it may be easiest to leave these fields blank. Even if you do not enter data in non-required fields, you must still include that field’s header in the file. Enter the specified field header at the top of the column and leave that column’s fields blank in the remaining rows (a blank field in a .csv file looks like two consecutive commas: ,, ).
- Quaver does not utilize any data contained in the orgs.csv, courses.csv, or demographics.csv data tables, but they are required by the OneRoster specification. You may either:
- Submit these data tables with only the field headers row and no other data (preferred).
- Submit the files with data, according to the specifications.
- Quaver accepts bulk OneRoster sets only. We do not accept delta file sets at this time. Per OneRoster spec, please leave the status and dateLastModified fields blank in each file.
Formatting data in a field:
- The first row of each .csv file must contain only and all of the specified field header names, listed left to right in the order specified. (Field header names are not case sensitive.)
- If you need to list multiple values in a single field that can accommodate them, list the values separated by commas and enclose the entire set with double quotes. (for example ,“123456, 654321”,…)