canvas-lms

Contents

• canvas-lms.config Functions
• canvas-lms.http Functions
• canvas-lms.datetime Functions
• canvas-lms.announcements Functions
• canvas-lms.assign Functions
• canvas-lms.discuss Functions
• canvas-lms.grades Functions
• canvas-lms.message Functions
• canvas-lms.modules-pages Functions
• canvas-lms.students Functions
• canvas-lms.rubrics Functions

Modules

• canvas

Topics

• Getting started

Module canvas

User interface for managing Canvas LMS courses using its REST API.

There is a single table used in an object-like way for interacting with a single Canvas course. The functions below are stored within the canvas table and store their data and metadata in the same table.

canvas-lms.config Functions

set_debug (bool)	Set debug status, which disables interaction with the live Canvas API.
set_verbose (num)	Set verbose status, which echoes all interaction with the Canvas API.
set_course_id (str)	Set course ID, which defines course prefix.
set_url (str)	Set Canvas URL.
set_cohort (str)	Set cohort (e.g., year+semester).
set_token (str)	Set user token for authenticated to API (keep this secret!).
set_token_env (str)	Set environment variable to query for API token
set_cache_dir (str)	Set folder for storing cache files of this library.
set_first_monday (arg)	Set date of first Monday of teaching interval (multiple allowed).
set_break_week (arg)	Set last week before mid-interval break (multiple allowed).
set_break_length (arg)	Set number of weeks of mid-interval break (multiple allowed).

canvas-lms.http Functions

get_paginated (download_flag, req, opt_arg)	Paginated GET.
define_getter (var_name, field_name, index_name_arg, opt_default)	Define getter function to retrieve and store item metadata.
get (req, opt)	Wrapper for GET.
post (req, opt)	Wrapper for POST.
put (req, opt)	Wrapper for PUT.
patch (req, opt)	Wrapper for PATCH.
delete (req, opt)	Wrapper for DELETE.
file_upload (opt)	Upload a file to a Canvas course.

canvas-lms.datetime Functions

datetime (args)

Calculate the datetime from a table of "logical" date and time declarations.

canvas-lms.announcements Functions

update_announcement (title, opt)

Update metadata for a single announcement.

canvas-lms.assign Functions

get_assignments ()	Get assignments.
get_assignment_groups ()	Get assignment groups IDs.
assign_group_args	Setup assignment group arguments.
setup_assignment_groups (args)	Set up assignment groups.
get_assignment (dl_bool, assign_name, assign_opts)	Get full details of a single assignment.
create_assignment_args	Create assignment arguments.
create_assignment (args)	Create a Canvas assignment.
update_assignment (assignname, opt)	Basic assignment metadata update function.
update_quiz (assignname, opt)	Basic quiz metadata update function.
check_assignments ()	Compare assignments in Canvas to what has been defined locally.

canvas-lms.discuss Functions

get_discussion_topics ()	Get discussion topics and store their metadata and IDs.
setup_discussion_topics (args)	Create/edit up discussion topics.

canvas-lms.grades Functions

get_grade_columns ()	Retrieve and store the names and IDs of any added custom gradebook columns.
setup_grade_columns (columns)	Create custom gradebook columns.
get_assign_grades (opt)	Retrieve and store grades from specified assignments.
write_grades (gfile, assign_names)	Write grades to CSV from specified assignments.

canvas-lms.message Functions

message_user_args	Message user table arguments.
message_user (send_check, msg)	Message a specific Canvas user.

canvas-lms.modules-pages Functions

get_modules ()	Get all Canvas modules and store their metadata.
update_module (modname, opt)	Update metadata for a single module.
get_page_by_title (title)	Get content for a single page.
update_page (modname, opt)	Update metadata for a single page.
setup_modules (modules)	Create/edit all modules.
update_module_contents (module_name, ask, items)	Create/edit contents of an individual module.
check_modules ()	Suite of sanity checks for all Canvas modules.

canvas-lms.students Functions

get_student_groups ()	Get student groups.
get_student_group_categories ()	Get student group categories.
find_user (str)	Find a single user by name or ID.
get_students (opt)	Get all enrolled students.
get_groups_by_cat (use_cache_bool, group_category_name)	Get groups in a single category.
setup_group_categories (categories)	Creating group categories.

canvas-lms.rubrics Functions

get_rubrics ()	Get all course rubrics and store their metadata.
send_rubric (self, rubric)	Send a rubric to Canvas.
assoc_rubric (self, args)	Associate a rubric to an assignment.
rubric_from_csv (csvfile)	Read in a carefully structured CSV file and convert it into a rubric.
setup_csv_rubrics (self, args)	Read a collection of CSV files and create rubrics from them all.
delete_all_rubrics ()	Delete all rubrics.

canvas-lms.config Functions

set_debug (bool)

Set debug status, which disables interaction with the live Canvas API.

Parameters:

• bool

set_verbose (num)

Set verbose status, which echoes all interaction with the Canvas API. Default = 0, which hides most things

Parameters:

