CSV Courses Integration
- Adi A
Ready Education integrates with CSV files to bring personalized Courses Integrations into the mobile app.
Table of Contents
Integration Flow
Client Requirements:
Downloads course information and student enrollment information into two CSV files:
course-info.csv
student-info.csv
Transfers the two files to Ready Education's servers using SSH File Transfer Protocol Server (SFTP).
The CSV data is downloaded from your SIS - Student Information System e.g. Banner, PeopleSoft, Campus Management, etc.
Ready Education Configuration Requirements:
Provides access to the SFTP Server
Checks CSV files for accuracy and required fields
Configures the CSV files for Courses Integrations
Tests Integrations
Configures for Production
Ready Education Production Integrations:
After configuration for Production, the Ready Education system automatically checks and ingests new files every 4 hrs.
Course Integrations and updates appear immediately to users of the mobile app after ingestion.
Downloading the CSV files
Ready Education requires two CSV files to be downloaded from your system's SIS per our requirements.
Naming Convention
The CSV files must follow a specific naming convention. The name for the CSV file used in Integrations will be:
<school_code>_<file_type>.csvAn example of a student-info file and course-info file name are:
mcgill_student-info.csv
mcgill_course-info.csv
The fields are as follows:
<school_code> is a string used to denote your institution - typically an abbreviation of the institution name e.g. mcgill
<file_type> is "course-info" for the course data and "student-info" for the student data.
The fields in the file name are separated by underscores ("_").
File Content, Text Delimiters, and Qualifiers
The CSV files must follow the below specifications to run successfully. Please ensure your files meet the below requirements before sending them through the SFTP server:
Requirements:
Each file should contain all the data (not a delta from the previous file)
Include headers and use the data field's label as the header name
(eg. "student_unique_id"|"course_unique_id"|"name"|"gender")
Text fields are separated by a pipe character | or comma ,
The contents of any text field is enclosed within double quotes (""). We do not accept single quotes. Text using double quotes can be escaped with a backspace (e.g. "The \"New\" Normal: Post-pandemic")
Other considerations:
Booleans Supported: 1/0
If omitting data, include the column but use an empty string as the value ("").
We handle return carriages ie. line breaks; do not escape them using '\n'
student-info.csv and course-info.csv
For courses integrations, we require two CSV files:
Course Info
Student Info
The course-info.csv provides the list of courses offered at your institution. We recommend sending courses that span across the current semester, previous semester and next semester for the best experience. The student-info.csv associates students to the courses they are enrolled in.
course-info.csv
We require the CSV files to include the below required information for courses. Please see the description for the expected format of the required fields.
Title | Required | Description | Example |
|---|---|---|---|
course_unique_id | Yes | Unique identifier that identifies the course, section, and term. Used for mapping the course object in your institution's database to course information in your Learning Management System and to the Ready Education's database. The course_unique_id is referenced in the student-info.csv to link students to their enrollments, and in the mapping to LMS (if applicable). This value is never shown to the users on the app. | "Mech101-01-Fall2019" |
course_name | Yes | The full name of the course (not the course code). | "Biology 101" |
course_code | Yes | Short code used to uniquely identify the course within the institution. | "BIO 101"
|
section_code | Yes | A string or number used to differentiate students taking the same course taught different by professors or taught at different times. The course code and course section code typically uniquely identify the course a student is taking. | "01-A" |
semester_name | Yes | A string representing the name of the semester. Courses with the same semester name will be grouped together in student's schedules. | "Fall 2025" |
external_term_id | Yes | Unique identifier for the term object. Not displayed to users. | "Fa2025" or "202570" |
external_campus_id | Yes | Unique identifier for the campus. Not displayed to users. | "MC1" |
external_merge_id | Yes | Unique identifier used to map a single LMS course's data to various courses. | "X-Mech101-Fall2025" |
active_from | Yes | A Datetime string in the form YYYY-MM-DD of when the course starts. Also accepted: A UNIX timestamp. | "2025-08-15" |
active_until | Yes | A Datetime string in the form YYYY-MM-DD of when the course ends. Also accepted: A UNIX timestamp. | "2025-12-20" |
days_of_the_week | Yes | A string representing the days of the week on which the course takes place.
| "M,W,F" or "MFW", or "" for courses without a schedule. |
start_time | Yes | The time at which the course starts, in hours and minutes expressed as HHMM (0730, 1530). Also accepted: in seconds after midnight. Leave blank for online course with no start and end time. | "0900" |
end_time | Yes | The time at which the course ends, in hours and minutes expressed as HHMM (0730, 1530). Also accepted: in seconds after midnight. Leave blank for online course with no start and end time. | "1100" |
instructor_name | Yes | A string representing the instructor's full name. If more than one instructor exists, include both names, separated by a comma. | "Paul Markowicz" |
location | Yes | The location (building name and room number). If an Online course, use "Online" or "Web". | "Thomas Great Hall 325" |
course_description | Optional | A longer-form course description. | "Introduction to Biology is a study of the mechanisms ..." |
latitude | Optional | The longitude value of the location where the course is taught. Displays the map location in conjunction with longitude. | "40.026498" |
longitude | Optional | The latitude value of the location where the course is taught. Displays the map location in conjunction with latitude. | "-75.315285" |
User friendly, readable text in the fields are recommended. Every text field sent will display to students with the exception of external_term_id and external_campus_id. For example, Course Code = Bio 101 is a better understood by students as the short name for a course. A Course Code such as BIO3521 where 3521 is a Course Reference Number (CRN) is accurate, but not intuitive to students, and therefore is not recommended.
For Courses having Multiple Sections:
Add multiple lines to the CSV tile, one line per section per course.
For example, we have "Intro to Accounting" with three sections: A, B, and C. Sections A and B are offered at the same time Mondays and Wednesdays at 10:00am and on Fridays at 2:00pm but with different instructors. Section C offered once per week on Thursday at 6:00pm.
The most efficient format for the course-info.csv file would be a total of five (5) records:
one record for section A for the Monday / Wednesday class with "MW" as day of the week (combine into one record since the start time and end time are the same).
one record for section B for the Monday / Wednesday class with "MW" as day of the week (combine into one record since the start time and end time are the same).
one record for section A for Friday class with "F" as day of the week.
one record for section B for Friday class with "F" as day of the week.
one record for section C for Thursday class with "H" as day of the week
Intro to Accounting Example
student-info.csv
We require the CSV files to include the below required information for student info. Please see the description for the expected format of the required fields.
Title | Required | Description | Example |
|---|---|---|---|
student_unique_id | yes | A unique string (or number) that identifies the student. | “A1234456" |
course_unique_id | yes | Unique string (or number) that identifies a course associated with this student. This Identifier is used for mapping the course objects in the course-info.csv to the user object in the student-info.csv. | "Mech101-01-Fall2025" |
yes | Primary email on file for the student, in form of string. Used for mapping the student to the LDAP or SingleSignOn system (e.g. CAS or SAML). | “paula@email.com”
| |
grade | no | Applicable for each course in which the student is enrolled e.g. mid-term grade or final grade. Open text field, we support numeric or letter grades. | "B+" |
Associating One Student with Multiple Courses
To associate a student with multiple courses (e.g., a student taking four courses), add a line for each course enrollment in the student-info.csv. For example, a student Stephan Law is taking four courses:
Intro to Accounting
Intro to Spanish
Intro to Chemistry
Intro to Business Fundamentals
The student-info.csv file will contain 4 records:
Key Point in Mapping Integrations
CSV integrations involve multiple key mappings for a successful end-to-end integration. The integration spans systems from your authentication to the CSV files to the LMS - Learning Management System. Review these key details and reach out to your Technical Project Manager if you have questions.
Mapping from Authentication to CSV:
The email released in the student-info.csv must match the email released in your school's SSO (SAML, CAS, D2L, et.c) or LDAP log-in flow. Please confirm with your Technical Project Manager and with your LDAP or SSO admin to confirm the correct email to release.
Mapping between CSV files:
The course_unique_id field is released in both the student-info.csv and the course-info.csv files. This field must match character for character in both files.
Mapping from CSV to LMS:
If you have opted for the package that connects your CSV integrations to your Learning Management System (LMS) e.g. Canvas, Blackboard, D2L, etc., ensure this additional step is met:
The course_unique_id field must be mappable to your LMS. Please check with your LMS admin before configuring this field to be released.
Example of mapping between Banner and Blackboard:
For one of our clients, the blackboard integration releases a path (e.g. course unique identifying information) through their API as 11822.202010 . The identifying information is a combination of:
CRN (course reference number) = 11822
Term Code = 202010 (e.g. Spring 2020)
Sample Data from Blackboard response:
{
"HasAssignments": "true",
"CourseDescription": "202010",
"CourseName": "202010 - ORAL COMMUNICATION",
"Path": "11822.202010",
"SectionId": "11822.202010",
"Instructors": [
{
"Id": "12345",
"UserName": "jane@readyeducation.edu",
"Name": "Jane Smith"
}
],
"SectionMeetings": [
],
"SectionTerm": "Spring 2020",
"SectionTermDescription": "Spring 2020"
}In order for Ready Education to connect the CSV course information to the LMS, the CSV file will need to release a course_unique_id that is mappable to the path. Here's an example:
course_unique_id = 11822-010-2020 Spring
This example is acceptable because:
CRN : 11822 is in both Blackboard and the CSV course_unique_id
Term Code : 202010 maps to 2020 Spring via a chart provided by the client:
10 = Spring
20 = Summer
30 = Fall
Questions? Consult the FAQ or reach out to your Technical Project Manager.
Accessing and Sending Files to the SFTP Server
The CSV files are transferred to Ready Education using SSH File Transfer Protocol Server (SFTP).
To access the SFTP server and transfer data, your technical project manager will provide you with:
the hostname of the SFTP server
a designated folder to deliver the file
a username and password to gain access (option for SSH private/public key access)
Timing of imports from the SFTP server
We recommend setting up an automated nightly file transfer. Our system regularly checks for new CSV files and typically completes processing within 6 hrs of new files being transferred.
Minimum - At least once every 24 hrs.
Recommended - Up to four times a day for the best student experience. An example of when up to four times a day is beneficial is during add/drop periods where student enrollment changes frequently.
Initial Set-up and Testing
Done reviewing the Documentation? Here are the next steps on set-up and testing!
Client Verification: Complete the checklist* to ensure your files are ready for integration!
Send the files: Download and Transfer the student-info.csv and course-info.csv files to the Ready SFTP server.
Ready Verification: Notify your Technical Project Manager. Your project manager will verify the CSV files and notify you if any edits are required.
Configuration: Once the files pass verification, they will be configured in our system.
Testing: Test and approve the Course Integrations.
*CSV Quick Checklist
The files:
Match the naming convention (e.g. readyed_student-info.csv and readyed_course-info.csv)
Include headers (eg. "student_unique_id"|"course_unique_id"|"name"|"gender")
Text fields are separated by a pipe character | or comma ,
The contents of every field is enclosed within double quotes ("")
Consider the mapping between Authentication and CSV
If applicable, consider the mapping between CSV and LMS
All checked off? You're ready to send the files to Ready's SFTP servers.
Column Ordering:
Subsequent file transfers do not need to be re-configured in our system if the column ordering remains the same.
If you change the order of the columns, or add columns, notify your Technical Project Manager.
FAQs