Integration

Ready Education Integration Documentation

Welcome to the Integration developer hub. You'll find comprehensive guides and documentation to help you start working with Integration as quickly as possible, as well as support if you get stuck. Let's jump right in!

Guides    
Suggest Edits

Getting Started

Documentation for working with the Ready Education Data Integration Node

 

The academic institution software landscape is cluttered with specialized software systems, each handling a specific set of user functions -- enrolment, payments, class work and careers. Providing a seamless experience to students is often a challenge since so much of the data resides in different databases.

Through integration, the Ready Education platform can provide a seamless experience for students to access important information, while leaving specialized functionality to the software that has already implemented it.

The Ready Education implementation team is focused on making it easy and painless to share data that can be shown to students on the mobile app. Our top priority is student data privacy and security. We work with our partners to outline how data will be used, how it will be consumed and how it will be disposed of.

The Ready Education Data Integration Node is a flexible software stack built and supported in-house. It is comprised mainly of APIs (consuming and providing) and flat file transfer processes. No two institutions are the same, so our node is built with flexibility at the core.

This document will guide you through the required steps to get the node set up for your institution.

Your Integration Contact is ready to help you.

As a customer of Ready Education, you have been assigned an Implementation Manager. This person has been tasked with making sure your institutional data is able to be imported successfully and securely. If you have any questions about any of the information contained in this document, please do not hesitate to reach out to your Implementation Manager.

Suggest Edits

General Information

Information regarding file structure, contents and format.

 

CSV file naming convention

The name for the CSV file used in Integrations will be:

<school code>_<file type>.csv

The fields are as follows:

  • <school code> is an arbitrary code to quickly denote the institution - typically an abbreviation of the institution name, you can choose your own as long as it is unique (will be verified with your Implementation Manager)
  • <file type> is “course-info” for the course data and “student-info” for the student data.

Note that the fields in the file name are separated by underscores ("_").

An example of a file name is:
McGill_student-info.csv

Timing of imports from the SFTP server

The CSV file containing your student information is transferred to Ready Education using SSH File Transfer Protocol Server (SFTP).

To access the server and transfer data, your integration contact will provide you with:

  • the URL or address of the SFTP server
  • a username and password to gain access.

The node regularly updates stored data throughout the day, therefore files can be transferred at any frequency. The required minimum is one update per 24-hour period, to keep the data minimally up to date for students.

Booleans Supported

You can use the following Boolean values when transferring data throughout the Ready Education integration system:

  • 1 / 0
  • True / False
  • Yes / No
  • Oui / Non

Text Delimiters and Qualifiers

The data file used in an integration with the node should follow a specific format but can be modified to make integrations easier. Speak with your integration contact to request support for format differences.

1) Text fields must be separated by a pipe character ("|").
2) The contents of any text field should be enclosed within double quotes.
3) Double quotes should be escaped using a backspace (\")
4) ODIN will handle return carriages ie. line breaks, do not escape them using '\n'

Here is an example of three fields together on one row of a sample data file:

"Robert's Apples"|"Oranges and Lemons"|"Grapefruit"
"Bananas, a string with \"double quotes\" in it"|"More Fruit!"|"Field with a 
line break in it"|"More Fruit"

File Content

Each file should contain (student and course data) should contain all the data (not a delta from the previous file). The data should span across the current semester, previous semester and next semester. The node will automatically ensure the data in the Ready Education DB is consistent with what is in the latest file.

If you are omitting certain data, include the column but use an empty string as the value ("").

You should include file headers and use the data field's label as the header name (eg. "student_unique_id"|"course_unique_id"|"name"|"gender")

Return carriages should be escaped as to not affect the parsing of the file. You can replace the return carriage with '\n'

Suggest Edits

Student Data Integration

This page describes the data file format used to exchange student information between your institution and the Ready Education Data Integration Node. The following fields are suggestions only, you are welcome to add your own custom fields.

 
post
curl --request POST \
  --url http://example.com/
