Imagine Language & Literacy

OneRoster™ file specifications

Populating OneRoster™ templates

The OneRoster™ 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. (www.imsglobal.org). You can use OneRoster™ CSV files to import data in Imagine Language & Literacy.

There are seven OneRoster™ templates: orgs.csv, users.csv, courses.csv, classes.csv, enrollments.csv, academicSessions.csv, and demographics.csv. The files must be in CSV format, and filenames must match OneRoster™ 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 Provisioning Specialist.

All of the files are required for an import.

To populate OneRoster™ templates

  1. Click the link to download a .zip file containing the OneRoster™ templates.
  2. Populate each file with the necessary data.

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.

orgs.csv fields

Field

Required

Description

sourcedId

Yes

Enter the number that has been assigned to this organization by the district or by the district SIS. 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

No

For a full import, leave this field blank. For an incremental import, enter active, inactive, or tobedeleted. If you assign the status to be deleted, the information will be deleted in Imagine Language & Literacy 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 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 school, local, state, or national. Imagine Language & Literacy will interpret local as a district, and state or national as "other."

identifier

No

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

metadata.classification

No

Enter charter, private, or public. Imagine Language & Literacy ignores this value.

metadata.gender

No

Enter female, male, or mixed. Imagine Language & Literacy ignores this value.

metadata.boarding

No

Enter true if the school is a boarding school. Imagine Language & Literacy ignores this value.

parentSourcedId

No

Enter the sourcedId of the parent organization. An organization can't list itself as its own parent. If the parentSourcedId is missing, Imagine Language & Literacy 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 Language & Literacy, the exact record will be found. Omit this column from any import file that did not come from an export of Imagine Language & Literacy records.

users.csv fields

Field

Required

Description

sourcedId

Yes

Enter the user's number as defined by the district or by the district SIS. This number is a primary identifier; it uniquely identifies the user and will not change.

status

No

For a full import, leave this field blank. For an incremental import, enter active, inactive, or tobedeleted. If you assign the status to be deleted, the information will be deleted in Imagine Language & Literacy 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.

orgSourcedIds

Yes

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

role

Yes

Enter teacher, student, parent, guardian, relative, aide, or administrator. Imagine Language & Literacy skips any record where the user's role is parent, guardian, relative, or aide.

username

Yes

Enter the username. For students, this becomes the Imagine Language & Literacy username. For teachers and administrators, the email field becomes the username.

userId

No

Enter an ID that can be read by an external machine (e.g., an LDAP or LTI identity). Use this field when the sourcedId should not be used. Imagine Language & Literacy ignores this value.

givenName

Yes

Enter the user's first name.

familyName

Yes

Enter the user's last name.

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 Language & Literacy requires this field. If it is blank, Imagine Language & Literacy 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 Language & Literacy ignores this value.

phone

No

Enter the user's phone number. Imagine Language & Literacy ignores this value.

agents

No

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

ext_imagineLearning_
organizationDatabaseIds

No

Optional export extension field. Contains the Imagine Language & Literacy organization database ID. Omit this column for any import file that did not come from an export of Imagine Language & Literacy 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.

ext_imagineLearning_
studentPassword

No

Optional export extension field. Contains the Imagine Language & Literacy student password. If you know this information, you may include it for each record under this column.

ext_imagineLearning_
studentGrade

No

Optional export extension field. Contains the grade of the student (i.e., pk, k, 1 through 12, or other). If you know this information, you may include it for each student record under this column.

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.

courses.csv fields (Imagine Language & Literacy ignores the data rows in this file.)

Field

Required

Description

sourcedId

Yes

Enter the number that has been assigned to the course by the district or by the district SIS. 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

No

For a full import, leave this field blank. For an incremental import, enter active, inactive, or tobedeleted. If you assign the status to be deleted, the information will be deleted in Imagine Language & Literacy 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.

schoolYearId

No

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

metadata.duration

No

Enter a description of how long the course runs (e.g., two weeks or one semester).

title

Yes

Enter the name of the course.

courseCode

No

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

grade

No

Enter a grade or grade range (e.g., 3 or 3-5).

orgSourcedId

No

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").

classes.csv fields

Field

Required

Description

sourcedId

Yes

Enter the number that has been assigned to the class by the district or by the district SIS. 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

No

For a full import, leave this field blank. For an incremental import, enter active, inactive, or tobedeleted. If you assign the status to be deleted, the information will be deleted in Imagine Language & Literacy 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 of the class.

grade

No

Enter a grade or grade range (e.g., 3 or 3-5). While the OneRoster™ 1.0 standard does not specify how to represent individual grades, Imagine Language & Literacy recommends that you use single digits (or double for grades 10 and higher) with no ordinal suffix or other text. For pre-kindergarten and kindergarten, we recommend using pk and k. Imagine Language & Literacy can use this grade to guess the enrolled students' grade levels if the users.csv file does not include them.

courseSourcedId

No

Enter the sourcedId of the course with which this class is associated. Imagine Language & Literacy ignores this value.

classCode

No

Enter a class code. This information should be human readable. Imagine Language & Literacy ignores this value.

classType

Yes

Enter homeroom or scheduled. Imagine Language & Literacy ignores this value.

location

No

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

schoolSourcedId

Yes

Enter the sourcedId of the organization which teaches 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, separated with commas according to CSV conventions (e.g., "1,4,8").

subjects

No

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

enrollments.csv fields

Field

Required

Description

sourcedId

Yes

Enter the sourcedId of this enrollment.

classSourcedId

Yes

Enter the sourcedId of the class.

schoolSourcedId

Yes

Enter the sourcedId of the school.

userSourcedId

Yes

Enter the sourcedId of the user.

role

Yes

Enter student, teacher, parent, guardian, relative, aide, or administrator.

status

No

For a full import, leave this field blank. For an incremental import, enter active, inactive, or tobedeleted. If you assign the status to be deleted, the information will be deleted in Imagine Language & Literacy 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.

primary

No

Enter true or false. This field should be true for only one teacher for a class. Imagine Language & Literacy ignores this value.

ext_imagineLearning_
classDatabaseId

No

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

ext_imagineLearning_
userDatabaseId

No

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

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, inactive, or tobedeleted. If you assign the status to be deleted, the information will be deleted in Imagine Language & Literacy 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 Language & Literacy ignores this value.

type

Yes

Enter term, gradingPeriod, schoolYear, semester. Imagine Language & Literacy ignores this value.

startDate

Yes

Enter the start date of the session in this format: YYYY-MM-DD. Imagine Language & Literacy 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 Language & Literacy 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 Language & Literacy ignores this value.

demographics.csv fields (Imagine Language & Literacy ignores the data rows in this file.)

Field

Required

Description

userSourcedId

Yes

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

status

No

For a full import, leave this field blank. For an incremental import, enter active, inactive, or tobedeleted. If you assign the status to be deleted, the information will be deleted in Imagine Language & Literacy 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

Yes

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

sex

Yes

Enter female, or male.

americanIndianOrAlaskaNative

Yes

Enter true or false.

asian

Yes

Enter true or false.

blackOrAfricanAmerican

Yes

Enter true or false.

nativeHawaiianOrOther
PacificIslander

Yes

Enter true or false.

white

Yes

Enter true or false.

demographicRaceTwoOrMore
Races

Yes

Enter true or false.

hispanicOrLatinoEthnicity

Yes

Enter true or false.

countryOfBirthCode

Yes

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

Yes

Enter the city of birth.

publicSchoolResidenceStatus

Yes

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

Tags