Audiences Plus - Integration Guide
- Adi A
Ready Education integrates with CSV files to bring notifications based on targeted groups into the mobile app. To learn more about Dynamic Audiences, check out our Support Helpdesk:
Have you already integrated with CSV Courses? If yes, skip to the section: Customizable Fields
Table of Contents
Integration Flow
Client Requirements:
Downloads student population information into a CSV: student-info.csv
Transfers the CSV file 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. We can support any SIS system.
Ready Education Configuration Requirements:
Provides access to the SFTP Server
Checks CSV files for accuracy and required fields 3. Configures the CSV files for Dynamic Audiences Integrations
Downloading the CSV files
Ready Education requires the Student Info CSV file to be downloaded from your system's Student Information System e.g. SIS per our requirements. Examples of SIS include Banner, PeopleSoft, Campus Management, Jenzabar, Colleague, etc.
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 an 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")
student-info.csv
Extending CSV Courses Integrations to Dynamic Audiences: Already integrated to our SFTP Server through the CSV Courses Integration? If yes, scroll down to the section Customizable Fields.
Required Fields
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 | It is called "course_unique_id" however you may use any identifier that will be a unique value for identifying each record in the csv file. | "19437233" |
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” |
Customizable Fields
The Dynamic Audience feature gives you full control over the fields you want to target. We recommend working with your Campus Cloud Administrator (end user of the Dynamic Audience feature) to discuss the best fields for your school.
Custom fields requirements:
Maximum of 100 customizable fields. A field is a grouping such as "Program of Study", "Ethnicity", "Dietary Restriction", etc.
Maximum of 500 options per field. Each field, such as Program of Study has a maximum of 500 options.
Data is in a "grouping" instead of individual attributes. For example, GPA needs be provided as groups of "1.0 - 1.5", "1.5 - 2.0", ... , "3.0 - 3.5" and "3.5 - 4.0". We don't accept individual GPAs such as "3.3334", "3.991", "2.832", etc.
Custom fields recommendations:
User Friendly Names. Recommended for the Title to be user friendly and readable. The Title will display to administrators creating the Dynamic Audiences in Campus Cloud (our administrative portal).
Name missing data. Recommended to handle fields with no data. For example, if a student has no dietary restrictions consider sending the field over as "No Dietary Restrictions" instead of blank e.g. "" or with a dash "-". Every field displays to administrators and a blank or dash is less informative, and may cause confusion.
The below are suggested fields for your Dynamic Audiences integration.
Academic
Title | Sample Response |
|---|---|
program_status | Full-Time, Part-Time |
term_of_admission | Fall 2020, Spring 2021, Fall 2021 |
academic_career | Undergraduate, Graduate, Post-graduate, Staff, Continuing Education, etc. |
academic_status | Freshman, Sophomore, Junior, Senior |
major | Biology, Mathematics, Sociology |
minor | Spanish, English, Physics |
honors | Yes, No |
Student Success
Title | Sample Response |
|---|---|
retention_status | Dropped out, Transferred, Continued |
early_alerts | Yes, No |
at_risk_student | First-generation, Pell Grant Recipient |
academic_advisor | Susan Smith |
peer_mentor | John Coates |
faculty_mentor | Nathan Daniels |
gpa_range | 1.0 - 1.5, 1.5 - 2.0, ... , 3.5 - 4.0 |
Demographic
Title | Sample Response |
|---|---|
first_generation | Yes, No |
ethnicity | White, Black, Asian, American Indian or Alaskan Native, Hispanic, Pacific,Islander |
length_of_program | 1, 2, 3, 4 |
college | The Prairie University |
gender | Male, Female, Trans, Intersex, Gender non-conforming, Other, None of above |
year_of_graduation | 2020 |
athlete | Yes, No |
international_student | Yes, No |
veteran | Yes, No |
distance_learning | Yes, No |
scholarship | Yes, No |
adult_non_traditional | Yes, No |
living_in_residence | Yes, No |
dormitory | Yes, No |
residence_assistant | Yes, No |
Financial Information
Title | Sample Response |
|---|---|
pell_grant_eligible | Yes, No |
fafsa_status | Yes, No |
missing_documents | Yes, No |
outstanding_balance | Yes, No |
grant | Yes, No |
scholarship | Yes, No |
work_study | Yes, No |
loans | Yes, No |
Associating One Student with Multiple Fields
A student cannot be associated to multiple records in the student info csv file. Each student should be associated to one record and have data for each field. For example, if a student it studying Biology and Mathematics only one may be inputted in the "Major" field.
SAMPLE: STUDENT-INFO.CSV file
Extending Dynamic Audiences to Courses Integrations - Handling multiple student lines When leveraging the student-info.csv file for Courses integration and Dynamic Audience integrations, your files will have multiple lines due to the multiple courses associated to each student. However, the custom fields must be identical and replicated for each student record.
For example, here is a student-info.csv example for a student with the custom fields appended:
Key Point in Mapping Integrations
CSV integrations involve multiple key mappings for a successful end-to-end integration.
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.
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.
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 file 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.
Dynamic Audiences ready!
*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