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 Math.

OneRoster™ v1.1 CSV files are now 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 templates:

The files must be in CSV format, and filenames must match OneRoster™ v1.1 specifications, which dictate specific filenames with exact spelling in lowercase. 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.

 

All of the files are required for an import.

To populate OneRoster™ v1.1 templates

  1. Click the link to download a .zip file containing the OneRoster™ templates.
  2. Populate each file with the necessary data.
  3. 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. 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.

manifest.csv fields

Field

Required

Description

manifest.version

Yes

The version of the manifest. For an initial value this must be "1.0".

oneroster.version

Yes

The OneRoster version supported by this file set. This must be "1.1".

file.academicSessions

Yes

Each file 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.

For academicSessions, write "bulk", or "delta" if this is an update.

file.categories

Yes

For categories, write "absent".

file.classes

Yes

For classes, write "bulk", or "delta" if this is an update.

file.classResources

Yes

For classResources, write "absent".

file.courses

Yes

For courses, write "bulk", or "delta" if this is an update.

file.courseResources

Yes

For courseResources, write "absent".

file.demographics

Yes

For demographics, write "absent".

file.enrollments

Yes

For enrollments, write "bulk", or "delta" if this is an update.

file.lineItems

Yes

For lineItems, write "absent".

file.orgs

Yes

For orgs, write "bulk", or "delta" if this is an update.

file.resources

Yes

For resources, write "absent".

file.results

Yes

For results, write "absent".

file.users

Yes

For users, write "bulk", or "delta" if this is an update.

source.systemName

No

The name for the system producing the set of files.
Omit this entry

source.systemCode

No

Identification code for the system producing the set of files.
Omit this entry

academicsessions.csv fields

Field

Required

Description

sourcedId

Yes

Enter the number that has been assigned to this academic session. In this and other files, you use this number to assign an academic session. This number is a primary identifier; it uniquely identifies the academic session and will not change.

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 in Imagine Math 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.

title

Yes

Enter the name or title of the grading period. Imagine Math ignores this value.

type

Yes

Enter term, gradingPeriod, schoolYear, semester. Imagine Math ignores this value.

startDate

Yes

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

endDate

Yes

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

parentSourcedId

No

Enter the sourcedId of the parent of this academic session. Imagine Math ignores this value.

categories.csv fields

 

Imagine Math ignores the data rows in this file.

Field

Required

Description

sourcedId

Yes

Format is a GUID. This number is a primary identifier; it uniquely identifies the category and will not change.

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 in Imagine Math 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.

classes.csv fields

Field

Required

Description

sourcedId

Yes

Format is a GUID. 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 will not change.

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 in Imagine Math 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., 3 or 3-5). If more than one, enclose in double quotes and separate with commas. 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 Math ignores this value.

classCode

No

Enter a class code. This information should be human readable. Imagine Math ignores this value.

classType

Yes

Enter homeroom or scheduled. Imagine Math ignores this value.

location

No

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

schoolSourcedId

Yes

Enter the sourcedId of the organization which teaches this class.

termSourcedId

Yes

A list of GUIDs. 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, separated 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, separated with commas according to CSV conventions (e.g., "reading,math"). Imagine Math ignores this value.

subjectcodes

No

A list of subjectCodes. These are paired with subjects above. If you need to enter more than one subject, enclose subject names in double quotes, separated with commas according to CSV conventions (e.g., "400,401"). Imagine Math ignores this value.

subjectcodes

No

A list of time slots in the day that the class will be given. If you need to enter more than one subject, enclose subject names in double quotes, separated with commas according to CSV conventions (e.g., "1,3,5"). Imagine Math ignores 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 Imagine Math, the exact record will be found. Omit this column for any import file that did not come from an export of Imagine Math records.

ext_imagineLearning_
organizationDatabaseIds

No

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

classResources.csv fields

 

Imagine Math ignores the data rows in this file.

Field

Required

Description

sourcedId

Yes

Format is a GUID. This number is a primary identifier; it uniquely identifies the class resource and will not change.

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 in Imagine Math 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

No

Enter the name of the related class.

classSourcedId

Yes

Format is a GUID. This is a reference to the associated class in classes.csv. This number is a primary identifier; it uniquely identifies the class and will not change.

resourceSourcedId

Yes

Format is a GUID. This is a reference to the associated resource in resources.csv. This number is a primary identifier; it uniquely identifies the resource and will not change.

courses.csv fields

 

Imagine Math ignores the data rows in this file.

Field

Required

Description

sourcedId

Yes

Format is a GUID. 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 will not change.

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 in Imagine Math 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.

