Requirements for OneRoster Standard Imports

Districts can upload class roster data corresponding to the OneRoster 1.0 or 1.1 standard by preparing files in .csv format as described in this help topic. Note: Do not mix OneRoster formats; if you import using OneRoster 1.0, you should continue using OneRoster 1.0 for future imports.

This topic also includes steps to prevent unwanted changes being made to your roster after import and update your roster at any any point after your initial import.

Where can I find my school IDs?

Important Requirements and Specifications

File Names

• orgs.csv (OneRoster 1.0 and 1.1)
• users.csv (OneRoster 1.0 and 1.1)
• courses.csv (OneRoster 1.0 and 1.1)
• classes.csv (OneRoster 1.0 and 1.1)
• enrollments.csv (OneRoster 1.0 and 1.1)
• academicSessions.csv (OneRoster 1.0 and 1.1)
• demographics.csv (OneRoster 1.0 and 1.1)
• manifest.csv (OneRoster 1.1 only)

Content of Headers and Fields

• The file format MUST be comma-separated values format (CSV) for the OneRoster standard.
• Each field will be separated by commas, with line breaks between each row.
• Double quotes MUST be used with a field that contains a comma. For example, if you are listing more that one subject area it would be: "music, drama, poetry"
• All seven (OneRoster 1.0) or eight (OneRoster 1.1) files are required, even empty ones. Files which contain no data MUST contain the header fields.
• The header row is required.
• Header fields MUST be named the same as per the field header in the tables below.
• All file names and header fields are case-sensitive.
• Some fields are required (see tables below for details).
• Optional fields with no data MUST simply be empty in the CSV.

How to import OneRoster templates

1. On the Renaissance Home page, select your name in the upper-right corner. In the drop-down list, select Manage Apps & Users.



2. Under New School Year Wizards, select Upload Your Roster.



3. On the Import Rostering Data page, select OneRoster for the import type.



4. To create a snapshot of any existing rostering data in Renaissance and to create templates containing (among other things) required school names and IDs, first, select the school year that you want to export data from. Be sure to select the school year that you also plan to import data into; do not use an export file from a previous school year.



Then, select Generate Roster Export. After it has processed, you will see a red failed or a green complete message. If the export is successful, you will see Complete and the Download link will appear.



The roster export generates OneRoster 1.1 files. OneRoster 1.0 files from other sources can be uploaded by following the steps below.

5. Under step 2, select Download [date export was created] CSV Files. A OneRosterExport.zip file will be downloaded. Save the .zip file and extract the files so you can edit them.



6. Open all of the templates just downloaded from Renaissance.

How can I update the files in Microsoft Excel®?

If you plan to use Excel to update your files, be careful to follow these steps to avoid introducing formatting issues that would cause your data to import incorrectly. Repeat these steps for each file you update.

1. Rename the extension of your file from .csv to .txt.
2. Open Excel.
3. In Excel, browse for the file you renamed and open it. The Import Text Wizard will appear.
4. Under Choose the file type..., select Delimited. Then check the My data has headers box. Select Next.
5. In step 2 of the Import wizard, check the comma box as the delimiter and remove any other selected delimiter. Select Next.
6. In step 3 of the Import wizard:
1. Under Data preview, click in the header of the first column to select it, and then hold down the Shift key; scroll to the right and click the header of the last column in the file to select all the columns.
2. Under Column data format, select Text to change the format of all the column headers from General to Text.
3. Select Finish.
7. Your file will open and you can update it. Make any changes and save the file.
8. When you are done and the file is ready to import, change the file name extension back from .txt to .csv.
9. Continue with the steps below.
7. In your external rostering tool (such as OneRoster or some other SIS system), create export files and open the file(s) to edit them.
8. OneRoster 1.0 or 1.1 standard files can be imported.

If you are using the OneRoster 1.1 file that was exported in the steps above, in the export files from your external rostering tool, copy all of the columns that match the Renaissance columns. Note: If the columns in your file do not match the Renaissance downloaded files, your imports will fail.

If you will be importing OneRoster 1.0 files, make sure they follow the specifications below.

Which columns do I need and which fields are required?

These tables, one for each file, list the necessary column headers and indicate which fields are required by Renaissance to have data (shaded rows), those that are not required to have data (white rows), and important notes to help you enter the correct information in each field. Column headers specific to Renaissance are the darker shaded rows at the end of each table.

Orgs.csv (1.0 and 1.1)

