A OneRoster CSV rostering integration requires that you submit a set of .csv (Comma Separated Value) files that comply with the 1EdTech OneRoster 1.1 format.
The formatting instructions presented below are intended to simplify the information provided by 1EdTech in regard to producing the OneRoster 1.1 format.
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: ,, ).
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”,…)
Please note that each data table is a .csv file.
The manifest file contains the list of files that are supplied in your upload. It also allows you to denote which files you will send to QuaverEd and enable new files when they are needed.
This file will consist of just two columns with the headers propertyName and value. Each row will contain a single property/value pair.
| Property Name (One per row) | Value Required | Format | Value Description |
| manifest.version | Yes | String | The version of the manifest. For an initial value this must be “1.0”. |
| oneroster.version | Yes | String | The OneRoster version supported by this file set. This must be “1.1”. |
| file.academicSessions | Yes | Enumeration | Each field is enumerated as: { “absent” | “bulk” | “delta” } with the values denoting:• absent – this CSV file is not supplied;• bulk – this CSV file contains only bulk data;• delta – this CSV file contains only delta data.These processing mode hints should be consistent with the data held within the accompanying CSV files but in cases of conflict the values in the data CSV files must take precedence. |
| file.categories | Yes | Enumeration | |
| file.classes | Yes | Enumeration | |
| file.classResources | Yes | Enumeration | |
| file.courses | Yes | Enumeration | |
| file.courseResources | Yes | Enumeration | |
| file.demographics | Yes | Enumeration | |
| file.enrollments | Yes | Enumeration | |
| file.lineItems | Yes | Enumeration | |
| file.orgs | Yes | Enumeration | |
| file.resources | Yes | Enumeration | |
| file.results | Yes | Enumeration | |
| file.users | Yes | Enumeration | |
| source.systemName | No | String | The name for the system producing the set of files. |
| source.systemCode | No | String | Identification code for the system producing the set of files. |
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.
| Field Header | Value Required | Format | Description |
| sourcedId | Yes | GUID | SourcedId of this academicSession. This value must be unique for every row in this file. Academic session sourcedIds will be used in other files to reference each unique academic session listed here. |
| status | Yes for Delta | Enumeration | Permitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified.This MUST NOT be used for the Bulk mode. |
| title | Yes | String | Name or title of the academic session. |
| type | Yes | Enumeration | Describes the type of academic session. Permitted values of: { gradingPeriod | semester | schoolYear | term } |
| startDate | Yes | Date | This value defines the start date of classes that reference this session. All classes with a start date in the future are visible to users. |
| endDate | Yes | Date | This value defines the end date of classes that reference this session. Classes in Quaver become archived after this end date has passed. |
| parentSourcedId | No | GUID Reference. | SourcedId of the parent of this academic session.You can use this value to nest sessions, for example, the sourcedId of the school year to which the semester belongs. |
| schoolYear | Yes | Year | The school year for which the academic session contributes. This year should be that in which the school year ends.(Format is YYYY) |
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.”
| Field Header | Value Required | Format | Description |
| sourcedId | Yes | GUID | Unique ID for the class. Class sourcedIds will be used in the enrollments.csv file to enroll users in the classes listed here. This value must be unique for every row in this file. |
| status | Yes for Delta | Enumeration | Permitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified.This MUST NOT be used for the Bulk mode. |
| title | Yes | String | Name of the class. Class titles over 20 characters may not display correctly in all areas of Quaver. |
| grades | No | List of Strings | Grade level of the class (for example, 5). |
| courseSourcedId | Yes | GUID Reference. | SourcedId of the course of which this class is an instance. This value must reference a sourcedId in the courses.csv file |
| classCode | No | String | Human readable code used to help identify this class. |
| classType | Yes | Enumeration | Describes how the class meets. The permitted values are: { homeroom | scheduled } |
| location | No | String | Human readable description of where the class is physically located. |
| schoolSourcedId | Yes | GUID Reference. | SourcedId of the organization (school) which teaches this class. This value must reference a sourcedId in the orgs.csv file. |
| termSourcedIds | Yes | List of GUID References. | SourcedId of the terms (the academicSessions) in which the class is taught.The start and end dates of the referenced academicSessions row will determine the start and end dates of this class within Quaver. |
| subjects | No | List of Strings | Subject name(s) in human readable form. If the ‘subjectCodes’ attribute is present then the subjects and subjectCodes lists must have the same length and have order significanceThe vocabulary is from SCED (School Codes for the Exchange of Data) (Version 4) for the “Course Title” field: http://nces.ed.gov/forum/SCED.asp |
| subjectCodes | No | List of Strings | Subject codes(s) in machine readable form. If more than one subject code is needed, use double quotes, and separate with commas (per RFC 4180). If the ‘subjects’ attribute is present the two lists must have the same length and have order significance. |
| periods | No | List of Strings | The time slots in the day that the class will be given. If more than one period is needed, use double quotes, and separate with commas.Examples: 1; “1,3,5” |
The enrollments data table assigns users to their various classes. Each row designates one user belonging to one class.
| Field Header | Value Required | Format | Description |
| sourcedId | Yes | GUID | Unique identifier of this enrollment. This value must be unique for every row in this file. An enrollment is the pairing of a user (student or teacher) and a class. |
| status | Yes for Delta | Enumeration | Permitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified.This MUST NOT be used for the Bulk mode. |
| classSourcedId | Yes | GUID Reference. | SourcedId of the Class.This value must reference a sourcedId in the classes.csv file. |
| schoolSourcedId | Yes | GUID Reference. | SourcedId of an Org with type ‘school’.This value must reference a sourcedId inthe orgs.csv file. |
| userSourcedId | Yes | GUID Reference. | SourcedId of the User. This value must reference a sourcedId in the users.csv file. |
| role | Yes | Enumeration | Permitted values are: { administrator | proctor | student | teacher }. |
| primary | No* | Enumeration | Permitted values: { “true” | “false” }. Applicable only to teachers. Only one teacher should be designated as the primary teacher for a class.*If more than one teacher is enrolled in a class, this value is required to be “true” for exactly one teacher. |
| beginDate | No | Date | The start date for the enrollment. This date must align with the associated academic session (term) identified in the class. |
| endDate | No | Date | The end date for the enrollment. This date must align with the associated academic session (term) identified for the class. |
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.
| Field Header | Value Required | Format | Description |
| sourcedId | Yes | GUID | Unique ID for the user. SourcedId is used in other files and must be unique across all users. |
| status | Yes for Delta | Enumeration | Permitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified.This MUST NOT be used for the Bulk mode. |
| enabledUser | Yes | Enumeration | Permitted values: { “true” | “false” }. ‘false’ denotes that the user is an active record but system access is curtailed according to the local administration rules. |
| orgSourcedIds | Yes | List of GUID References. | The sourcedId of the organization(s) to which this user belongs. In most cases, it is expected that users will belong to a single school.If the user belongs to multiple organizations you may list multiple values separated by commas and enclose the entire set with double quotes. For example: “123456, 654321” |
| role | Yes | Enumeration | Permitted values are : { teacher | student | parent | guardian | relative | aide | administrator | proctor }. |
| username | Yes | String | This is usually the user’s district username. This value will not have any bearing on the username used to access the Quaver site. |
| userIds | No | List of Strings | External machine-readable ID (e.g. LDAP id, LTI id) for this user. The ID must be accompanied by a type to indicate the nature of the Identifier. The Type and ID values are enclosed in ‘{}’ with a colon used to separate the values. If more than one userId is needed, use double quotes, and separate with commas (per RFC 4180).Examples:{LDAP:Id}”{LDAP:Id},{LTI:Id},{Fed:Id}” |
| givenName | Yes | String | User’s first name. |
| familyName | Yes | String | User’s surname. |
| middleName | No | String | User’s middle name (s). If more than one then they are separated by a space. |
| identifier | No | String | Identifier for the user with a human readable meaning. |
| No | String | Email address for the User. | |
| sms | No | String | SMS address for the User. |
| phone | No | String | Phone number for the User. |
| agentSourcedIds | No | List of GUID References | SourcedIds of the Users to which this user has a relationship. If multiple IDs are required then use double quotes and separate with commas. For example: “123456, 654321” .Note: In most cases this will be for indicating parental relationships. |
| grades | No | String | Grade(s) for which a user with role ‘student’ is enrolled. The permitted vocabulary is from CEDS (Version 5) for the ‘Entry Grade Level’ element https://ceds.ed.gov/CEDSElementDetails.aspx?TermId=7100. |
| password | No | String | The password for the user. This may or may not be an encrypted string. |
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).
- If your district is using Auto-Registration, data must be provided in this file.
| Field Header | Value Required | Format | Description |
| sourcedId | Yes | GUID | Unique id for the organization. SourcedId is used in other files and must be unique across all organizations. |
| status | Yes for Delta | Enumeration | Permitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified.This MUST NOT be used for the Bulk mode. |
| name | Yes | String | Name of the organization. |
| type | Yes | Enumeration | Permitted values are : { department | school | district | local | state | national }. |
| identifier | No | String | NCES ID National Center for Education Statistics) for the school/district. |
| parentSourcedId | No | GUID Reference. | SourcedId of an Org representing the Parent organization.For example, the sourcedId of the district to which the school belongs. |
The courses data table establishes the course to which multiple classes may belong. Each row represents a course, such as “General Music.”
- If your district is using Auto-Registration, data must be provided in this file.
| Field Header | Value Required | Format | Description |
| sourcedId | Yes | GUID | Unique ID for the course.Course sourcedIds can be used in the classes.csv file to assign classes to the courses listed here |
| status | Yes for Delta | Enumeration | Permitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified.This MUST NOT be used for the Bulk mode. |
| schoolYearSourcedId | No | GUID Reference. | SourcedId of an AcademicSession with type of “schoolYear”. |
| title | Yes | String | Name of the course. |
| courseCode | No | String | Human readable course code. |
| grades | No | List of Strings | Grade(s) for which the class is attended. The permitted vocabulary is from CEDS (Version 5) for the ‘Entry Grade Level’ element https://ceds.ed.gov/CEDSElementDetails.aspx?TermId=7100 |
| orgSourcedId | Yes | GUID Reference. | SourcedId of an org to which this course belongs. |
| subjects | No | List of Strings | Subject name(s) in human readable form. If the ‘subjectCodes’ attribute is present then the subjects and subjectCodes lists must have the same length and have order significanceThe vocabulary is from SCED (School Codes for the Exchange of Data) (Version 4) for the “Course Title” field: http://nces.ed.gov/forum/SCED.asp |
| subjectCodes | No | String | Subject codes(s) in machine readable form. If the ‘subjects’ attribute is present then the subjects and subjectCodes lists must have the same length and have order significance.For deployments in the USA this vocabulary SHOULD be a School Courses for the Exchange of Data (SCED) code: http://nces.ed.gov/forum/SCED.asp |
The demographics data table describes the ethnicity, birth date, and other information of each user.
- This file is optional. QuaverEd does not use this information.
| Field Header | Value Required | Format | Description |
| sourcedId | Yes | GUID Reference | SourcedId of the User to which the demographics refer. Typically this will be a student. Each user can have only one demographics record.This value must reference a sourcedId in the users.csv file. |
| status | Yes for Delta | Enumeration | Permitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified.This MUST NOT be used for the Bulk mode. |
| birthDate | No | Date | The date of birth. |
| sex | No | Enumeration | Permitted values: are { “male” | “female” }. |
| americanIndianOrAlaskaNative | No | Enumeration | Permitted values: { “true” | “false” }. |
| asian | No | Enumeration | Permitted values: { “true” | “false” }. |
| blackOrAfricanAmerican | No | Enumeration | Permitted values: { “true” | “false” }. |
| nativeHawaiianOrOtherPacificIslander | No | Enumeration | Permitted values: { “true” | “false” }. |
| white | No | Enumeration | Permitted values: { “true” | “false” }. |
| demographicRaceTwoOrMoreRaces | No | Enumeration | Permitted values: { “true” | “false” }. |
| hispanicOrLatinoEthnicity | No | Enumeration | Permitted values: { “true” | “false” }. |
| countryOfBirthCode | No | String | Country where the user was born. The permitted vocabulary is from CEDS (Version 5) for the “Country of Birth” element https://ceds.ed.gov/CEDSElementDetails.aspx?TermxTopicId=20002 |
| stateOfBirthAbbreviation | No | String | State where the user was born. The permitted vocabulary is from CEDS (Version 5) for the “State of Birth” element https://ceds.ed.gov/CEDSElementDetails.aspx?TermxTopicId=20837 |
| cityOfBirth | No | String | |
| publicSchoolResidenceStatus | No | String | An indication of the location of the user’s legal residence relative to (within or outside) the boundaries of the public school attended and its administrative unit. The permitted vocabulary is from CEDS (Version 5) for the “Public School Residence Status” element https://ceds.ed.gov/CEDSElementDetails.aspx?TermxTopicId=20863 |
Auto-Registration Files
If your district intends to set up Auto-Registration, you will need to send additional .csv files. Please refer to the Auto-Registration documentation for specific instructions regarding your roster data.
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.
- This file is only required for Auto-Registration integrations.
| Field Header | Value Required | Format | Description |
| sourcedId | Yes | GUID | Unique ID for the class/resource association. SourcedId is used in other files and must be unique across all class resources. |
| status | Yes for Delta | Enumeration | Permitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified.This MUST NOT be used for the Bulk mode. |
| title | No | String | Name of the related class. |
| classSourcedId | Yes | GUID Reference. | SourcedId of the reference Class.This value must reference a sourcedId in the classes.csv file. |
| resourceSourcedId | Yes | GUID Reference. | SourcedId of the Resource associated with the Class. |
The course resources data table is used to link a resource from resources.csv to a course, 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.
- This file is only required for Auto-Registration integrations.
| Field Header | Value Required | Format | Description |
| sourcedId | Yes | GUID | Unique ID for the course/resource association. SourcedId is used in other files and must be unique across all course resources. |
| status | Yes for Delta | Enumeration | Permitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified.This MUST NOT be used for the Bulk mode. |
| title | No | String | Name of the related course. |
| courseSourcedId | Yes | GUID Reference. | SourcedId of the reference Course.This value must reference a sourcedId in the courses.csv file. |
| resourceSourcedId | Yes | GUID Reference. | SourcedId of the Resource associated with the Course. |
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.
- This file is only required for Auto-Registration integrations. Please download and use the resources.csv template file below.
| Field Header | Value Required | Format | Description |
| sourcedId | Yes | GUID | Unique ID of this resource. |
| status | Yes for Delta | Enumeration | Permitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified.This MUST NOT be used for the Bulk mode. |
| vendorResourceId | Yes | ID | Unique ID of this resource. This value is provided by QuaverEd. |
| title | No | String | Name of this resource. |
| roles | No | Enumeration List | Permitted values are : { administrator | teacher |aide | guardian | parent | proctor | relative | student }. |
| importance | No | String | Permitted values: { “primary” | “secondary” }. |
| vendorId | No | ID | The vendor ID for QuaverEd. This field must be “vnd.qed”. |
| applicationId | No | ID | Identifier of the application associated with this resource. |