Requirements for OneRoster Standard Imports

Contact Technical Support for help preparing and importing your data; call 1-800-338-4204 or select Live Chat at the top of the Home page.

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.

Note that you must use existing Renaissance program schools and school IDs; you cannot enter new schools with this import type. The school names and IDs in the import templates must match the IDs in the software.

  1. On the Home page, select your name in the upper-right corner. In the drop-down list, select Manage Apps & Users.
  2. Select Districts & Schools.
  3. On the Schools tab, you will see the name and ID for each school. If not already there, you can copy and paste them into your import files.

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

Who can do this with default user permissions?

District Level Administrators, School Level Administrators

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

  6. 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.
  7. Open all of the templates just downloaded from Renaissance.
  8. 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 import to fail. 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 all the column headers from Multi-School Files 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.
  9. In your external rostering tool (such as OneRoster or some other SIS system), create export files and open the file(s) to edit them.
  10. OneRoster 1.0 or 1.1 standard files can be imported.
  11. 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
    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.
    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_cu

    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.
  12. Save all the files. If you prefer to combine your files into a .zip file, name the file Roster.zip.
  13. 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).

  14. Select Import.
  15. 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.