About OneRoster Template Files

The OneRoster® 1.1 CSV import template includes eight data files. An API version of this template is also available.

➔ For instruction for each OneRoster import workflow, see the following:

➔ Download the OneRoster 1.1 template. (Click to download.)

The table below provides a list of all eight of the OneRoster 1.1 CSV template files, descriptions, and links to detailed file instructions. All eight files must be included in your import.

File Name	Purpose	Field-level Details Click a link to open.
orgs.csv	Used to create and update organization identification.	OneRoster orgs File
users.csv	Used to create and update student and teacher identification.	OneRoster users File
classes.csv	Used to create and update class information and school association. A class is defined as a specific group of students enrolled in the same course at the same school with the same teacher during the same class period. Each class must have a unique ID.	OneRoster classes File
enrollments.csv	Used to create and update the associations between classes, students, and teachers, identifying the class rosters for each class and school within the district.	OneRoster enrollments File
manifest.csv	Used to determine the version of OneRoster is version 1.1 and not an earlier version. Failure to provide a manifest file results in misleading import errors.	OneRoster manifest File
*courses.csv	Data from this file is not stored at this time; for import, include file with only the header row populated.	OneRoster courses File
*academicSessions.csv	Data from this file is not stored at this time; for import, include file with only the header row populated.	OneRoster academicSessions File
*demographics.csv	Data from this file is not stored at this time; for import, include file with only the header row populated.	OneRoster demographics File

*HMH strongly recommends that you populate these files to comply with IMS Certification. Some HMH platforms may not require this data and as such may ignore it; however, to align with IMS standards, you should populate the data in these files. If you leave these files blank with just a header, HMH will process the file at the current time, but you would not be following IMS standards and the file you create may not work with other vendors. Whatever way you choose to populate them, these files must be included in the zipped file that is imported.

Note:

● HMH does not support the OneRoster 1.1 resources.csv file. Instead, use the District Details page to specify the HMH platforms to which your users and classes have access.

● IMS no longer supports OneRoster 1.0 and encourages all users to upgrade to OneRoster 1.1. If you cannot support OneRoster 1.1 files, you can click here for information on the older OneRoster 1.0 Template Files.

● HMH is aware of ongoing standards upgrades in the IMS workspace related to LTI and OneRoster. At this time, IMS has not released OneRoster 1.2 openly to the public. Once it is officially released, HMH will look to prioritize development work and certification to be supported in a future build. Communications will be provided when that occurs.

● Some fields and files deemed optional by HMH are designated as such for roster flexibility, which is unique to HMH. To remain in full compliance with industry expectations, be sure to follow the IMS standards for any files created for and used with platforms or vendors other than HMH. Likewise, some fields that are required by HMH (such as teacher EMAIL and global USERNAME) may be optional by IMS standards, but must be included in HMH platforms for full feature compatibility.

Important:

● If you are moving to the OneRoster template from the Simple File Format (SFF) template, you must first perform a mass inactivation of your accounts in the previous template format.

● If you did not use SFF last year and/or your organization's usernames on ThinkCentral (TC) differ from the usernames in Holt McDougal Online (HMO), then HMH recommends a purge or mass deactivation prior to importing in order to prevent duplicate accounts.

➔ To mass inactivate your existing accounts:

– For SFF, populate just the header rows of the users.csv, class.csv, and classassignments.csv files and then upload.

– For TC, enter a "D" in the Active/Inactive (column R) for all data in the import file and then upload.

– For HMO, enter an "I" in the Activate field (column Q) for all data in the users.csv file and then upload.

CSV File Requirements

The files that you prepare and submit must meet the requirements listed in the following table.

Files Must Be . . .	Additional Details
Saved as CSV (comma delimited) files with quoted identifiers	HMH strongly recommends that you use quoted identifiers because without quoted identifiers, commonly used punctuation in text fields can cause errors during the import process.
Named to match the original file names: – orgs.csv – users.csv – classes.csv – enrollments.csv – manifest.csv – courses.csv – academicSessions.csv – demographics.csv	The file names for each .csv file must be an exact match to the names in the template file.
Combined and compressed into a single, zipped prior to upload	The zipped file must include all of the CSV files and must be named according to the following rules: – Valid Values: alphanumeric (A–Z, a–z, 0–9), dashes ( - ), underscores ( _ ) – Must not contain special characters (except dashes and underscores) – For SFTP site file submissions (automated imports), spaces are not allowed. (Import Management accepts zipped files with spaces, but the SFTP site does not.)
Complete snapshots of your organization's data	HMH supports BULK rostering, which is full files every run. We do not support partial or delta based processing at this time. Imports require that all data be included at the time of the import. Your submitted import files are considered full year-to-date data files, so every import file replaces the last one imported. Always submit full files for all locations if using OneRoster. Examples: – If a data object from a Day 1 file is missing from the Day 2 file, then that data object is deactivated. – If you import 500 users today and then import 15 tomorrow, that triggers the deactivation of 485 users.

