The SIS Integration
This guide outlines the required formats for importing data into Student Information Systems (SIS) using flat files.
General Requirements
- 🚨 Only upload the currently active term(s) data.
- If no active term exists an empty file (with headers included) may be uploaded. We will not process this file.
- Files must be in CSV format with UTF-8 encoding
- File names must match the file names provided below.
- First row must contain column headers matching the headers below.
- Required fields cannot be left blank
- Date time should follow MM/DD/YYYY format. Time is optional and will be by default, 12:00 AM local time (for start and release dates) and 11:59pm (for end dates) when not provided.
- For Passwords:
- Length must be at least 6 characters long.
- Please choose a password pattern that is easy for students and faculty to recognize.
- For Strings:
- Length varies, but as a lower bound, must be between 1 and 256 characters long. However length limits can vary by field, and are defined in the tables below.
- Must only contain characters supported here: Regex Guide
- Empty or null strings will be processed verbatim. For example:
- If a cell contains an empty string, it will not cause an error if field is required.
- If a cell is set to Null, it will cause an error if field is required.
SIS Behavior
- Based on the file, files uploaded are either processed as overrides or appends.
- Override uploads are destructive. Any entities that previously existed in the ClassRanked system that do not exist in the upload are removed. Some files are uploaded in override processing style because we want to maintain the most up to date snapshot of a specific dataset. The following SIS uploads are destructive and should be carefully planned as such:
- Course Sections
- Student Enrollments
- Instructor Assignments
- Conditions exist on these uploads to prevent the accidental deletion of any of these entities during critical times such as when surveys are live or published.
- Append uploads are additive only. Any entities that previously existed in the ClassRanked system that do not exist in the upload remain in the ClassRanked system. The following SIS uploads are appends:
- Student Users
- Faculty and Staff Users
- Courses
- This is likely because your institution is only sending a snapshot of the courses that exist in a given term or users that exist in a given term, as such we do not want to remove users, courses, in case they return in a later term.
File Types
View all the templates together: All SIS Templates
1. Student Records
File name: students.csv
Description: Contains basic student demographic and enrollment information.
Download here: students.csv
| Field Name | Required | Unique | Format (length) | Description |
|---|---|---|---|---|
| First Name | Yes | No | String (128) |
|
| Last Name | Yes | No | String (128) |
|
| Yes | Yes | String (1024) |
The student’s email. Used to enroll a student with their course section and as primary identifier for user during login. Example: andy.ju@classranked.edu |
|
| School ID | Yes | Yes | String (128) |
The unique identifier used by your institution to identify students. Used as a fallback identifier during login if email does not match a user in the system. Example: S012345 |
| Password | Yes | No | String (32) | Default password that the student will use to log in locally. |
| User Attributes ... | No | No | String (128) |
Any number of additional columns that represent attributes for the user. The column header represents the title of the attribute and the value in each specific row is a possible value of that attribute. Example: Grade Level (column title) → Sophomore (cell) |
2. Faculty and Staff Records
File name: faculty-and-staff.csv
Description: Contains basic faculty and staff demographic and enrollment information.
Download here: faculty-and-staff.csv
| Field Name | Required | Unique | Format (length) | Description |
|---|---|---|---|---|
| First Name | Yes | No | String (128) |
|
| Last Name | Yes | No | String (128) |
|
| Yes | Yes | String (1024) |
The user’s email. Used to link an instructor with their course sections and admins with their academic units, and to identify users during login. Example: melissa.helvey@classranked.edu |
|
| School ID | Yes | Yes | String (128) |
The unique identifier used by your institution to identify users. Used as a fallback during login if email doesn't match a system user. Example: S000001 |
| Password | Yes | No | String (32) | The default password that the user will use to log in locally. |
| User Attributes ... | No | No | String (128) |
Any number of additional columns that represent attributes for the user. The column header represents the title of the attribute and the value in each specific row is a possible value of that attribute. Example: Gender (column title) → Male (cell) |
3. Course Records
File name: courses.csv
Description: Contains course catalog information.
Download here: courses.csv
| Field Name | Required | Unique | Format (length) | Description |
|---|---|---|---|---|
| Title | Yes | No | String (256) |
The full title of the course. Example: Special Topics in Computer Science |
| Abbreviation | Yes | Yes | String (128) |
The shorthand identifier used to reference the course. Must be unique. Often contains department and some sort of course number. Commonly referred to as Example: COMPSCI 297 |
| Parent Academic Unit | Yes | No | String (128) |
The abbreviation of the academic unit that owns this course. Academic units are defined in the Reporting Hierarchy (not part of the SIS flat file exchange). Often, the department. Example: COMPSCI |
| Course Attributes… | No | No | String (128) |
Any number of additional columns that represent attributes for the course. The column header represents the title of the attribute and the value in each specific row is a possible value of that attribute. All attributes assigned to a Course are inherited by its sections. Examples:
|
4. Term Records
File name: terms.csv
Description: Contains term details.
Download here: terms.csv
| Field Name | Required | Unique | Format (length) | Description |
|---|---|---|---|---|
| Title | Yes | Yes | String (256) |
The user-friendly title of the term. The title provided here is used to link Course Sections to specific terms and is used around the ClassRanked platform to show terms. Example: Fall 2024 |
| Start Date | Yes | No | Date time |
The start date of the term. All course sections and subterms must fall between the start and end dates. Example: 09/25/2025 00:00 09-25-2025 |
| End Date | Yes | No | Date time |
The end date of the term. All course sections and subterms must fall between the start and end dates. Example: 12/13/2025 23:59 12-13-2025 |
5. Course Section Records
File name: course-sections.csv
Description: Contains course section information.
Download here: course-sections.csv
| Field Name | Required | Unique | Format (length) | Description |
|---|---|---|---|---|
| Title | No | No | String (256) |
The full title of the Course Section. Can be the same or different from the Course title. Example: Special Topics in Computer Science: Prompt Engineering |
| Course ID | Yes | No | String (128) |
The ID of the course this section is an instance of. This should be the same value as Abbreviation of the corresponding course. Example: COMPSCI 297 |
| Section ID | Yes | Yes (For the associated term) | String (128) |
The ID of the specific section, must be unique for each term. Example: COMPSCI 297-001 |
| Start Date | Yes | No | Date time |
The start date of the course section. Example: 09/25/2025 08:00 |
| End Date | Yes | No | Date time |
The end date of the course section. Example: 12/13/2025 23:59 |
| Term | Yes | No | String (256) |
The title of the term that this section is part of. Example: Fall 2024 |
| Cross-List Code | No | No | String (32) |
The cross-list group identifier used to link cross-listed courses together. Example: KG |
| Is Primary Course | No | No | String (8) |
Indicates that this course is the primary course in this cross-listing group. Empty cell means this is not the primary course. Example: x |
| Course Attributes… | No | No | String (128) |
Any number of additional columns that represent existing* attributes for the course section. The column header represents the title of the attribute and the value in each specific row is a possible value of that attribute. Example:
|
6. Student Enrollment Records
File name: student-enrollments.csv
Description: Links students to their enrolled courses.
Download here: student-enrollments.csv
| Field Name | Required | Unique | Format (length) | Description |
|---|---|---|---|---|
| Academic Unit | Yes | No | String (128) |
The Referred to as Section ID in Course Sections Record. Example: COMPSCI 297-001 |
| Term | Yes | No | String (256) |
The term in which this student was enrolled in this section Example: Fall 2024 |
| Yes | No | String (1024) |
The email of the student who was enrolled. Example: andy.ju@classranked.edu |
7. Instructor Course Section Assignment Records
File name: instructor-assignments.csv
Description: Links instructors to the course sections they teach.
Download here: instructor-assignments.csv
| Field Name | Required | Unique | Format (length) | Description |
|---|---|---|---|---|
| Academic Unit | Yes | No | String (128) |
The Referred to as Section ID in Course Sections Record. Example: COMPSCI 297-001 |
| Term | Yes | No | String (256) |
The term in which the instructor was teaching in this term. Example: Fall 2024 |
| Yes | No | String (1024) |
The email of the instructor who taught the course section. Example: melissa.helvey@classranked.edu |
|
| Role | No | No | String (128) |
Available roles:
|