fbpx

OneRoster Data Entry Guidelines

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 RequiredFormatValue Description
manifest.versionYesStringThe version of the manifest. For an initial value this must be “1.0”.
oneroster.versionYesStringThe OneRoster version supported by this file set. This must be “1.1”.
file.academicSessionsYesEnumerationEach 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.categoriesYesEnumeration
file.classesYesEnumeration
file.classResourcesYesEnumeration
file.coursesYesEnumeration
file.courseResourcesYesEnumeration
file.demographicsYesEnumeration
file.enrollmentsYesEnumeration
file.lineItemsYesEnumeration
file.orgsYesEnumeration
file.resourcesYesEnumeration
file.resultsYesEnumeration
file.usersYesEnumeration
source.systemNameNoStringThe name for the system producing the set of files.
source.systemCodeNoStringIdentification 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 HeaderValue RequiredFormatDescription
sourcedIdYesGUIDSourcedId 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. 
statusYes for DeltaEnumerationPermitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode.
dateLastModifiedYes for DeltaDateTimeThe date that this record was last modified.This MUST NOT be used for the Bulk mode.
titleYesStringName or title of the academic session.
typeYesEnumerationDescribes the type of academic session. Permitted values of: { gradingPeriod | semester | schoolYear | term }
startDateYesDateThis value defines the start date of classes that reference this session. All classes with a start date in the future are visible to users.
endDateYesDateThis value defines the end date of classes that reference this session.  Classes in Quaver become archived after this end date has passed.
parentSourcedIdNoGUID 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.
schoolYearYesYearThe 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 HeaderValue RequiredFormatDescription
sourcedIdYesGUIDUnique 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.
statusYes for DeltaEnumerationPermitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode.
dateLastModifiedYes for DeltaDateTimeThe date that this record was last modified.This MUST NOT be used for the Bulk mode.
titleYesStringName of the class. Class titles over 20 characters may not display correctly in all areas of Quaver.
gradesNoList of StringsGrade level of the class (for example, 5).
courseSourcedIdYesGUID Reference.SourcedId of the course of which this class is an instance. This value must reference a sourcedId in the courses.csv file
classCodeNoStringHuman readable code used to help identify this class.
classTypeYesEnumerationDescribes how the class meets. The permitted values are: { homeroom | scheduled }
locationNoStringHuman readable description of where the class is physically located.
schoolSourcedIdYesGUID Reference.SourcedId of the organization (school) which teaches this class. This value must reference a sourcedId in the orgs.csv file.
termSourcedIdsYesList 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.
subjectsNoList of StringsSubject 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 
subjectCodesNoList of StringsSubject 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.
periodsNoList of StringsThe 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 HeaderValue RequiredFormatDescription
sourcedIdYesGUIDUnique 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. 
statusYes for DeltaEnumerationPermitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode.
dateLastModifiedYes for DeltaDateTimeThe date that this record was last modified.This MUST NOT be used for the Bulk mode.
classSourcedIdYesGUID Reference.SourcedId of the Class.This value must reference a sourcedId in the classes.csv file.
schoolSourcedIdYesGUID Reference.SourcedId of an Org with type ‘school’.This value must reference a sourcedId inthe orgs.csv file.
userSourcedIdYesGUID Reference.SourcedId of the User. This value must reference a sourcedId in the users.csv file.
roleYesEnumerationPermitted values are: { administrator | proctor | student | teacher }.
primaryNo*EnumerationPermitted 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.
beginDateNoDateThe start date for the enrollment. This date must align with the associated academic session (term) identified in the class.
endDateNoDateThe 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 HeaderValue RequiredFormatDescription
sourcedIdYesGUIDUnique ID for the user. SourcedId is used in other files and must be unique across all users.
statusYes for DeltaEnumerationPermitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode.
dateLastModifiedYes for DeltaDateTimeThe date that this record was last modified.This MUST NOT be used for the Bulk mode.
enabledUserYesEnumerationPermitted values: { “true” | “false” }. ‘false’ denotes that the user is an active record but system access is curtailed according to the local administration rules.
orgSourcedIdsYesList 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”
roleYesEnumerationPermitted values are : { teacher | student | parent | guardian | relative | aide | administrator | proctor }.
usernameYesStringThis is usually the user’s district username. This value will not have any bearing on the username used to access the Quaver site.
userIdsNoList of StringsExternal 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}”
givenNameYesStringUser’s first name.
familyNameYesStringUser’s surname.
middleNameNoStringUser’s middle name (s). If more than one then they are separated by a space.
identifierNoStringIdentifier for the user with a human readable meaning.
emailNoStringEmail address for the User.
smsNoStringSMS address for the User.
phoneNoStringPhone number for the User.
agentSourcedIdsNoList of GUID ReferencesSourcedIds 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.
gradesNoStringGrade(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
passwordNoStringThe 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).

