Rostering Integrations

About OneRoster

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.1 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.1 format. Quaver does not require all fields be sent. 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 eight 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.
• manifest.csv  – The manifest contains the list of files that are supplied in your upload. This allows you to denote which files you will and won’t send to QuaverEd as well as enable new files when they are needed.

If your district intends to set up Auto-Registration you need to send more .csv files than what is required for a standard OneRoster CSV integration. Please refer to the Auto-Registration page for specifics on what additional fields are required in the above files. Additional required files are as follows:

• resources.csv – The resources data table contains information regarding resources that will be used to link a teacher to a Quaver license via a class or course. This table requires a unique value for the resource, as well as the vendor’s (Quaver’s) ID and vendor resource ID.
• classResources.csv – The class resources data table is used to link a resource from resources.csv to a class, allowing for the teacher of that class to receive the resource. This table requires a sourcedID for each entry, as well as sourcedIDs for both the class and the resource that are being linked.
• courseResources.csv – The course resources data table is used to link a resource from resources.csv to a class, allowing for any teacher who owns a class in that course to receive the resource. This table requires a sourcedID for each entry, as well as sourcedIDs for both the course and the resource that are being linked.

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:

1. 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.
2. 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”,…)

Before you can deliver your roster files for production on QuaverMusic.com, you must provide the public IP address of the machine that will be delivering your roster files. Please provide this IP to the Quaver integrations team at integration@quavered.com.

Delivering OneRoster Files

Step 1: Connect via sFTP

Once we have whitelisted your IP address, we will reach out to your district IT agent and deliver sFTP connection credentials (domain, username, and password) via email. You should use these credentials to connect with Quaver’s server using sFTP. You may establish this connection using any capable sFTP client. Quaver operates on the default sFTP Port 22. A successful connection will open to your district’s root directory automatically.

Step 2: Deliver roster files

Locate the OneRoster files in your local file system and upload the OneRoster files to your root directory on the Quaver server. Ensure that all files are named exactly as specified prior to transfer, and verify that the transfer of each file completed successfully.

Please do NOT:

• Upload any extra files in the root directory
• Deliver a zipped file set
• Keep backup files in the root directory

Step 3: User testing

After your first file set is delivered to production, we will need to test with a Quaver teacher in the district to ensure that their rosters are built correctly when they go through the typical workflow. You should identify a teacher who currently uses Quaver and is willing to participate. The more responsive this teacher can be, the faster testing can proceed.

Testing involves two steps:

1. The teacher will log into Quaver using your district’s Single Sign-On method. Then, they will see our account provisioning The teacher will log into Quaver using your district’s Single Sign On method. Then, they will see our account provisioning page. When prompted, the teacher should select “Link existing QuaverEd Account” and enter their Quaver account credentials. Learn more about this account provisioning step.

2. The testing teacher will need to check their Classes and Student Accounts in the Student Admin section of the Teacher Dashboard. If the test is successful, the teacher should see their rosters automatically populate.

Step 4: Scheduling regular file delivery

Once we verify that a teacher gets their classes via the established workflow, you can set up a recurring file transfer. You can submit updated file sets to the production server as often as daily. Keeping your files up-to-date ensures that teachers are always getting Quaver classes that match up with your district’s SIS data. We process files nightly, so be sure your file transfer has finished by 4:00AM Central Time.

Step 5: Release

Recall that an SSO integration must accompany a rostering integration. Thus before you release this functionality district-wide, we must confirm that:

1. Both a Quaver teacher and student have logged into Quaver using the SSO link successfully.
2. The Quaver teacher that logged in using the SSO link has seen his or her rosters appear correctly in Quaver.

Once we have confirmed that the SSO link and rosters are working properly, you can launch the functionality district-wide whenever you wish. You should notify your Quaver users when the functionality becomes available, and you are responsible for training your users how to access Quaver from your district’s system. You can share our account provisioning instructions with your district’s users in order to smooth their transition into using SSO to access Quaver.

Step 6: Support

Quaver will continue to support the rostering integration with your district throughout our contract term. We are committed to providing responsive support for our integrations, and will work with you to resolve any issues that may arise. If you need to alter your district’s SSO or rostering configuration at any time, please notify us prior to making any changes so that we can provide uninterrupted access for your Quaver users.

Note: This is especially true of changing your sourcedId schema, which will disrupt your users’ experience on QuaverMusic.com. Please notify us before you make sourcedId schema changes in your roster files.

About Auto-Registration

An Auto-Registration integration automatically provisions the appropriate access levels and creates accounts for your teachers using your OneRoster data. In doing so, this integration removes the need for teachers to register their Teacher Access Code to gain access to Quaver. To do this we use the teacher’s name and email along with their associated schools to determine their access and create their account. A simple integration can be achieved by supplying the following data with an SSO and rostering integration:

• First name, last name, email, role (i.e. teacher, student, etc)
• OneRoster orgs data with NCES ID in the “identifier” field.

Note: If the OneRoster orgs data is not supplied, teachers can be given the option to select which schools they are associated with.

A more granular integration can be achieved by using the resources dataset of the OneRoster format. An integration using the OneRoster resources service can be set up via OneRoster.CSVs sent via SFTP, or with ClassLink OneRoster API (other APIs don’t currently support the resources service). This service is mainly useful if you want to control which teachers are granted access or have multiple QuaverEd products. Here are the pieces of information we need to provide this service:

• An SSO or rostering integration that supplies the following data for teacher users: first name, last name, email.
• OneRoster orgs data with NCES ID in the “identifier” field.
• OneRoster resources data with appropriate “vendorResourceIds” (QuaverEd will provide these)
• OneRoster classResources and courseResources to associate QuaverEd resources with a teacher’s enrolled class.
• Teachers in OneRoster users are associated with an org that has a valid QuaverEd license and enrolled as teacher in a class with the appropriate resource.

It is important to note that a rostering integration with Quaver requires that we also integrate via Single Sign On (SSO) for your district. To set up an Auto-Registration integration, reach out to the integration department at integration@Quavered.com.