Imagine Math

OneRoster 1.1 file specifications

Populating OneRoster v1.1 templates

The OneRoster™ v1.1 standard has been developed by IMS Global Learning Consortium® to facilitate the exchange of roster information and grades between an educational organization and a software vendor. OneRoster™ is a trademark of IMS Global Learning Consortium, Inc. You can use OneRoster™ v1.1 CSV files to import data in Imagine Learning programs.

OneRoster™ v1.1 CSV files are sent as a .zip file, which includes a manifest.csv file that lists the files in the .zip file. There are 14 OneRoster™ v1.1 files:

The files must be in CSV format, and filenames must match OneRoster™ v1.1 specifications, which dictate specific filenames with exact spelling in the mixed case shown above. If your Student Information System (SIS) exports data in OneRoster™ format, you don't need to format CSV files manually; simply export the SIS data and give the resulting CSV files to an Imagine Learning Data Integration Specialist. You can securely transfer CSV files to the Imagine Learning Data Integration team using the secure Upload roster files form.

 

Since Imagine Learning programs only import rostering information (not gradebook or resource information), only these files are required for an import: (manifest.csv, academicSessions.csv, classes.csv, courses,csv, demographics.csv, enrollments.csv, orgs.csv, and users.csv. If you omit any of the other files, the manifest.csv must still list them, but as being "absent" in the .zip file.

To populate OneRoster™ v1.1 templates

  1. Click the link to download a .zip file containing the OneRoster™ templates.
  2. Unzip its CSV files.
  3. Populate each CSV file with the necessary data.
  4. Zip the files, including the manifest.csv file.

Field information for OneRoster™ templates

The following tables list descriptions of required and optional fields in each template. The columns are position sensitive, and column names are case sensitive. All columns must be present in the header row, whether optional or not, but you can omit values in any data row under the optional columns.

A full or incremental import is determined by the values given in the dateLastModified and status fields. For each file, the import will be incremental if both fields are set in every record; it is a full import if both fields are empty in every record. The import file is in error if some records fill in both columns, and other records omit both columns within the same file. A record error occurs when a record contains information in one of these columns and leaves the other blank. If a file is incremental, then the manifest property for that file should contain the value delta, otherwise it should contain the value bulk.

manifest.csv fields

This file has two fields: propertyName and value. Both fields are required. As with all OneRoster fields, the order and case of these fields is significant.

These are the properties (the individual data rows) that you include in this file, with a description of the values allowed for each property. Most properties are required. For optional properties, you can omit the row.

Property

Required

Value description

manifest.version

Yes

The version of the manifest. Currently this value must be the string 1.0.

oneroster.version

Yes

The OneRoster version supported by this file set. Currently this value must be the string 1.1.

file.academicSessions

Yes

The value is absent, bulk, or delta with these meanings:

  • absent - this CSV file is not supplied;
  • bulk - this CSV file contains only bulk data (a full import of all records);
  • delta - this CSV file contains only delta data (an incremental report of only records that have changed recently).

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 over this property value.

This file can be absent only if the file set does not create any new classes.

file.categories

Yes

String values absent, bulk, or delta (see the description above). Since Imagine Learning programs only import rostering files, this value can be absent.

file.classes

Yes

String values absent, bulk, or delta (see the description above). This file can be absent only if the file set does not enroll any teachers or students in new classes.

file.classResources

Yes

String values absent, bulk, or delta (see the description above). Since Imagine Learning programs only import rostering files, this value can be absent.

file.courses

Yes

String values absent, bulk, or delta (see the description above). This file can be absent only if the file set does not associate a class with any new course.

file.courseResources

Yes

String values absent, bulk, or delta (see the description above). Since Imagine Learning programs only import rostering files, this value can be absent.

file.demographics

Yes

String values absent, bulk, or delta (see the description above). This file can be absent only if the file set defines no new users.

file.enrollments

Yes

String values absent, bulk, or delta (see the description above). This file can be absent only if the file set does define or change the assignment of any users to classes.

file.lineItems

Yes

String values absent, bulk, or delta (see the description above). Since Imagine Learning programs only import rostering files, this value can be absent.

file.orgs

Yes

String values absent, bulk, or delta (see the description above). This file can be absent only if not changing any existing user's school assignment or creating a new user.

file.resources

Yes

String values absent, bulk, or delta (see the description above). Since Imagine Learning programs only import rostering files, this value can be absent.

file.results

Yes

String values absent, bulk, or delta (see the description above). Since Imagine Learning programs only import rostering files, this value can be absent.

file.users

Yes

String values absent, bulk, or delta (see the description above). This file can be absent if the file set does not create any new user or update any existing user.

source.systemName

No

A string that represents the name of the system producing this set of files. You may omit this entry.

source.systemCode

No

A string that represents an identification code for the system producing this set of files. You may omit this entry.

academicsessions.csv fields

Field

Required

Description

sourcedId

Yes

Enter the identifier that has been assigned to this academic session. In this and other files, you use this number to assign classes and courses to specific academic sessions. This number is a primary identifier; it uniquely identifies the academic session and must not change from one import to the next.

status

No

For a full import, leave this field blank. For an incremental import, enter active or tobedeleted, depending on whether this record was recently added or changed versus recently deleted. If you assign the status to be deleted, the information will be deleted if it already exists.

dateLastModified

No

For a full import, leave this field blank. For an incremental import, enter the date when the record was last modified or deleted in this format: YYYY-MM-DD.

title

Yes

Enter the name or title of the grading period. Imagine Learning programs ignore this value.

type

Yes

Enter term, gradingPeriod, schoolYear, semester. Imagine Learning programs ignore this value.

startDate

Yes

Enter the start date of the session in this format: YYYY-MM-DD. Imagine Learning programs only import administrators, teachers, and students who are enrolled in current classes as determined by the academic session's startDate and endDate (inclusive). It will not assign administrators, teachers, or students to classes that ended in the past or that start in the future.

endDate

Yes

Enter the end date of the session in this format: YYYY-MM-DD. Imagine Learning programs only imports administrators, teachers, and students who are enrolled in current classes as determined by the academic session's startDate and endDate (inclusive).

parentSourcedId

No

Enter the sourcedId of the parent of this academic session. Imagine Learning programs ignore this value.

categories.csv fields

 

Imagine Learning programs ignore the data rows in this file. If you like, you can leave it out of the .zip file and mark it as absent in the manifest. If it is easier for you to include the file, see IMS Global documentation for its field requirements.

classes.csv fields

Field

Required

Description

sourcedId

Yes

Enter the district- or SIS-defined identifier for each class. In this and other files, you use this number to assign users to a class. This number is a primary identifier; it uniquely identifies the class and must not change from one import to the next.

status

Yes for delta

For a full import, leave this field blank. For an incremental import, enter active or tobedeleted. If you assign the status to be deleted, the information will be deleted if it already exists.

dateLastModified

Yes for delta

For a full import, leave this field blank. For an incremental import, enter the date when the record was last modified in this format: YYYY-MM-DD.

title

Yes

Enter the name of the class.

grades

No

Enter a list of grades or grade ranges (e.g., 03 or 03-05). If more than one, enclose in double quotes and separate with commas (e.g., "02,04"). Grade levels are coded using the Common Education Data Standards (CEDS) Version 5 Entry Grade Level element.

courseSourcedId

No

Format is a GUID. Enter the sourcedId of the course with which this class is associated. Imagine Learning programs ignore this value.

classCode

No

Enter a class code. This information should be human readable. Imagine Learning programs ignore this value.

classType

Yes

Enter homeroom or scheduled. Imagine Learning programs ignore this value.

location

No

Enter a description of where the class is physically located. This information should be human readable. Imagine Learning programs ignore this value.

schoolSourcedId

Yes

Enter the sourcedId of the organization which offers this class.

termSourcedId

Yes

Enter the sourcedId of the academic session in which the class is taught. If you need to enter more than one academic session, enclose academicSessions sourcedIds in double quotes and separate them with commas according to CSV conventions.

subjects

No

Enter the subject name(s). If you need to enter more than one subject, enclose subject names in double quotes and separate them with commas according to CSV conventions (e.g., "reading,math"). Imagine Learning programs ignore this value.

subjectcodes

No

A list of subjectCodes. These are paired with subjects above. If you need to enter more than one subject code, enclose them in double quotes and separate them with commas according to CSV conventions (e.g., "400,401"). Imagine Learning programs ignore this value.

periods

No

A list of time slots in the day that the class will be given. If you need to enter more than one period, enclose them in double quotes and separate them with commas according to CSV conventions (e.g., "1,3,5"). Imagine Learning programs ignore this value.

ext_imagineLearning_
databaseId

No

Optional export extension field. When exporting data, the Include Ids check box in the Import and Export utility will include this data. When this file is then re-imported into an Imagine Learning program, the exact record will be found. Omit this column for any import file that did not come from an export of records from an Imagine Learning program.

ext_imagineLearning_
organizationDatabaseIds

No

Optional export extension field. Contains the Imagine Learning program organization database ID. Omit this column for any import file that did not come from an export of records from an Imagine Learning program.

classResources.csv fields

 

Imagine Learning programs ignore the data rows in this file If you like, you can leave it out of the .zip file and mark it as absent in the manifest. If it is easier for you to include the file, see IMS Global documentation for its field requirements.

courses.csv fields

 

Imagine Learning programs ignore the data rows in this file except to validate that they follow the OneRoster 1.1 specifications.

Field

Required

Description

sourcedId

Yes

In this and other files, you use this number to assign users to a course. This number is a primary identifier; it uniquely identifies the course and must not change from one import to the next.

status

No

For a full import, leave this field blank. For an incremental import, enter active or tobedeleted. If you assign the status to be deleted, the information will be deleted if it already exists.

dateLastModified

No

For a full import, leave this field blank. For an incremental import, enter the date when the record was last modified in this format: YYYY-MM-DD.

schoolYearSourceId

No

Enter the sourceId of the academic session in which the course runs.

title

Yes

Enter the name of the course.

courseCode

No

Enter a course code. The information should be human readable.

grades

No

Enter a list of grades or grade ranges (e.g., 03 or 03-05). If more than one, enclose in double quotes and separate with commas (e.g., "02,04". Grade levels are coded using the Common Education Data Standards (CEDS) Version 5 Entry Grade Level element.

orgSourcedId

Yes

Enter the sourcedId of the organization to which this course belongs.

subjects

No

Enter the subject name (e.g., reading). If you need to enter more than one subject name, enclose multiple names in double quotes and separate them with commas according to CSV conventions (e.g., "reading, math").

subjectCodes

No

If the 'subjects' attribute is present then the subjects and subjectCodes lists must have the same length and follow the same order so they are paired by position. The code vocabulary is from the School Codes for the Exchange of Data (SCED) Version 4.

courseResources.csv fields

 

Imagine Learning programs ignore the data rows in this file. If you like, you can leave it out of the .zip file and mark it as absent in the manifest. If it is easier for you to include the file, see IMS Global documentation for its field requirements.

demographics.csv fields

 

Imagine Learning programs ignore the data rows in this file except to validate that they follow the OneRoster 1.1 specifications.

Field

Required

Description

sourcedId

Yes

Enter the sourcedId of the user to which the demographics refer. This user will typically be a student.

status

No

For a full import, leave this field blank. For an incremental import, enter active or tobedeleted. If you assign the status to be deleted, the information will be deleted if it already exists.

dateLastModified

No

For a full import, leave this field blank. For an incremental import, enter the date when the record was last modified in this format: YYYY-MM-DD.

birthdate

No

Enter the student's date of birth in this format: YYYY-MM-DD.

sex

No

Enter female, or male.

americanIndianOrAlaskaNative

No

Enter true or false.

asian

No

Enter true or false.

blackOrAfricanAmerican

No

Enter true or false.

nativeHawaiianOrOther
PacificIslander

No

Enter true or false.

white

No

Enter true or false.

demographicRaceTwoOrMore
Races

No

Enter true or false.

hispanicOrLatinoEthnicity

No

Enter true or false.

countryOfBirthCode

No

Enter the code for the country of birth. Click the link to access Common Education Data Standards Country of Birth codes.

stateOfBirthAbbreviation

No

Enter the abbreviation for the state of birth. Click the link to access Common Education Data Standards State of Birth codes. This field is mandatory for US and US territories.

cityOfBirth

No

Enter the city of birth.

publicSchoolResidenceStatus

No

Enter the public school residence status. Click the link to access a definition and codes for Common Education Data Standards Public School Residence Status.

enrollments.csv fields

Field

Required

Description

sourcedId

Yes

Enter the sourcedId of this enrollment.

status

No

For a full import, leave this field blank. For an incremental import, enter active or tobedeleted. If you assign the status to be deleted, the information will be deleted if it already exists.

dateLastModified

No

For a full import, leave this field blank. For an incremental import, enter the date when the record was last modified in this format: YYYY-MM-DD.

classSourcedId

Yes

Enter the sourcedId of the class involved in this enrollment (user-to-class relationship).

schoolSourcedId

Yes

Enter the sourcedId of the school involved in this enrollment.

userSourcedId

Yes

Enter the sourcedId of the user involved in this enrollment (user-to-class relationship).

role

Yes

Enter administrator, aide, guardian, parent, proctor, relative, student, or teacher. This value defines the relationship of the user to the class in this enrollment. Imagine Learning programs process enrollments for administrator, student, and teacher roles, but skip any enrollment where the role is parent, guardian, relative, aide, or proctor.

primary

No

Applicable only for teachers. If the teacher is the primary teacher for this class, enter true otherwise false. Of all teachers enrolled in the same class, only one should have this value marked true. Imagine Learning programs associate all teachers with their enrolled classes whether they are the primary teacher for the class or not.

beginDate

No

Enter the first date of this user's enrollment in this class in this format: YYYY-MM-DD. Imagine Learning programs only import current student/teacher assignments to classes.

endDate

No

Enter the last date of this user's enrollment in this class in this format: YYYY-MM-DD. Imagine Learning programs only import current student/teacher assignments to classes.

lineitems.csv fields

 

Imagine Learning programs ignore the data rows in this file. If you like, you can leave it out of the .zip file and mark it as absent in the manifest. If it is easier for you to include the file, see IMS Global documentation for its field requirements.

orgs.csv fields

Field

Required

Description

sourcedId

Yes

Unique id for the organization. The sourcedId is used in other files to associate users, classes, courses, and enrollments to this organization. This number is a primary identifier; it uniquely identifies the organization and must not change from one import to the next.

status

No

For a full import, leave this field blank. For an incremental import, enter active or tobedeleted. If you assign the status to be deleted, the information will be deleted if it already exists.

dateLastModified

No

For a full import, leave this field blank. For an incremental import, enter the date when the record was last modified in this format: YYYY-MM-DD.

name

Yes

Enter the name of the organization as you want it to appear in the portal.

type

Yes

Enter department, school, district, local, state, or national. An Imagine Learning program will interpret a local organization the same way as a district. While it imports department, state, and national organizations, it does not process them either as districts or as schools, so it will not associate students to them.

identifier

No

Enter the National Center for Education Statistics ID (NCES ID) for the school or district. Imagine Learning programs ignore this value.

parentSourcedId

No

Enter the sourcedId of this organization's parent organization. An organization can't list itself as its own parent. If the parentSourcedId is missing, Imagine Learning puts this organization at the top level of the import site into which you upload this file.

resources.csv fields

 

Imagine Learning programs ignore the data rows in this file. If you like, you can leave it out of the .zip file and mark it as absent in the manifest. If it is easier for you to include the file, see IMS Global documentation for its field requirements.

results.csv fields

 

Imagine Learning programs ignore the data rows in this file. If you like, you can leave it out of the .zip file and mark it as absent in the manifest. If it is easier for you to include the file, see IMS Global documentation for its field requirements.

users.csv fields

Field

Required

Description

sourcedId

Yes

This number is a primary identifier; it uniquely identifies the user and must not change from one import to the next.

status

No

For a full import, leave this field blank. For an incremental import, enter active or tobedeleted. If you assign the status to be deleted, the information will be deleted if it already exists.

dateLastModified

No

For a full import, leave this field blank. For an incremental import, enter the date when the record was last modified in this format: YYYY-MM-DD.

enabledUser

Yes

Enter true or false, where 'false' denotes that the user is an active record but system access is curtailed according to the local administration rules. Imagine Learning programs ignore this field and treats all users as enabled.

orgSourcedIds

Yes

Enter the sourcedId of the organization to which this user belongs. If the user belongs to more than one organization, enclose multiple IDs in double quotes and separate them with commas according to CSV conventions.

role

Yes

Enter administrator, aide, guardian, parent, proctor, relative, student, or teacher. An Imagine Learning program imports administrators, students, and teachers, but skips any record where the user's role is parent, guardian, relative, aide, or proctor.

username

Yes

Enter the username. For students, this becomes the Imagine Learning program username. For teachers and administrators, the email field becomes the username.

userIds

No

Enter a list of IDs associated with this user by other products or standards (e.g., an LDAP or LTI identity). Enclose these identifiers in curly braces and prefix them with the product or standard designation and a colon (such as {LDAP:id} or {Fed:id}). If you have multiple IDs, enclose them in double quotes and separate them with commas according to CSV conventions. Imagine Learning programs ignore this value.

givenName

Yes

Enter the user's first name.

familyName

Yes

Enter the user's last name.

middleName

No

Enter the user's middle name. Imagine Learning programs ignore this value.

identifier

No

Enter a human readable identifier for the user (e.g., a student ID). Imagine Learning programs ignore this value.

email

No

Enter an email address for the user. For teachers and administrators, Imagine Learning programs ignore this field for students. For teachers and administrators, an Imagine Learning program requires this field and stores it as the username. If it is blank, an Imagine Learning program uses the username field instead of the email field, but will skip such a user if the username is not an email address.

sms

No

Enter the SMS address for the user. Imagine Learning programs ignore this value.

phone

No

Enter the user's phone number. Imagine Learning programs ignore this value.

agentSourcedIds

No

Enter the sourcedIds of users to which this user has a relationship. This information is used to indicate parental relationships, in most cases. Enclose multiple IDs in double quotes and separate them with commas according to CSV conventions. Imagine Learning programs ignore this value.

grades

No

For students, enter the student's grade. The permitted grade values are PK, KG, 01 through 12, and Other. If a student is associated with more than one grade, enclose the grades in double quotes and separate them with commas according to CSV conventions. If multiple grades are present, an Imagine Learning program uses only the first grade from the list. If the grades field has no value, an Imagine Learning program sets the student's grade to Other. Imagine Learning programs ignore this field for non-students.

password

No

The password for the user. Imagine Learning programs ignore this field for non-students. For students, Imagine Learning programs use this value as the student password. If the password field is empty and this is not a delta record (incremental update), Imagine Learning programs use the student's username as the initial password instead. If students or their teachers change this password in an Imagine Learning program, subsequent imports will not change the manually set password. Note that this value is not needed if the student accesses an Imagine Learning program through Single Sign-On (SSO). For non-students, Imagine Learning programs will not set user passwords, but will send email to new users with instructions on setting their passwords to activate their accounts.

ext_imagineLearning_ssoId

No

Optional extension field that contains the SSO identity provider record ID for this user. You only need to use this field if your users access Imagine Learning programs through Single Sign-On (SSO) and the users.csv file's username field does not contain the ID by which your identity provider identifies this user.

ext_imagineLearning_
studentLanguage

No

Optional export extension field that contains the student's first language. Supported languages are English (default value), Arabic, Cantonese, French, Haitian Creole, Hmong, Japanese, Korean, Mandarin, Marshallese, Portuguese (Brazil), Russian, Somali, Spanish, Tagalog, Vietnamese. If this value is present, Imagine Learning programs can present instructions to students first in their native language and then in English. This field is ignored for non-students.

ext_imagineLearning_
demographics

No

If present and the user's role is student, Imagine Learning programs use this value as a demographics tag on the student record. The district predefines its set of allowed tags and their meanings, often to satisfy legal requirements. Contact Imagine Learning if your district needs to define such demographics tags.