Requirements for OneRoster Standard Imports

Districts can upload class roster data corresponding to the OneRoster 1.1 standard by preparing files in .csv format as described in this help topic.

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
• users.csv
• courses.csv
• classes.csv
• enrollments.csv
• academicSessions.csv
• demographics.csv
• manifest.csv

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

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.1 standard files can be imported.

If you are using the 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.

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

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	Leave this field blank.
dateLastModified	NO	Leave this field blank.
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.
parentSourcedId	NO	SourcedId of the Parent organization.
metadata.stateId	NO	string

Users.csv

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	Leave this field blank.
dateLastModified	NO	Leave this field blank.
enabledUser	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.
userIds	NO	External machine-readable ID (e.g. LDAP ID, LTI ID) for this user. The ID must be accompanied by a type in the format {type:ID}. If multiple userIDs are needed, use double quotes, and separate the IDs with commas. Examples: {LDAP:Id} "{LDAP:Id},{LTI:Id},{Fed:Id}"
givenName	YES	User's first name.
familyName	YES	User's surname.
identifier	NO	Identifier for the user with a human-readable meaning.
grades	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. 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.
agentSourceIds	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.

Courses.csv

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	Leave this field blank.
dateLastModified	NO	Leave this field blank.
schoolYearSourceId	NO	School year in which course runs. This is the sourcedId of an academic Session (see below).
title	YES	Name of the course.
courseCode	NO	Human-readable course code.
grades	NO	Grade(s) for which the class is attended. If multiple grades are in the file for a class, only the first grade is used. 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	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.

Classes.csv

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	Leave this field blank.
dateLastModified	NO	Leave this field blank.
title	YES	Name of this class.
grades	NO	Grade(s) for which the class is attended. If multiple grades are in the file for a class, only the first grade is used. The permitted vocabulary is from CEDS (Version 5) for the "Entry Grade Level" element: https://ceds.ed.gov/CEDSElementDetails.aspx?TermId=7100
courseSourcedId	YES	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.
termSourcedIds	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	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	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"

Enrollments.csv

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	Leave this field blank.
dateLastModified	NO	Leave this field blank.
primary	NO	MUST only be set to true for ONE teacher for a class.
beginDate	NO	The start date for the enrollment. This date must align with the associated academic session (term) identified in the class.
endDate	NO	The end date for the enrollment (exclusive). This date must align with the associated academic session (term) identified for the class.

AcademicSessions.csv

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	Leave this field blank.
dateLastModified	NO	Leave this field blank.
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	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	In the row for the school year, this field must be blank. In the rows for all other academic sessions, this field must contain the school year's sourcedID.
metadata.orgSourcedId	NO	School sourcedId that this particular academicSession is under.

Demographics.csv

Column Header	Required	Notes
userSourcedId	YES	SourcedId of the user to which the demographics refer. Typically this will be a student.
status	NO	Leave this field.
dateLastModified	NO	Leave this field.
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

Manifest.csv

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	Enumerated as: bulk - this CSV file contains only bulk data (Delta is not supported.)
file.categories	Yes	Enumeration	Enumerated as: absent - this CSV file is not supplied
file.classes	Yes	Enumeration	Enumerated as: bulk - this CSV file contains only bulk data (Delta is not supported.)
file.classResources	Yes	Enumeration	Enumerated as: absent - this CSV file is not supplied
file.courses	Yes	Enumeration	Enumerated as: bulk - this CSV file contains only bulk data (Delta is not supported.)
file.courseResources	Yes	Enumeration	Enumerated as: absent - this CSV file is not supplied
file.demographics	Yes	Enumeration	Enumerated as: bulk - this CSV file contains only bulk data (Delta is not supported.)
file.enrollments	Yes	Enumeration	Enumerated as: bulk - this CSV file contains only bulk data (Delta is not supported.)
file.lineItems	Yes	Enumeration	Enumerated as: absent - this CSV file is not supplied
file.orgs	Yes	Enumeration	Enumerated as: bulk - this CSV file contains only bulk data (Delta is not supported.)
file.resources	Yes	Enumeration	Enumerated as: absent - this CSV file is not supplied
file.results	Yes	Enumeration	Enumerated as: absent - this CSV file is not supplied
file.users	Yes	Enumeration	Enumerated as: bulk - this CSV file contains only bulk data (Delta is not supported.)
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 eight 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.