Column Header	Required	Notes
sourcedId	YES	Unique ID for the organization. SourcedId is used in other files and must be unique across all organizations (for example, schools in your district).
status	NO	"active" | "inactive" | "tobedeleted". A tobedeleted object may be deleted in receiving systems if it already exists.
dateLastModified	NO	The date that this record was last modified (format is YYYY-MM-DD).
name	YES	Name of the organization.
type	YES	"school" | "local" | "state" | "national"
identifier	NO	NCES ID (National Center for Education Statistics) for the school/district.
metadata.classification	NO	"charter" | "private" | "public"
metadata.gender	NO	"female" | "male" | "mixed"
metadata.boarding	NO	True if school is boarding school.
parentSourceID (OneRoster 1.1 only)	NO	SourceID of an org representing the parent organization.
parentSourcedId	NO	SourcedId of the Parent organization.
metadata.stateId	NO	string
renaissanceId	NO	A GUID (ex: 91d60007-3e8c-49c4-8960-dc625d3cd6aa). These will be present in exported files.

Users.csv (1.0 and 1.1)

Column Header	Required	Notes
sourcedId	YES	Unique ID for the user. SourcedId is used in other files and must be unique across all users.
status	NO	"active" | "inactive" | "tobedeleted". A tobedeleted object may be deleted in receiving systems if it already exists.
dateLastModified	NO	The date that this record was last modified (format is YYYY-MM-DD).
enabledUser (OneRoster 1.1 only)	YES	Boolean: { "true" | "false" } "false" denotes that the user is an active record, but system access is curtailed according to the local administration rules.
orgSourcedIds	YES	SourcedIds of the Organizations to which this user belongs. If multiple IDs are required, then use double quotes and separate with commas. Note that in most cases, it is expected that users will belong to a single school.
role	YES	"teacher", "student", "parent", "guardian", "relative", "aide", "administrator"
username	YES	Username Note: If the username is not included, one will be generated. For personnel, the generated username includes the user's first initial and the full last name. For students, the generated user name includes the student's first initial and the first four characters of the student's last name. If a generated username is already in use for either personnel or a student, a number is added to the username.
userId	NO	External machine-readable ID (e.g. LDAP ID, LTI ID) for this user, to be used if the sourcedId should not be used.
givenName	YES	User's first name.
familyName	YES	User's surname.
identifier	NO	Identifier for the user with a human-readable meaning.
grades (OneRoster 1.1 only)	NO	Grade(s) for which a user with the 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. NOTE: Since a student must have a grade level set before taking a Star test, including a grade level is recommended. For OneRoster 1.1 imports, this is the field that sets students' grades.
password	NO	The password for the user. This may or may not be an encrypted string. If it is encrypted, the systems processing it must be aware of the encryption method. Note: If a password is not provided, one will be generated. For personnel, the generated password is the same as the username. For students, the generated password is abc.
email	NO	Email address for the user.
sms	NO	SMS address for the user.
phone	NO	Phone number for the user.
agents (OneRoster 1.0) or agentSourceIds (OneRoster 1.1)	NO	SourcedIds of the users to which this user has a relationship. If multiple IDs are required, then use double quotes and separate with commas. Note: In most cases, this will be for indicating parental relationships.
ext_renaissance_middleName	NO
ext_renaissance_salutation	NO
ext_renaissance_statePersonnelId	NO
ext_renaissance_stateStudentId	NO
ext_renaissance_suffix	NO
ext_renaissance_gradeTag	NO	A number or a string: "1-12" or "Pre-K" or "K". NOTE: Since a student must have a grade level set before taking a Star test, including a grade level is recommended. For OneRoster 1.0 imports, this is the field that sets students' grades.
renaissanceId	NO	A GUID (for example, 91d60007-3e8c-49c4-8960-dc625d3cd6aa). These will be present in exported files.

Courses.csv (1.0 and 1.1)

