About this data
The Roster import places students in classes. The roster file should reflect all student schedule records records for each student within a given academic year.
About this import
The roster.txt file is the process by which student schedule records are loaded into Illuminate. In Illuminate Data and Assessment (DnA) or Illuminate Special Education (ISE) this file is a key component of the regular data automation. For Illuminate Student Information (ISI) the roster.txt file is used to load historical roster data. For both DnA and ISI, it is the ONLY way that students are placed into classes. Without data in the roster.txt file, the students will not be “in” a class or with a teacher.
The unique key on a roster record is: Import Student ID, Section ID, Entry Date, and Academic Year. These five fields together are what constitute a unique roster record.
- Import Student ID
- Student Last Name
- Student First Name
- Birth Date
- Section ID*
- Site ID
- User ID*
- Entry Date
- Exit Date
- Grade Level ID*
- Academic Year
Import Student ID is the key identifier for this dataset. The Import Student ID should be a unique value for each student. It is not required that the value is the Student Information System (SIS) ID. It is required that for the entire installation the value is guaranteed to be unique. Traditionally, in a single district instance, the Import Student ID is the SIS generated student ID. In installations that span multiple districts, such as a consortium or a county, the Import Student ID is usually the State Student ID because this value is expected to be unique across multiple SIS.
Student Last Name, Student First Name, and Birth Date are actually “soft” requirements within this dataset. It is expected that every student should have these additional three basic data elements available in this file. In the roster.txt file, these fields are only used to assist in troubleshooting data. Ensuring that the data is available in the file allows for more efficient troubleshooting when reviewing import logs. This data is required to be present in the import file, however, the fields are not imported. These fields are updated only through the studemo.txt import.
Section ID* should reference the section ID from the mastschd.txt import. For more information on this field, read more about the master schedule data in the mastschd.txt import process document.
Site ID is the internal identifier of the site to which the student is enrolled and where the roster record exists. The site ID in this file must align to the site IDs that were originally provided in the sites.txt import file when the system was originally set up.
User ID* should reference the ID that is sent in the users.txt file. This information is frequently duplicated across the master schedule file and the roster file. This field identifies the teacher of record for this course
Entry Date identifies the date that the student was first actively scheduled into a section. It is important to note that in Illuminate, the entry date should represent the student's first day of activity in the section. If the first date that the student is in the class is 09-01-2016, the student’s Entry Date is expected to be 09-01-2016. Roster Entry dates cannot exist outside of term start and end dates. If the provided Entry Date pre-dates the session start date as identified in the term setup, the date will default to the term start date.
Grade Level ID* is used to identify a student's grade level. Currently, in the import processes, it is expected that the Grade Level ID aligns to Illuminate’s internal grade level ID sequencing. This is frequently confusing and not ideal, however it is how the imports currently work. This will be addressed in the future, however, for now it is important to know how the Grade Level IDs should be provided. See below in the “Common Issues” section of this document for more information.
Academic Year is currently required to identify the academic year to which the student data belongs. Generally, after historic data loads and for regular automation, the Academic Year field simply identifies the current academic year. The data, as stated in the spec, should be represented as a hyphenated two year range such as: 2016-2017.
* Section ID, User ID, and Grade Level ID are dependent requirements. If Section ID is not provided, then it is expected that User ID and Grade Level ID will be provided. If User ID and Grade Level ID is blank then Section ID cannot be. In the roster file either a Section ID is provided to refer back to a master schedule record (usually middle and high schools) or the student is simply in a grade level course with a teacher (usually elementary schools).
If any of the required fields are not provided or if any of the required fields do not align to the designated field types or values, the entire record will not import. Problems with required fields will generate import errors.
Whether or not a field is required refers to basic, minimal operation of the system. With only the required fields your Illuminate installation will work, however, it will not be configured optimally. Additionally, beyond minimal functionality and basic reporting, in an Illuminate Student Information (ISI) installation as much data as can possibly be provided should be imported. Many non-required fields are used in basic reports and compliance reporting.
Non-required but recommended fields
- State Student ID
- Course ID
- Session Type
State Student ID is the student’s unique identifier for state data reporting. It is used extensively as an alternate identifier for students. It is strongly recommended that this information is provided. In this import this ID is used solely for troubleshooting and student identifying information. It is not updated or imported from this file. It is only updated or importing via the studemo.txt import.
Course ID is provided in this file for reference only. The expectation here is that the roster record somewhat repeats some of that data that is in the mastschd.txt file. Having the section, user, site, and course is helpful for troubleshooting.
Session Type is used to differentiate normal sessions from summer sessions. If this field is left blank then the import process assumes that the data is for the normal session (Session Type ID = 1)
- Student Middle Name
Grade Level ID misalignment:
- This often occurs because traditional alphanumeric grades are provided to Illuminate. For example, in the incoming data file grade levels are provided as K, 1, 2, … 12. For import into Illuminate, the Grade Level ID must align to the specific codes provided in the data specification. If the Grade Level IDs are not provided in the correct format as required for import, student grade levels will be out of alignment. There are only two options to properly align student grade levels: provide the data as required according to the spec or introduce a transformation to the Grade Level ID field in the import configuration.
No Show roster records:
- By default, the only way that students are removed from a class is if they are properly exited from a class. In some instances, a roster record is provided with an entry date and then subsequently, the roster record is completely removed from the roster file and there is no exit date provided. The record is simply no longer sent for import. This happens because a student’s record may be deleted from the SIS or a student’s schedule was changed and the exit was not necessary in the SIS. In these instances, the students are never exited from the class in Illuminate since the Exit Date is not provided. The solution for this is to enable “no show” handling in Illuminate.