• num

set_course_id (str)

Set course ID, which defines course prefix.

Parameters:

• str

set_url (str)

Set Canvas URL.

Parameters:

• str

set_cohort (str)

Set cohort (e.g., year+semester).

Parameters:

• str

set_token (str)

Set user token for authenticated to API (keep this secret!).

Parameters:

• str

set_token_env (str)

Set environment variable to query for API token

Parameters:

• str

set_cache_dir (str)

Set folder for storing cache files of this library.

Parameters:

• str

set_first_monday (arg)

Set date of first Monday of teaching interval (multiple allowed).

Parameters:

• arg

set_break_week (arg)

Set last week before mid-interval break (multiple allowed).

Parameters:

• arg

set_break_length (arg)

Set number of weeks of mid-interval break (multiple allowed).

Parameters:

• arg

canvas-lms.http Functions

get_paginated (download_flag, req, opt_arg)

Paginated GET.

Parameters:

• download_flag true | false | "ask" | "cache"
• req string URL stub to GET from
• opt_arg table of optional parameters

Returns:

table REST result

This is the workhorse function for most commands that retrieve data from Canvas. Most REST interfaces use pagination to control sizes of return data. This requires iteration of multiple requests to return a full collection of information. Since this can be quite slow, this function has a built-in cache feature that stores the data to disk and if desired re-reads this cache instead of slowly requesting the data again. Where the cache is stored can be customised in the config file.

Usage:

canvas:get_paginated(true,self.course_prefix.."assignments")

define_getter (var_name, field_name, index_name_arg, opt_default)

Define getter function to retrieve and store item metadata.

Parameters:

• var_name string

  Name of Lua table field to store item data
  

