CanvasHelper is a Python application which uses the Instructure Canvas LMS API to automate several functions in the Canvas LMS which are not included in the web app by default.
Current and future abilities of CanvasHelper include (italics for unstable/in development):
- Adding a user to a course without sending an invitation email
- Getting enrollment reports for individual classes or every class in a term
- Creating groups and group categories, and allocating students into the groups.
- Creating Scheduler blocks of appointment groups for student self-signup
- Changing the time zone or other settings on behalf of a group of students (for campus rotation)
- Creating copies of courses from a course shell template
- Changing notification preferences for students' communcation channels
- Getting a per-student list of enrolled courses
CanvasHelper has been developed for and on OS X. That's not to say that other platforms won't work - just that I haven't tried them.
Note: This will install pip (the python package management system) and run the setup.py
script to install the required python packages and create the executable, as well
as creating a shortcut in /Applications
.
- Move the CanvasHelper code folder to the directory in which you'd like to store it.
- Double-click the setup.app application to launch the installer.
- Click OK to confirm, then navigate to the directory where you put the code files.
- Wait for the install process to complete.
- Launch the script from
/Applications
(app nameCanvasHelper.command
)
- Move the CanvasHelper code folder to the directory in which you'd like to store it.
- cd into that directory.
- Type
sudo -H ./setup.sh
and hit return. Enter your password at the prompt.
The first time it is launched, CanvasHelper will prompt you to create and save your API access tokens. When you provide the website endpoint (which must be HTTPS, e.g. https://example.test.instructure.com), a browser page will launch and ask for authorisation. After authorisation is approved, you will be redirected back to your Canvas main page, but with a long 'code' string in the URL. Copy this entire URL back into CanvasHelper, and your API token will be retrieved and saved for future use.
API access only needs to be authorised once, unless the tokens are revoked from the Canvas
settings page. If you need to delete your saved tokens
from CanvasHelper, or need to add new tokens, simply delete the file titled sensitive.json
from the code folder, and upon next launch, CanvasHelper will prompt you to enter API tokens.
If you're an institution that wants to use this software and don't have access to a devkey, feel free to send me a message to ask for use of mine. Developers will need to request a devkey from Instructure.
You'll need to create a devkey.json
file in the code/canvashelper
folder, with the following data:
{"client_id":YOUR_CLIENT_ID, "client_secret":YOUR_CLIENT_SECRET}
Double-click CanvasHelper.command in /Applications
to launch the script.
The script can also be launched from the command line by changing into the
CanvasHelper/CanvasHelper/
directory and running
python canvashelper.py
Any scripts that output data, usually in .csv spreadsheet format, will be saved in the
CanvasHelper/output
folder.
Function | Description |
---|---|
Add a Single User Enrollment | Add a single student, TA, etc. to a single course without sending an invitation. |
Get Printable Course Groups Report | Pulls a printable, easy to read report for all groups in a course in a spreadsheet. |
Get Enrollment Report for Single Course | Pulls an list of all students in a course, with an empty column (for adding group name/number). |
Create and Assign Groups from CSV | Using a CSV input in the same format as the Get Enrollment Report, creates a group category, creates all the groups, and assigns students into groups. |
Get Enrollment Report for Single Course with Groups | Using the same format as the Enrollment Report (not as easy to read when printed), pulls a report but with the Group column already filled in. |
Get Enrollment Reports for All Courses in a Term | Provides a list of terms and asks for a choice, then performs the "Get Enrollment Report" operation for all courses in the chosen term. |
Create Appointment Group (Scheduler) | Allows easy creation of Scheduler time slots based on CSV input, which makes it possible to include breaks in the Scheduler. |
Note: The CSV layouts for input are inflexible. Notably, some must include headers and some cannot include them. If you're using Excel on a Mac, you must format the files as 'Windows Comma Seperated', otherwise you'll encounter a 'newline' error. Many/most of the existing bugs are related to formatting of the CSV inputs. If you find any, let me know about them!
Includes and requires a header
Name | SIS User ID | Group/Module |
---|---|---|
James Bond | 007007 | Group 6 |
Alec Trevelyan | 006006 | Group 6 |
Note: Group/Module header will be generated when pulling an enrollment report. When pulling an Enrollment Report with Groups, the header will be labelled Group.
For uploading, the Create and Assign Groups from CSV script will ask for the header of the column which represents SIS ID and the header of the column which represents the group name or number. These must be typed exactly as they appear in the CSV.
Does not include a header
Group 1 | James Bond | Alec Trevelyan |
007007 | 006006 | |
james.bond@instructure.com | alec.trevelyan@instructure.com | |
Group 2 | Indiana Jones | Henry Jones, Sr. |
0010001 | 191919 | |
indiana.jones@instructure.com | henry.jones@instructure.com |
Note: As you can see, the formatting is not ideally suited for a script to parse through, but is much easier to see visually. This makes it suited for printing reports for instructors if they prefer a printed copy over viewing the groups from within Canvas.
Does not include a header
Scheduler Event 1 | 25/07/2015 | 9:00 | 9:45 | EST | course_sis_id |
Scheduler Event 2 | 25/07/2015 | 10:00 | 10:45 | EST | course_sis_id |
Scheduler Event 2 | 25/07/2015 | 13:00 | 13:45 | EST | course_sis_id |
Scheduler Event 2 | 25/07/2015 | 14:00 | 14:45 | EST | course_sis_id |
The row layout is as follows:
Event Title | Date | Start Time | End Time | Time Zone | Course SIS ID |
Note: The script will sort the events by title, assigning them into one Scheduler group. It will prompt you for max participants per slot, and the max and min slots a student may sign up for. It will also ask whether or not to publish the events immediately.
├── root
| ├── CanvasHelper
| ├── canvashelper
├── python script files
├── get-pip.py
├── main.py
├── setup.py
└── setup.sh
├── README.md
├── logs
├── output
└── setup.app
The main script files are kept in the /CanvasHelper/canvashelper
folder. Diagnostic or troubleshooting
logs can be found in /logs
, and any scripts that output data will put
their files (usually CSV format) in /output
.
Designed and developed by Jason Gwartz while at Hult International Business School. The Canvas API documentation can be found here.
README Changelog:
- 31/07/2015: Adjusted folder structure to match new folder setup. Moved readme to root directory so it shows on Github preview.
- 29/07/2015: Added Functionality list and example CSV layouts. Added better formatting for code.
- 29/07/2015: Version 1