var request = require("request");

var options = { method: 'POST', url: 'http://example.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("http://example.com/")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://example.com/");

xhr.send(data);
import requests

url = "http://example.com/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

student_unique_id
string
required

A unique string (or number) that identifies the student. Will be used for mapping the user object on the institution data store to the user object on Ready Education.

course_unique_id
string
required

Unique string (or number) that identifies a course associated with this student. This Identifier is also used for mapping course objects between the Institution and Ready Education. This should match the unique identifier used in the Course Data CSV file.

name
string
required

Full name of the student. Format: Given Name Surname

email
string
required

Primary email on file for the student, in form of string.

gender
string

One character abbreviation of the gender of the student.
M [Male], F [Female], T [Trans], I [Intersex/Gender non-conforming], O [Other], N [None of above],

year_of_graduation
string

String representing the estimated year of student graduation.

academic_status
string

One character representation student's degree type.
U [Undergraduate], G [Graudate], P [Post-graduate], O [Staff], C [continuing education/certificate/diploma]

secondary_email
string

Secondary email on file for this student, in form of string.

grade
string

Applicable for each course in which the student is enrolled. Open text field, we support numeric or letter grades

 

Associating One Student with Multiple Courses

To associate a student with multiple courses (e.g., a student taking two courses), add multiple lines to the Student Data Integration CSV tile.
Each row will have identical content, except for the “course unique identifier” field.

The Ready Education integrations platform also supports a number of extra data fields, which can be customized according to your institution's needs and the data you gather on your students. A list of Academic and Non-Academic fields are found below. Certain platform features have dependencies on the data provided, ask your integration contact for more information.

Suggest Edits

Student Data (Cont'd) - Academic

 
post
curl --request POST \
  --url http://example.com/
var request = require("request");

var options = { method: 'POST', url: 'http://example.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("http://example.com/")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://example.com/");

xhr.send(data);
import requests

url = "http://example.com/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

cell_phone
string

String representing the user's cell phone number. Example format: XXX-XXX-XXXX

first_generation
boolean

Is the student the first in their family (not including a brother or sister) to attend a post-secondary institution?

ethnicity
string

One-character string representing the student's ethnicity.
W [White], B [Black], A [Asian], N [American Indian or Alaskan Native], H [Hispanic], P [Pacific Islander]

length_of_program
int32

How many years will the user be working towards a degree/certification at the academic institution?

program_information
string

Text description of the students program of study.

college
string

Name of institution that will award the student's degree / certification (if different from the institution).

gpa
string

A field to hold the student's numerical GPA.

program_status
string

A string indicating: PT [Part-time], FT [Full-time]

honours
boolean

Is the student enrolled in an Honours program?

 
Suggest Edits

Student Data (Cont'd) -- Non-academic

 
post
curl --request POST \
  --url http://example.com/
var request = require("request");

var options = { method: 'POST', url: 'http://example.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("http://example.com/")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://example.com/");

xhr.send(data);
import requests

url = "http://example.com/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

living_in_residence
boolean

Is the student living in residence on campus?

athlete
boolean

Is the student involved in competitive sports on behalf of the Institution?

international_student
boolean

Is the student's country of residence different from the country where the institution is located?

veteran
boolean

Has the student served in the active military, naval, or air service?

distance_learning
boolean

Is the student enrolled in courses where technologically-mediated solutions replace face-to-face interaction?

scholarship
boolean

Is the student the recipient of one or more scholarships?

adult_non_traditional
boolean

Is the student an adult, or otherwise a non-traditional student?

 

A Single File for All Student Data

You should include all data fields in a single file. If you are sharing 15 different data fields for each students, then the "Student Data" file should have 15 columns.

Suggest Edits

Course Data Integration

 
post
curl --request POST \
  --url http://example.com/
var request = require("request");

var options = { method: 'POST', url: 'http://example.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("http://example.com/")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://example.com/");

xhr.send(data);
import requests

url = "http://example.com/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

course_unique_id
string
required

Unique string (or number) that identifies the course. Used for mapping the course object in your institution's database to course information in Ready Education's database. This is the unique ID referenced in the Student Data CSV linking students to their enrolments.

course_name
string
required

The full name of the course (not the course code)

course_description
string
required

A longer-form course description.

course_code
string
required

Short code used to uniquely identify the course within the institution.

grade_mode
string

The type of grading scheme. Supported options: "Standard Grading", "Satisfactory/Unsatisfactory"

credit_num
int32

The number of credits for completing the given course.

campus
string

Name of the campus where the course is offered (if your institution has multiple campuses).

external_campus_id
string

Unique identifier for the campus.

section_code
string
required

A string or number used to differentiate students taking the same course taught different by professors or at different times. The course code and course section code typically uniquely identify the course a student is taking.

active_from
int32
required

A UNIX timestamp of when the course starts.
To translate dates into UNIX timestamps, please see epochconverter.com. Also accepted: Datetime string in the form YYYY-MM-DD.

active_until
int32
required

A UNIX timestamp of when the course ends.
To translate dates into UNIX timestamps, please see epochconverter.com. Also accepted: Datetime string in the form YYYY-MM-DD.

location
string

The location (building name and room number).

start_time
int32
required

The time at which the course begins, in seconds, measured from midnight (00:00:00). Also accepted: the hour and minute expressed as HHMM (0730, 1530). Leave blank for online courses.

end_time
int32
required

The time at which the course ends, in seconds, measured from 00:00:00. Also accepted: the hour and minute expressed as HHMM (0730, 1530). Leave blank for online courses.

section_type
string

A string indicating the instruction format. EG, Lecture, Lab, etc. <br/>Options: Lecture, Laboratory, Project, Seminar, Tutorial, Practicum

latitude
float

The lattitude value of the location where the course is taught.

longitude
float

The longitude value of the location where the course is taught.

course_time_code
string
required

A string representing the name of the semester. Courses with the same "course time code" will be grouped together in student's schedules.

external_term_id
string

Unique identifier for the term object

section_size
int32

Max number of students who can attend this section.

days_of_the_week
string
required

A [comma separated] string representing the days of the week on which the course takes place.
M [Monday], T [Tuesday], W [Wednesday], H [Thursday], F [Friday], S [Saturday], U [Sunday]

instructor_name
string

A string representing the instructor's full name.
If more than one instructor exists, include both names, separated by a comma.

 

For Courses having Multiple Sections:

Add multiple lines to the CSV tile, one line per section per course.

For example, a course called "Intro to Accounting" (ACCT 101), with two sections (sections A and B) offered at the same time (Mondays and Wednesdays at 10:00am and on Fridays at 2:00pm) and a third section (section C) offered at night once per week (Thursdays at 6:00pm).

This calls for:

  • one record for section A for the Monday / Wednesday class with "MW" as day of the week (can be put together since they have the same start and end time)

  • one record for section B for the Monday / Wednesday class with "MW" as day of the week (can be put together since they have the same start and end time)

  • 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 Fridays class with "F" as day of the week.

That is, ACCT 101 calls for a total of five (5) records in this example.

An example structure with some fields omitted.

Course Unique Identifier
Course Name
Course Code
Section Code
Start Time
End Time
Days of the Week

ACCT101-A

Intro to Accounting

ACCT101

A

36000

41400

MW

ACCT101-B

Intro to Accounting

ACCT101

B

36000

41400

MW

ACCT101-A

Intro to Accounting

ACCT101

A

50400

55800

F

ACCT101-B

Intro to Accounting

ACCT101

B

50400

55800

F

ACCT101-C

Intro to Accounting

ACCT101

C

64800

79200

H