Column Header	Required	Notes
sourcedId	YES	Unique ID for the course. SourcedId is used in other files and must be unique across all courses.
status	NO	"active" | "inactive" | "tobedeleted". A tobedeleted object may be deleted in receiving systems if it already exists.
dateLastModified	NO	The date that this record was last modified (format is YYYY-MM-DD).
schoolYearId (OneRoster 1.0) or schoolYearSourceId (OneRoster 1.1)	NO	School year in which course runs. This is the sourcedId of an academic Session (see below).
metadata.duration (OneRoster 1.0 only)	NO	Description of how long the course runs for (for example, two weeks, one semester).
title	YES	Name of the course.
courseCode	NO	Human-readable course code.
grade (OneRoster 1.0 only)	NO	Grade (for example, 9 or a range such as 9-12).
grades (OneRoster 1.1 only)	NO	Grade(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
orgSourcedId	NO	SourcedId of the org to which this course belongs. This may be a district-level org ID.
subjects	NO	Subject name(s). If more than one subject is needed, use double quotes, and separate with commas (per RFC 4180): Examples: "chemistry, physics" physics "music, drama, poetry"
subjectCodes (OneRoster 1.1 only)	NO	Subject code(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.
renaissanceId	NO	A GUID (for example, 91d60007-3e8c-49c4-8960-dc625d3cd6aa). These will be present in exported files.

Classes.csv (1.0 and 1.1)

Column Header	Required	Notes
sourcedId	YES	Unique ID for the class. SourcedId is used in other files and must be unique across all classes.
status	NO	"active" | "inactive" | "tobedeleted". A tobedeleted object may be deleted in receiving systems if it already exists.
dateLastModified	NO	The date that this record was last modified (format is YYYY-MM-DD).
title	YES	Name of this class.
grade (OneRoster 1.0 only)	NO	Grade (such as 9 or a range such as 9-12).
grades (OneRoster 1.1 only)	NO	Grade(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
courseSourcedId	NO (for 1.0) or YES (for 1.1)	SourcedId of the course of which this class is an instance.
classCode	NO	Human-readable code used to help identify this class.
classType	YES	"homeroom", "scheduled"
location	NO	Human-readable description of where the class is physically located.
schoolSourcedId	YES	SourcedId of the organization which teaches this class.
termSourcedId	YES	SourcedId of the academicSessions(s) in which the class is taught. If more than one term is needed, use double quotes and delimit with commas, (per RFC 4180). Examples: "1,2" 1 "1,4,8"
subjects	NO	Subject name(s). If more than one subject is needed, use double quotes, and delimit with commas (per RFC 4180): Examples: "chemistry, physics" physics "music, drama, poetry"
subjectCodes (OneRoster 1.1 only)	NO	Subject code(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. The vocabulary is from SCED (School Codes for the Exchange of Data): http://ceds.ed.gov/ScedCourseCodes.aspx (any commas in the label should be removed).
periods (OneRoster 1.1 only)	NO	The 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 (per RFC 4180). Examples: 1, "1,3,5"
renaissanceId	NO	A GUID (for example, 91d60007-3e8c-49c4-8960-dc625d3cd6aa). These will be present in exported files.

Enrollments.csv (1.0 and 1.1)

Column Header	Required	Notes
sourcedId	YES	ID of this enrollment.
classSourcedId	YES	ID of this class.
schoolSourcedId	YES	ID of the school.
userSourcedId	YES	ID of the user (teacher or student).
role	YES	"student" | "teacher" | "parent" | "guardian" | "relative" | "aide" | "administrator"
status	NO	"active" | "inactive" | "tobedeleted". A tobedeleted object may be deleted in receiving systems if it already exists.
dateLastModified	NO	The date that this record was last modified (format is YYYY-MM-DD).
primary	NO	MUST only be set to true for ONE teacher for a class.
beginDate (OneRoster 1.1 only)	NO	The start date for the enrollment. This date must align with the associated academic session (term) identified in the class.
endDate (OneRoster 1.1 only)	NO	The end date for the enrollment (exclusive). This date must align with the associated academic session (term) identified for the class.
renaissanceId	NO	A GUID (for example, 91d60007-3e8c-49c4-8960-dc625d3cd6aa). These will be present in exported files.

AcademicSessions.csv (1.0 and 1.1)

Column Header	Required	Notes
sourcedId	YES	SourcedId of this academicSession. AcademicSessions are used in other files and need to be unique across all academicSessions.
status	NO	"active" | "inactive" | "tobedeleted". A tobedeleted object may be deleted in receiving systems if it already exists.
dateLastModified	NO	The date that this record was last modified (format is YYYY-MM-DD).
title	YES	Name or title of the grading period.
type	YES	"term" | "gradingPeriod" | "schoolYear" | "semester"
startDate	YES	Start date of academic session. Use format YYYY-MM-DD.
endDate	YES	End date of academic session. Use format YYYY-MM-DD.
schoolyear (OneRoster 1.1 only)	YES	The school year for which the academic session contributes. This year should be that in which the school year ends (format is YYYY).
parentSourcedId	NO	Sourced ID of parent of this academic session.
metadata.orgSourcedId	NO	School sourcedId that this particular academicSession is under.
renaissanceId	NO	A GUID (for example, 91d60007-3e8c-49c4-8960-dc625d3cd6aa). These will be present in exported files.

Demographics.csv (1.0 and 1.1)

Column Header	Required	Notes
userSourcedId	YES	SourcedId of the user to which the demographics refer. Typically this will be a student.
status	NO	"active" | "inactive" | "tobedeleted". A tobedeleted object may be deleted in receiving systems if it already exists.
dateLastModified	NO	The date that this record was last modified (format is YYYY-MM-DD).
birthdate	YES	Student's date of birth
sex	YES	"Female" | "Male"
americanIndianOrAlaska Native	YES	Boolean "Yes" or "No"
asian	YES	Boolean "Yes" or "No"
blackOrAfricanAmerican	YES	Boolean "Yes" or "No"
nativeHawaiianOrOther PacificIslander	YES	Boolean "Yes" or "No"
white	YES	Boolean "Yes" or "No"
demographicRaceTwo OrMoreRaces	YES	Boolean "Yes" or "No"
hispanicOrLatinoEthnicity	YES	Boolean "Yes" or "No"
countryOfBirthCode	YES	Vocabulary - https://ceds.ed.gov/CEDS ElementDetails.aspx?TermxTopicId=20002
stateOfBirthAbbreviation	YES/NO*	Vocabulary - https://ceds.ed.gov/CEDS ElementDetails.aspx?TermxTopicId=20837 *Note: For US and US territories, this field should be considered mandatory. Outside of the US, this field is optional.
cityOfBirth	YES
publicSchoolResidenceStatus	YES	Vocabulary - https://ceds.ed.gov/CEDS ElementDetails.aspx?TermxTopicId=20863
ext_renaissance_language	NO	"en-GB" or "en-US" or "en-AU" for English or "es-MX" or "es-US" for Spanish.
ext_renaissance_customCharacteristic	NO	File specifies the custom characteristics.
ext_renaissance_demoCharacteristic	NO	"At-Risk Students", "Bilingual Education", "Free Lunch", "Limited English Proficiency (LEP)", "Title I"

Manifest.csv (OneRoster 1.1 only)

The manifest file will consist of just two columns with the headers "propertyName" and "value". Each row will contain a single property/value pair. The list of supported property/value pairs is described below.

Property Name (one per row)	Required	Format	Value Description
manifest.version	Yes	String	The version of the manifest. For an initial value this must be "1.0".
oneroster.version	Yes	String	The OneRoster version supported by this file set. This must be "1.1".
file.academicSessions	Yes	Enumeration	Each 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.categories	Yes	Enumeration
file.classes	Yes	Enumeration
file.classResources	Yes	Enumeration
file.courses	Yes	Enumeration
file.courseResources	Yes	Enumeration
file.demographics	Yes	Enumeration
file.enrollments	Yes	Enumeration
file.lineItems	Yes	Enumeration
file.orgs	Yes	Enumeration
file.resources	Yes	Enumeration
file.results	Yes	Enumeration
file.users	Yes	Enumeration
source.systemName	No	String	The name for the system producing the set of files.
source.systemCode	No	String	Identification code for the system producing the set of file.

9. Save all the files. If you prefer to combine your files into a .zip file, name the file Roster.zip.
10. In Renaissance, on the Import Rostering Data page for the OneRoster import type, you can upload your files:
• If you have one Roster.zip file that contains the .csv files, drag and drop it into the first upload field.



After you upload the file, you'll see it listed in the field. You can select Delete if you decide not to use this file.



• If you have .csv files, drag the seven (OneRoster 1.0) or eight (OneRoster 1.1) files into the second upload field (Multiple .CSV files).



After you upload the files, you will see each one listed in the field. You can select the Delete link for any file that you want to remove and replace.



Instead of dragging files into the fields, you can select the upload from your computer link in the appropriate field to find and open your file(s).

11. Select Import.
12. Review the Most Recent Import Status at the top of the page to see the progress of your import. Select View Import Log to open the log file with information about how the import went. (See Import History page for more information.)

How do I prevent unwanted changes to my roster?

Set Data Editing Restrictions to prevent anyone from modifying rostering information within Renaissance.

How do I update my roster?

To make any changes, additions, deletions, or corrections to the OneRoster data, make those changes in your external rostering tool, then repeat these steps from the beginning to import the updated files again.