Feature Awareness

At this time, OneRoster template imports do not support the following features:

● Team teacher roles for TC and HMO (Team teacher roles are available for Ed, the HMH Learning Platform. For TC and HMO, team teacher data is stored, but not utilized.)

● Identification of specific fields in error reporting (only generic field names are provided); Click to view the OneRoster Reporting Field-Name Conversions.

CSV Required Files

All eight files must be submitted with every import. Which files you must populate, however, depends on the data that your organization wants to manage.

● To manage rosters, you must populate five files—orgs.csv, users.csv, classes.csv, enrollments.csv, and manifest.csv.

● To manage user data only, you need to populate only the orgs.csv and users.csv file. In this case, administrators and teachers must use the features within the application to create classes and rosters.

Note: If your organization uses multiple platforms—Ed, the HMH Learning Platform; ThinkCentral (TC); and/or Holt McDougal Online (HMO)—you must use the same template-type for all platform imports—either OneRoster, SFF, or Traditional (TC and HMO). It is not acceptable to mix the import template types in your imports by using the OneRoster template for one platform and then using the Traditional template for another platform. Only OneRoster and SFF can support Ed.

CSV Required Fields

● All fields in all files should be in quotes to prevent formatting errors.

● Required fields must be populated.

● Fields that are not required may remain empty, but even empty fields must be retained using commas. Do not use a space for an empty field.

● The requirements for a given OneRoster field may depend on the user role (student, teacher, class) of the row being populated. For example, the EMAIL field in the users.csv file is required for teachers but not required for students. These fields must be populated for users with a teacher role and must remain empty for users with a student role.

You must inform your newly added users how they can log in to the platform.

– If you are doing SSO, send them an email personally detailing how to launch from your SSO provider.

– If you are using the Ed or Flight platform login, do either of the following:

○ Select users to receive an email with login information. For details, see Send Login Credentials to School Admins and Teachers in Ed Administrator Help.

○ Direct your newly added teachers and administrators to go to the Ed Sign In page, click the "Request sign in details” link, and follow the instructions. For details, see Request Ed Platform Login Credentials in Ed Administrator Help.

– For TC administrators, any newly added administrator or teacher will get an email. You can manage this preference from the TC platform; see TC-Edit District Configuration Settings for details.

– For HMO administrators, any newly added administrator or teacher will get an email. You can manage this preference from the HMO platform; see HMO-District Settings for details.

For more information about OneRoster, see the following site: https://www.imsglobal.org/activity/onerosterlis

Error Report Field Name	OneRoster Field Name	Example of Error Message	Description
Class Local Id	classes.sourcedId	CLASSLOCALID is missing. This is a required field.	OneRoster is missing a sourcedId field in the class file.
ClassName	classes.title	Duplicate classnames found in the import file. Remove the duplicates. Class will not be created/updated.	HMH automatically appends the Classes.sourcedId value to the beginning of the title (class name) entry, up to 50 characters to help make it unique.
FirstName	givenname	The entry for FIRSTNAME contains invalid characters. Refer to online help for a list of valid characters.	Some HMH applications are limited in the character sets allowed. The givenname field for OneRoster has a maximum character limit of 255, and the following allowable characters: A–Z, a–z, 0–9, spaces, and symbols acceptable See Supported Symbols for complete list. See the OneRoster users File for more details.
grade (student or teacher)	user.metadata.grade	The entry for GRADE is invalid. Valid values are PK–12.	HMH supports users in grades PK–12. CEDS allows grades that go beyond that range, and as such, HMH aligns the grades to the grade closest to PK–12. If you provided a grade level that is not CEDS compliant, it will be rejected.
grade (class)	class.grade	Class could not be created. The entry for GRADE is invalid. Valid values are PK–12.	HMH supports users in grades PK–12. CEDS allows grades that go beyond that range, and as such, HMH aligns the grades to the grade closest to PK–12. If you provided a grade level that is not CEDS compliant, it will be rejected.
LASID	users.sourcedId	Attempting to add a LASID to a class. However the users.csv has no entry for this LASID.	A value in the userSourcedId field of the enrollments.csv file has no corresponding sourcedId in the users.csv file.
LastName	familyname	LASTNAME is missing. This is a required field.	Some HMH applications require a last name (family name). See the OneRoster users File for more details.
USERNAME	metadata.globalusername	This USERNAME is associated with a school in a different district.	The value in the custom field metadata.globalusername is not unique. If necessary, be sure to use a globally unique ID such as john.doe@mydistrict.com.