Field HeaderValue RequiredFormatDescription
sourcedIdYesGUIDUnique id for the organization. SourcedId is used in other files and must be unique across all organizations.
statusYes for DeltaEnumerationPermitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode.
dateLastModifiedYes for DeltaDateTimeThe date that this record was last modified.This MUST NOT be used for the Bulk mode.
nameYesStringName of the organization.
typeYesEnumerationPermitted values are : { department | school | district | local | state | national }.
identifierNoStringNCES ID National Center for Education Statistics) for the school/district.
parentSourcedIdNoGUID 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.”

Field HeaderValue RequiredFormatDescription
sourcedIdYesGUIDUnique ID for the course.Course sourcedIds can be used in the classes.csv file to assign classes to the courses listed here
statusYes for DeltaEnumerationPermitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode.
dateLastModifiedYes for DeltaDateTimeThe date that this record was last modified.This MUST NOT be used for the Bulk mode.
schoolYearSourcedIdNoGUID Reference.SourcedId of an AcademicSession with type of “schoolYear”.
titleYesStringName of the course.
courseCodeNoStringHuman readable course code.
gradesNoList of StringsGrade(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 
orgSourcedIdYesGUID Reference.SourcedId of an org to which this course belongs.
subjectsNoList of StringsSubject 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 
subjectCodesNoStringSubject 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 HeaderValue RequiredFormatDescription
sourcedIdYesGUID ReferenceSourcedId 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.
statusYes for DeltaEnumerationPermitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode.
dateLastModifiedYes for DeltaDateTimeThe date that this record was last modified.This MUST NOT be used for the Bulk mode.
birthDateNoDateThe date of birth.
sexNoEnumerationPermitted values: are { “male” | “female” }.
americanIndianOrAlaskaNativeNoEnumerationPermitted values: { “true” | “false” }.
asianNoEnumerationPermitted values: { “true” | “false” }.
blackOrAfricanAmericanNoEnumerationPermitted values: { “true” | “false” }.
nativeHawaiianOrOtherPacificIslanderNoEnumerationPermitted values: { “true” | “false” }.
whiteNoEnumerationPermitted values: { “true” | “false” }.
demographicRaceTwoOrMoreRacesNoEnumerationPermitted values: { “true” | “false” }.
hispanicOrLatinoEthnicityNoEnumerationPermitted values: { “true” | “false” }.
countryOfBirthCodeNoStringCountry 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 
stateOfBirthAbbreviationNoStringState 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 
cityOfBirthNoString 
publicSchoolResidenceStatusNoStringAn 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.

Field HeaderValue RequiredFormatDescription
sourcedIdYesGUIDUnique ID for the class/resource association. SourcedId is used in other files and must be unique across all class resources.
statusYes for DeltaEnumerationPermitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode.
dateLastModifiedYes for DeltaDateTimeThe date that this record was last modified.This MUST NOT be used for the Bulk mode.
titleNoStringName of the related class.
classSourcedIdYesGUID Reference.SourcedId of the reference Class.This value must reference a sourcedId in the classes.csv file.
resourceSourcedIdYesGUID 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.

Field HeaderValue RequiredFormatDescription
sourcedIdYesGUIDUnique ID for the course/resource association. SourcedId is used in other files and must be unique across all course resources.
statusYes for DeltaEnumerationPermitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode.
dateLastModifiedYes for DeltaDateTimeThe date that this record was last modified.This MUST NOT be used for the Bulk mode.
titleNoStringName of the related course.
classSourcedIdYesGUID Reference.SourcedId of the reference Course.This value must reference a sourcedId in the courses.csv file.
resourceSourcedIdYesGUID 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 HeaderValue RequiredFormatDescription
sourcedIdYesGUIDUnique ID of this resource.
statusYes for DeltaEnumerationPermitted values for Delta mode: { active | tobedeleted }.This MUST NOT be used for the Bulk mode.
dateLastModifiedYes for DeltaDateTimeThe date that this record was last modified.This MUST NOT be used for the Bulk mode.
vendorResourceIdYesIDUnique ID of this resource. This value is provided by QuaverEd.
titleNoStringName of this resource.
rolesNoEnumeration ListPermitted values are : { administrator | teacher |aide | guardian | parent | proctor | relative | student }.
importanceNoStringPermitted values: { “primary” | “secondary” }.
vendorIdNoIDThe vendor ID for QuaverEd. This field must be “vnd.qed”.
applicationIdNoIDIdentifier of the application associated with this resource.