• field_name string Name of REST field to retrieve item data from (nil -> use var_name`)
• index_name_arg string Name of metadata field to reference item data (default: "name")
• opt_default table Default options to pass to REST call Custom argument: download = true | false | "ask"

get (req, opt)

Wrapper for GET.

Parameters:

• req string URL stub to GET from
• opt table of optional parameters

Returns:

table REST result

post (req, opt)

Wrapper for POST.

Parameters:

• req string URL stub to POST to
• opt table of optional parameters

Returns:

table REST result

put (req, opt)

Wrapper for PUT.

Parameters:

• req string URL stub to PUT to
• opt table of optional parameters

Returns:

table REST result

patch (req, opt)

Wrapper for PATCH.

Parameters:

• req string URL stub to PATCH to
• opt table of optional parameters

Returns:

table REST result

delete (req, opt)

Wrapper for DELETE.

Parameters:

• req string URL stub to DELETE from
• opt table of optional parameters

Returns:

table REST result

file_upload (opt)

Upload a file to a Canvas course. The process for uploading files to Canvas is documented here.

Parameters:

• opt table Required argument opt.filename specifies filename to upload. opt.filepath.."/"..opt.filename defines where the file is to be found in the local filesystem. File will be uploaded in the root directory for the course or as specified by opt.folder. Additional arguments specified in the Canvas Files API.

canvas-lms.datetime Functions

datetime (args)

Calculate the datetime from a table of "logical" date and time declarations.

Parameters:

• args

canvas-lms.announcements Functions

update_announcement (title, opt)

Update metadata for a single announcement.

Parameters:

• title
• opt

canvas-lms.assign Functions

get_assignments ()

Get assignments. Data stored in .assignments table, indexed by assignment name. Code for this function uses the generic define_getter function in the HTTP submodule.

get_assignment_groups ()

Get assignment groups IDs. Gets details of each assignment group and stores their IDs for later lookup. Data stored in |self.assignment_groups|.

assign_group_args

Setup assignment group arguments. The function canvas:setup_assignment_groups takes a single table of arguments. The table should be an ordered list}

Fields:

• name The name of the assignment
• weight The weighting of the assignment group

setup_assignment_groups (args)

Set up assignment groups. If any assignment group weightings are specified, the course setting to enable assignment weightings is enabled.

Parameters:

• args table list of tables with fields defined by assign_group_args

get_assignment (dl_bool, assign_name, assign_opts)

Get full details of a single assignment.

Parameters:

• dl_bool bool Download data? Otherwise use cache, if available
• assign_name string Name of the assignment
• assign_opts table Additional REST arguments (link)

create_assignment_args

Create assignment arguments.

Fields:

• ask
• student_group_category (implies a group submission)
• omit_from_final_grade
• assign_type one of {"onlinequiz","none","onpaper","discussiontopic","externaltool"}
• due
• unlock
• lock
• published
• description
• descr_file
• rubric
• external_tool
• moderated_grading
• grader_count

create_assignment (args)

Create a Canvas assignment.

Parameters:

• args table arguments (see create_assignment_args)

update_assignment (assignname, opt)

Basic assignment metadata update function.

Parameters:

• assignname
• opt

update_quiz (assignname, opt)

Basic quiz metadata update function.

Parameters:

• assignname
• opt

check_assignments ()

Compare assignments in Canvas to what has been defined locally.

canvas-lms.discuss Functions

get_discussion_topics ()

Get discussion topics and store their metadata and IDs.

setup_discussion_topics (args)

Create/edit up discussion topics. Generally I like to set up all discussion topics once at the beginning of semester. Due to interface confusion I also prefer to keep a "frozen" list of discussion topics and not allow students to create their own. Defaults to published and nested. TODO: logical week conversion for delayed posting.

Parameters:

• args table

  Table of tables with REST arguments (see Canvas API documentation). Usage:

   canvas:setup_discussion_topics{
     { title = "Course Q&A" , pinned = true },
     { title = "Assign 1 discussion" },
     { title = "Assign 2 discussion" },
   }
  

canvas-lms.grades Functions

get_grade_columns ()

Retrieve and store the names and IDs of any added custom gradebook columns.

setup_grade_columns (columns)

Create custom gradebook columns. Currently this function only creates, not updates!

Parameters:

• columns

get_assign_grades (opt)

Retrieve and store grades from specified assignments.

Parameters:

• opt

write_grades (gfile, assign_names)

Write grades to CSV from specified assignments.

Parameters:

• gfile
• assign_names

canvas-lms.message Functions

message_user_args

Message user table arguments. The function canvas:message_user takes a table of arguments to define the message to send. The table may consist of the following}

Fields:

• canvasid The Canvas ID(s) of the recipient (reqd)
• subject The subject of the message to send
• body

   The body text of the message to send
  

• course The Canvas course ID to send from (defaults to defined course)
• group_conversation Whether a group message is sent (true, default) or multiple individual messages are sent (false) if multiple IDs are included
• bulk_message Default: |false|. Not sure what this does really but needs to be |true| for 100+ recipients and when |true| forces individual messages
• force_new

    Default: |false|. Not sure what this does really but when |true| forces individual messages
  

message_user (send_check, msg)

Message a specific Canvas user.

Parameters:

• send_check bool Toggle whether to truly send the message or just to pretty print it to the screen
• msg table

      Table with entries to define message according to <a href="index.html#message_user_args">message\_user\_args</a>
  

canvas-lms.modules-pages Functions

get_modules ()

Get all Canvas modules and store their metadata. Data stored in .modules table, indexed by module name. Code for this function uses the generic define_getter function in the HTTP submodule.

update_module (modname, opt)

Update metadata for a single module.

Parameters:

• modname
• opt

get_page_by_title (title)

Get content for a single page.

Parameters:

• title

update_page (modname, opt)

Update metadata for a single page.

Parameters:

• modname
• opt

setup_modules (modules)

Create/edit all modules.

Parameters:

• modules table List of ordered module names to create. If names are different than the modules currently defined, new ones are created and/or current modules are re-ordered. If modules exist that aren't specified, the function will offer to delete them (case-by-case).

update_module_contents (module_name, ask, items)

Create/edit contents of an individual module.

Parameters:

• module_name string
• ask string of whether to proceed — empty asks, or |"y"| does, or anything else does not
• items table (see Canvas API documentation for raw syntax) Table of module items has some shorthand definitions defined in the code. TODO: document these properly.

check_modules ()

Suite of sanity checks for all Canvas modules. * Checks if published module is empty * Checks if published items are located in unpublished module * More to come…

canvas-lms.students Functions

get_student_groups ()

Get student groups. A single list of all student groups in all group categories. Data stored in: .student_groups table indexed by name of the student group. Code for this function uses the generic define_getter function in the HTTP submodule.

get_student_group_categories ()

Get student group categories. Data stored in: .student_group_categories table indexed by name of the student group category. Code for this function uses the generic define_getter function in the HTTP submodule.

find_user (str)

Find a single user by name or ID.

Parameters:

• str

get_students (opt)

Get all enrolled students.

Parameters:

• opt

get_groups_by_cat (use_cache_bool, group_category_name)

Get groups in a single category.

Parameters:

• use_cache_bool
• group_category_name

setup_group_categories (categories)

Creating group categories.

Parameters:

• categories

canvas-lms.rubrics Functions

get_rubrics ()

Get all course rubrics and store their metadata. Data stored in: .rubrics table indexed by title of the rubric. Code for this function uses the generic define_getter function in the HTTP submodule.

send_rubric (self, rubric)

Send a rubric to Canvas. Note that rubrics are first defined independently from assignments, and later associated with an assignment.

Parameters:

• self
• rubric table definition

See also:

canvas.assoc_rubric

assoc_rubric (self, args)

Associate a rubric to an assignment.

Parameters:

• self
• args table arguments

rubric_from_csv (csvfile)

Read in a carefully structured CSV file and convert it into a rubric.

Parameters:

• csvfile string

setup_csv_rubrics (self, args)

Read a collection of CSV files and create rubrics from them all.

Parameters:

• self
• args table arguments

delete_all_rubrics ()

Delete all rubrics. This is sometimes needed when you create the same rubric over and over trying to get it right and you end up with many duplicates.