Skip to content

Home

Jump to bottom
Ben Smith edited this page Jun 14, 2019 · 11 revisions
Clone this wiki locally

Overview

This software extracts the current grades from a list of courses in Canvas. Once extracted, it sends each student a message indicating their current grade in each class and produces a list of 'at-risk' students for the advisors. A message received by a student might be something like:

This message is to inform you of your standing in select CBA courses. As of right now, your score in FNBK3250 is 89.01. Your current grade is a(n) "B+." This score is based on the current data in Canvas. Please contact your instructor if you have any questions.

This message is fully customizable. The spreadsheet generated has the following columns: Student, Course, E-Mail, Current Score, and Current Grade.

This script works functionally independent of scale -- it doesn't really matter if one class is involved or 100. All that is needed is a Canvas account and Google Apps Script (included with G Suite). There is three versions of the script: one that checks the term id and courses against a Google Spreadsheet ("checks" version), one that does not ("no-check" version) and one that sends additional information based on the course ("course-specific" version). The advantage of the first is that you need not unenroll the generic Canvas account from all courses after the term ends. The advantage of the second is that it is easier to setup. The "course-specific" version is identical to the "checks" version other than the addition of the ability to send course-specific information.

How does this work

Canvas has an application programming interface (API), a mechanism where a piece of software can programmatically talk to another. In this case, if a Canvas user account has access to the grades of students in a given course, that same user account programmatically has access to those grades.

Google Apps Scripts are programs that run within a user's Google account -- there is no need to setup a server. However, the language supports talking to APIs, sending email, and writing to Google Spreadsheets. This program was written in this language to keep the costs for the institution at zero.

What you need

  1. A generic Canvas account
  2. A generic Google account
  3. the software

A Canvas account is needed to enroll in each of the classes you wish to be involved in the program. The Google account is need to run the software from within Google App Scripts.

Steps to set this up

  1. Log into Canvas using the generic Canvas account
  2. From Account->Settings, click "New Access Token" to generate an API key for the generic account. Name the key whatever you want, but make sure to write down the key.
  3. Open Google Drive using the generic Google account
  4. Add a Google Apps Script from "+ New -> More"
  5. Copy the code from this software into files named "Code.gs" and "Utility.gs" (you will have to create a file named "Utility.gs")
  6. From within Google Drive, create a blank spreadsheet. Write down the url of this spreadsheet (from the address bar). This is your "storage sheet."
  7. Create a second blank spreadsheet. Write down the url of this spreadsheet. This is your "danger sheet."
  8. If you are using the "checks" or "course-specific" version of the software, create a spreadsheet listing all courses in the first column. Write down the url of this spreadsheet.
  9. If you are using the "course-specific" version, add the course specific information to column two. For instance, you might add the tutoring lab hours for that specific course.
  10. Run the script manually once (select the function "main" from the menu bar selection function drop down and click the run arrow). This will trigger a permissions request allowing you to grant the script access to resources in your Google account. This will trigger an error if you have not already set script properties (next section). But, the goal here is simply to grant permissions to the script; the script need not run successfully.
  11. Using an admin Canvas account enroll the generic Canvas account in all courses for which you want the script to be active. Depending on your Canvas permission setup, you might need to enroll the account as an "Observer" with special permissions or a "Teacher."

Setting up Script properties

The script must have the following script properties defined (set under File->Project Properties->Script Properties within the Apps Scripts editor):

Script Property Example
THRESHOLD 75
DOMAIN unomaha.edu
MESSAGE_SUBJECT CBA Periodic Grade Report
CANVAS_API https://unomaha.instructure.com
DEVELOPER_KEY Developer Key From Canvas
MESSAGE_HEADER This message is to inform you of your standing in select CBA classes. As of right now, your score in
MESSAGE_FOOTER This score is based on the current data in Canvas. Please contact your instructor if you have any questions.
TERM 1
COURSE_LIST https://docs.google.com/spreadsheets/d/1r1byAiO_6KhUSyJcVXAvTqOP0Uqw9eyQi-AIIDU7WBY/edit#gid=0
DANGER_SHEET https://docs.google.com/spreadsheets/d/1lM-bomPSIGyYm0Myt-T2KQXIYsAcZB3jUrUlci5H_Gk/edit#gid=0
EMAIL_STORAGE https://docs.google.com/spreadsheets/d/13tdBNFECF-6nMxAMhCFwbg2m1PB1iicYNpxRopJskZM/edit#gid=0

The "TERM" and "COURSE_LIST" properties are only necessary if you are using the "checks" or "course-specific" version of the software.

Fill in each of these values as appropriate. The threshold specified indicates which student records will be written to the 'danger sheet.' Any student grade below this threshold will be recorded. It is of note that the file is a standard Google Spreadsheet. Therefore, it can be shared with those who need to act on the information (e.g. advisors). Each time the script is run, it creates a new spreadsheet within the same document.

Automating the Script

Google Apps Scripts can be run on a schedule using Google Developer Hub. From within Google Apps Scripts, click the "trigger" button (it looks like a clock in a chat bubble). Click the "Add Trigger" button (bottom right corner).

From within the add trigger dialogue, select that you want to run the function "main," the development version is "Head," and the event source is "Time-drive." The type of time based trigger can be specified as "Specific date and time." You will then need to enter in the date and time in YYYY-MM-DD HH:MM format. You can repeat this process to specify as many triggers as you want.

Getting Help

If you encounter any issues setting up this program, please contact Ben Smith at bosmith@unomaha.edu.