schoolYearId

No

Format is a GUID. Enter the school year in which the course runs. The information in this field is also used as the sourcedId for an academic session.

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., 3 or 3-5). If more than one, enclose in double quotes and separate with commas. Grade levels are coded using the Common Education Data Standards (CEDS) Version 5 Entry Grade Level element.

orgSourcedId

No

Format is a GUID. Enter the sourcedId of the organization to which this course belongs. The orgSourcedId may be the sourcedId of a district.

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, separated with commas according to CSV conventions (e.g., "reading, math").

subject codes

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. The code vocabulary is from the School Codes for the Exchange of Data (SCED) Version 4.

courseResources.csv fields

 

Imagine Math ignores the data rows in this file.

Field

Required

Description

sourcedId

Yes

Format is a GUID. This number is a primary identifier; it uniquely identifies the course resource and will not change.

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 in Imagine Math 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

No

Enter the name of the related course.

courseSourcedId

Yes

Format is a GUID. This is a reference to the associated course in courses.csv. This number is a primary identifier; it uniquely identifies the course and will not change.

resourceSourcedId

Yes

Format is a GUID. This is a reference to the associated resource in resources.csv. This number is a primary identifier; it uniquely identifies the resource and will not change.

demographics.csv fields

 

Imagine Math ignores the data rows in this file.

Field

Required

Description

userSourcedId

Yes

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

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 in Imagine Math if it already exists.

dateLastModified

Yes

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

Format is a GUID. Enter the sourcedId of this enrollment.

classSourcedId

Yes

Enter the sourcedId of the class.

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 in Imagine Math 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.

classSourcedId

Yes

Enter the sourcedId of the class.
Format is a GUID. 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.

schoolSourcedId

Yes

Format is a GUID. Enter the sourcedId of the school.

userSourcedId

Yes

Format is a GUID. Enter the sourcedId of the user.

role

Yes

Enter administrator, aide, guardian, parent, proctor, relative, student, or teacher. This is used to know if the classSourcedid value is for a user or a student. For a user enter teacher or administrator. For student, enter student

primary

No

Applicable only for teachers. If the teacher is the primary teacher, enter true otherwise false. Imagine Math processes all teachers regardless of this setting.

beginDate

No

Enter the beginning date of the enrollment in this format: YYYY-MM-DD. Imagine Math only imports current student/teacher assignments to classes.

endDate

No

Enter the end date of the session in this format: YYYY-MM-DD. Imagine Math only imports current student/teacher assignments to classes.

ext_imagineLearning_
classDatabaseId

No

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

ext_imagineLearning_
userDatabaseId

No

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

lineitems.csv fields

 

Imagine Math ignores the data rows in this file.

Field

Required

Description

sourcedId

Yes

Format is a GUID. This number is a primary identifier; it uniquely identifies the line item and will not change.

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 in Imagine Math 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 or title of the line item. Imagine Math ignores this value.

description

No

Enter the description of the line item. Imagine Math ignores this value.

assignDate

Yes

Enter the date the associated activity was assigned for the line item. Enter in this format: YYYY-MM-DD. Imagine Math ignores this value.

dueDate

Yes

Enter the date the associated activity is due to be completed for the line item. Enter in this format: YYYY-MM-DD. Imagine Math ignores this value.

classSourcedid

Yes

GUID format. Enter the source id for the class. Imagine Math ignores this value.

categorySourcedid

Yes

GUID format. Enter the source id for the category. Imagine Math ignores this value.

gradingPeriodSourcedid

Yes

GUID format. Enter the source id for the grading period (i.e., the academic session). Imagine Math ignores this value.

resultValueMin

Yes

Float format. Enter the minimum value permitted for the score. Imagine Math ignores this value.

resultValueMax

Yes

Float format. Enter the maximum value permitted for the score. Imagine Math ignores this value.

orgs.csv fields

Field

Required

Description

sourcedId

Yes

GUID format. Unique id for the organization. SourcedId is used in other files and must be unique across all organizations. In this and other templates, you use this number to associate schools and users with this organization. This number is a primary identifier; it uniquely identifies the organization and will 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 in Imagine Math 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.

name

Yes

Enter the name of the organization as you want it to appear in Imagine Learning Portal. The organization name is a secondary identifier; it is unique within the site. The first import associates the organization number with this organization name. In subsequent imports, by using the correct organization number, you can change this organization name.

type

Yes

Enter department, school, district, local, state, or national. Imagine Math will interpret local as a district, and department, state and national as "other."

identifier

No

Enter the National Center for Education Statistics ID (NCES ID) for the school or district. Imagine Math ignores this value.

