1. The Historical Import Format
This guide explains how institutions should format historical survey response data for import into ClassRanked. The required structure matches ClassRanked’s own export format to ensure perfect compatibility.
ClassRanked exports data in a wide format (one row per response, one column per survey item).
Institutions must provide historical data in the same wide format.
ClassRanked will automatically transform the file into its internal long format during import.
1. File Format Requirements
- File type: CSV (.csv)
- Encoding: UTF-8
- First row must contain column headers
- No formulas or merged cells
- Field-length limits apply (see section 5)
Each row represents one anonymous respondent completing a survey for a specific course section.
2. Required Metadata Columns
These fields must be present for every record. They allow ClassRanked to map each response to the correct term, course, section, and instructor.
| Column Name | Description | Max Length (char) |
|---|---|---|
| Survey Title | Name of the survey project these responses belong to. | 256 |
| Response ID | Unique ID for the response row (necessary for dedupe & traceability). | 128 |
| School Code* | School identifier (for multi-college institutions). | 128 |
| Department Code* | Department identifier. | 128 |
| Course ID* | Course identifier used by the institution. | 128 |
| Section ID* | Unique identifier for the course section. | 128 |
| Course Title* | Human-readable course title. | 256 |
| Term Title* | Academic term name (e.g., “2025 Fall”). | 256 |
| Term Start Date* | First day of the academic term. | — |
| Term End Date* | Last day of the academic term. | — |
| Instructor Email | Email for the instructor being evaluated. | 256 |
| Instructor ID | Instructor’s institutional ID. | 128 |
| Instructor First Name | Instructor first name. | 128 |
| Instructor Last Name | Instructor last name. | 128 |
| One column per survey item | Each survey item’s response. | 2048 |
💡A note on survey item formatting
ClassRanked can work with your existing survey system’s column headers and survey item export formatting.
We can parse out:
- the section a survey item belongs to
- the ordering of survey items
- the survey item text
- the distinction between multi-items sharing a section
However, for the cleanest and most consistent import experience — especially when mapping historical survey templates — we recommend using the following pattern for each survey item column header:
Sec#_Section Title_Q#_Survey Item Text
Example:
Sec2_Instructor Effectiveness_Q4_The instructor graded my work promptly.
Sec3_Course Design_Q2_The course syllabus clearly described the requirements.
Sec1_Instructor Selection_Q1_Select your instructor.
Why this format is recommended:
- Makes the section hierarchy explicit
- Preserves survey item order
- Keeps the column name human-readable
- Makes mapping legacy → modern templates substantially easier
- Simplifies repeat imports across multiple terms
- Ensures clean parsing even when wording changes slightly
If a school cannot follow this naming pattern, ClassRanked can still process their survey items — this format is simply preferred.
3. Optional Metadata Columns
If present, these fields will be imported and used for reporting filters, attributes, and term/section logic.
| Column Name | Description | Max Length (char) |
|---|---|---|
| Start Date | Course section start date (overrides Term Start if present). | — |
| End Date | Course section end date (overrides Term End if present). | — |
| Submitted At | Timestamp of response submission (ISO or date). | — |
| Is Test Response | TRUE/FALSE flag to mark whether this row should be excluded from reporting. | — |
Attributes
More dynamic reporting by attributes may have been one of the reasons your institution switched to ClassRanked. We provide convenient importing standards for bringing in course, instructor, and student attributes along with their submissions.
To ensure ClassRanked can reliably parse attribute columns, each type of attribute must include a prefix in the column header:
| Column Name Prefix | Description | Max Length |
|---|---|---|
| CourseAttr_ | Course-level metadata (e.g., Modality, Program, Session). | 128 |
| InstructorAttr_ | Instructor metadata (e.g., Rank, Tenure Status, FT/PT). | 128 |
| RespondentAttr_ | Anonymous respondent characteristics (Level, Campus). | 128 |
| SubjectAttr_ | Subject/discipline-level attributes. | 128 |
4. Survey Response Columns (Survey Items)
Each survey item should appear in its own column exactly as in ClassRanked’s exported format.
Cell contents may include:
- Numeric responses: 5, 4, 3
- Labeled responses: Strongly Agree (5)
- Text responses: "The instructor was very clear"
- Multiple-choice labels
- “N/A” where applicable
Max length for any response: 2048 characters
5. Field-Length Constraints
ClassRanked enforces the following character limits:
| Field Type | Max Length (char) |
|---|---|
| Titles (Survey Title, Course Title) | 256 |
| Descriptions (Emails, Survey Templates) | 1024 |
| Abbreviations, Section IDs, Identifiers | 128 |
| First Name | 128 |
| Last Name | 128 |
| Survey Response Text | 2048 |
6. Example Row (Wide Format)
You can view a Sample Import File here.
7. How ClassRanked Processes the File
ClassRanked:
- Validates the file structure
- Extracts section, term, instructor, and attribute metadata
- Converts wide-format survey items → long-format rows
- Maps survey items to the active survey template using your Crosswalk
- Computes numeric values and weights
- Stores responses in the internal reporting engine
Respondents remain anonymous throughout the process.