parentSourcedId

No

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

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 Imagine Math, the exact record will be found. Omit this column from any import file that did not come from an export of Imagine Math records.

resources.csv fields

 

Imagine Math ignores the data rows in this file.

Field

Required

Description

sourcedId

Yes

GUID format. Unique id for the resource. SourcedId is used in other files and must be unique across all resources. This number is a primary identifier; it uniquely identifies the resource and will 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 in Imagine Math 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.

vendorResourceId

Yes

Enter the ID of the resource as allocated by the vendor of the resource. The ID is unique in the context of resource identifiers allocated by the vendor.

title

No

Enter the name of the resource.

roles

No

Enter a list of roles administrator, aide, guardian, parent, proctor, relative, student, or teacher. Enclose multiple roles in double quotes separated with commas according to CSV conventions.

importance

No

Enter the importance of the resource as primary or secondary.

vendorid

No

Enter the vendor identifier. This unique ID is assigned by IMS Global during the conformance process.

applicationid

No

Enter the application identifier. This identifier is assigned by the creator/vendor of the resource.

results.csv fields

 

Imagine Math ignores the data rows in this file.

Field

Required

Description

sourcedId

Yes

GUID format. Unique id for the result. SourcedId is used in other files and must be unique across all results. This number is a primary identifier; it uniquely identifies the result and will 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 in Imagine Math 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.

lineItemSourcedId

Yes

GUID format. Unique id for the line item associated with the result. This references a line item in lineitems.csv. This number is a primary identifier; it uniquely identifies the result and will not change from one import to the next.

studentSourcedId

Yes

GUID format. Unique id for the student (user) associated with the result. This references a student in users.csv. This number is a primary identifier; it uniquely identifies the result and will not change from one import to the next.

scoreStatus

Yes

Enter a score status from the list exempt, fullyGraded, notSubmitted, partiallyGraded, or submitted.

score

Yes

Enter a score as a floating point number. The range should be consistent with that defined in the associated lineItem resultValueMin and resultValueMax fields.

scoreDate

Yes

Enter the date the result was submitted in this format: YYYY-MM-DD.

comment

No

Enter a comment about the result.

users.csv fields

Field

Required

Description

sourcedId

Yes

GUID format. This number is a primary identifier; it uniquely identifies the user and will not change.

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 in Imagine Math 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.

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 Math ignores this field and treats all users as enabled.

orgSourcedIds

Yes

Format is a list of GUIDs. 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 separated with commas according to CSV conventions.

role

Yes

Enter administrator, aide, guardian, parent, proctor, relative, student, or teacher. Imagine Math 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 Math username. For teachers and administrators, the email field becomes the username.

userIds

No

Enter a list of IDs that can be used by an external machine (e.g., an LDAP or LTI identity). Use this field when the sourcedId should not be used. Enclose multiple IDs in double quotes separated with commas according to CSV conventions. Imagine Math ignores 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 Math ignores this value.

identifier

No

Enter a human readable identifier for the user (e.g., Student ID).

email

No

Enter an email address for the user. For teachers and administrators, Imagine Math requires this field. If it is blank, Imagine Math uses the username field instead, but that is only valid if it is an email address.

sms

No

Enter the SMS address for the user. Imagine Math ignores this value.

phone

No

Enter the user's phone number. Imagine Math ignores this value.

agentSourcedIds

No

Format is a list of GUIDs. Enter the sourcedIds to which this user has a relationship. This information is used to indicate parental relationships, in most cases. Enclose multiple IDs in double quotes separated with commas according to CSV conventions. Imagine Math ignores this value.

grades

No

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 - ("PK" | "KG" | "01" through "12" | "Other"). If present, Imagine Math uses the first grade from the list. If absent, Imagine Math sets the grade to "Other" for students. It is ignored for non-students.

password

No

The password for the user. Imagine Math uses this for a student password if present and the role is "student". If not present and role is "student" and this is not a delta record, the username is used for the student password instead. It is ignored for non-students.

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 Imagine Math, the exact record will be found. Omit this column for any import file that did not come from an export of Imagine Math records.

ext_imagineLearning_
organizationDatabaseIds

No

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

ext_imagineLearning_ssoId

No

Optional export extension field. Contains the SSO identity provider record ID. If you know this information, you may include it for each record under this column. By default, the student or teacher SSO ID is the username provided in this file. This field, if present, overrides the username field as the SSO ID.

ext_imagineLearning_
studentLanguage

No

Optional export extension field. 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.

ext_imagineLearning_
demographics

No

If present and the role is "student", this is used as a demographics tag in Imagine Math