Provisioning Canvas:
Manual,
Batch,
or Transactional?
Brent Shaw
bs@ucf.edu
Senior Systems Programmer
Center for Distributed Learning
University of Central Florida
About the
University of Central Florida
• 59,770 students (Spring 2014)
• 1,965 faculty & adjuncts
• 12 regional campuses
• 2013/4 budget: $1.45 B
• 180 buildings on 1,415 acres
• Classes started in October, 1968
Page 2 / 253
Provisioning Canvas
18 June 2014
About Me
• Yes, bs@ucf.edu really is my
email address
• UCF’s first LMS administrator in 1998
(when WebCT was in Beta for the first time)
• Worked for WebCT Inc. for a year
• I’m a lazy programmer.
• This is boring. Please laugh.
Page 3 / 253
Provisioning Canvas
18 June 2014
Words of Wisdom
“I can build one of the best
networks in the world…
“Until people want to start using it.”
-Anonymous Network
Architecture Instructor
Page 4 / 253
Provisioning Canvas
18 June 2014
Canvas is Awesome!
But do we HEROs really
have to add actual users?!?
Brent Shaw
bs@ucf.edu
Senior Systems Programmer
Center for Distributed Learning
University of Central Florida
The Provisioning Triad ™
Which (1) COURSE / SECTION
is being taught by which (2) INSTRUCTOR
to which (3) STUDENTS ?
If you don’t have that information at a minimum,
this presentation won’t help (much).
More information is better!
Page 6 / 253
Provisioning Canvas
18 June 2014
The SIS has The Triad ™
• Colleges / Departments Build Class Schedules
– Create Classes and Sections (1)
– Assign Instructors (2)
• Students Enroll in Classes (3)
• Implicit in the Triad are users.
– “Triad” is cooler than “Quartet”
Page 7 / 253
Provisioning Canvas
18 June 2014
The SIS has More Information
• Start / Stop dates of classes
• Terms
• Crosslisting
• TAs / Observers, other roles
• Changes in information !!!
• Adds / Drops
– Courses
– Enrollments
Page 8 / 253
Provisioning Canvas
18 June 2014
Provisioning:
SIS Information  LMS
• Information has to get from the SIS to
the LMS:
1. Manually
2. Batches
3. Transactions
• Some combination of manual, batches
and transactions
Page 9 / 253
Provisioning Canvas
18 June 2014
Manual
• Often involves someone typing directly
into Canvas
• Complete Free for All!
– Allow
– Allow
– Allow
– Allow
people to create their own user accounts
users to create their own classes / sect.
users to self enroll
instructors to enroll students
• Administrator manually matching your SIS
Page 10 / 253
Provisioning Canvas
18 June 2014
Manual
Pros
• Hands off for
administrators
• Valuable for sub-accounts
• Allows for flexibility
– Personnel training not
contained in SIS
• Great for “one offs”
– Pragmatic solutions
– Gets the job done
Page 11 / 253
•
•
•
•
•
Cons
Wild Wild West
Little control
Auditing / Reporting is
difficult ($$$)
Difficult to capture
changes in data
Not scalable
Provisioning Canvas
18 June 2014
Batches
• Chunks of data processed all at once
– As little as one record
– As much as 249,000 users
• In Canvas this means a CSV file
– CSVs can be uploaded into Canvas 2 ways
• Manually through the GUI
• Programmatically through the APIs
• CSVs Allows for snapshots and incrementals
Page 12 / 253
Provisioning Canvas
18 June 2014
Batches
•
•
•
•
•
Pros
CSVs are a simple format
Easy to export data from
SIS to a CSV file
Can be run multiple times
a day
Can be uploaded
manually or with APIs
Greatest return on
investment
Page 13 / 253
Cons
• Not “immediate”
• CSV files will be queued in
the order they are received
• Not granular
• Catching errors is more
difficult
Provisioning Canvas
18 June 2014
Transactions
• Triggered by a change in the SIS
– Could be a new item
– Course be a change
• A single “piece” of information is sent to
the LMS immediately using the API
– Success or failure is immediately known
Page 14 / 253
Provisioning Canvas
18 June 2014
Transactions
Pros
• Immediacy
• Allows for better error
handling
Cons
• Potentially lots of API call
need to be made in a
short period of time
– 3k / hour limit
• Harder to program
– Must catch errors
– Failures won’t be fixed in a
snapshot
Page 15 / 253
Provisioning Canvas
18 June 2014
Technical Details for
Provisioning Implementation
• Planning
• SISIDs
• Canvas CSV Files
• Batches
• Transactions
• A word about pagination
• APIs for batches / CSV uploads
• APIs for transactions (reference only)
Page 16 / 253
Provisioning Canvas
18 June 2014
Planning for Your Provisioning
• Time spent planning is never wasted
• Get to know your data
– What are the quirks in the data?
• Which do you have to account for?
• Which can you ignore?
– Trick question! You shouldn’t ignore any of the quirks
• Get to know your data source
– Who will get you The Triad?
– How often is data available?
Page 17 / 253
Provisioning Canvas
18 June 2014
Planning for Your Provisioning
• What do users expect?
– Students want it now!!!
• Transactions for enrollments?
– Instructors want it correctly.
– Registrars want it officially.
– SIS administrators want it conveniently.
Page 18 / 253
Provisioning Canvas
18 June 2014
SISIDs: Choose Wisely
• SIDID = Student Information System ID
– Unique identifier
• Automatically generated by your SIS
• SISID is the link between objects in your
LMS and your SIS
• Lots of things have SISIDs in an LMS:
– Users
– Courses and Sections
– Terms
Page 19 / 253
Provisioning Canvas
18 June 2014
SISIDs: Examples
• Our User SISID looks like this:
0111614
• Our Course SISID looks like this:
1470-UCF01-GEO-1200-SEC0001
• Every section gets a course and section
– The section SIS ID is: 1470-UCF01-GEO-1200-SEC0001
– The course SIS ID is: 1470-UCF01-GEO-1200-SEC0001
Page 20 / 253
Provisioning Canvas
18 June 2014
Canvas CSV Files
• In theory CSV files are standard
• In practice CSV files are different
• https://canvas.instructure.com/doc/api/
file.sis_csv.html
Page 21 / 253
Provisioning Canvas
18 June 2014
Canvas CSV Files
Things that can be added to Canvas using CSV files
1. Users
• That order is important
2. Sub-accounts
• Not all of them have to be
created
3. Groups
• The Triad would be:
4. Group memberships
0. Sub-accounts
5. Terms
• (manually created?)
6. Courses
1. Users
7. Sections
2. Courses
3. (Sections)
8. Enrollments
4. Enrollments
9. Crosslisting
Page 22 / 253
Provisioning Canvas
18 June 2014
A Word About Pagination
• For API calls that return large data sets
Canvas returns chunks of data
• Ex: An API call with1,000 results would take
10 API calls returning chunks of 100
• Create a wrapper to automatically handle
pagination of API calls
https://canvas.instructure.com/doc/api/file.pa
gination.html
Page 23 / 253
Provisioning Canvas
18 June 2014
APIs for Batches - Upload
• Upload a single CSV
-- OR -• Upload a ZIP file containing several CSV
files
https://canvas.instructure.com/doc/api/si
s_imports.html#method.sis_imports_api.c
reate
Page 24 / 253
Provisioning Canvas
18 June 2014
APIs for Batches - Upload
Request (POST with Attachment)
POST
https://webcourses2c.beta.instructure.com
/api/v1/accounts/89347/sis_imports
Page 25 / 253
Provisioning Canvas
18 June 2014
POST https://webcourses2c.beta.instructure.com/api/v1/accounts/89347/sis_imports
Authorization: Bearer <REALLY_POWERFUL_TOKEN_GOES_HERE>
Content-Length: 58095
Content-Type: multipart/form-data; boundary=xYzZY
--xYzZY
Content-Disposition: form-data; name="import_type"
instructure_csv
--xYzZY
Content-Disposition: form-data; name="attachment"; filename="2014-06-16-13:19:122014-06-16-12:00:04-CANVAS_MEMBER.CSV"
Content-Type: text/csv
course_id,user_id,role,section_id,status
1515-UCF01-BMS-6001-SEC0001,0111614,teacher,1515-UCF01-BMS-6001-SEC0001,active
Page 26 / 253
Provisioning Canvas
18 June 2014
APIs for Batches - Upload
• Response (JSON)
– Returns a creation object
{
'ended_at' => undef,
'created_at' => '2014-06-16T17:32:13Z',
'progress' => 0,
'updated_at' => '2014-06-16T17:32:13Z',
'data' => {'import_type' => 'instructure_csv' },
'id' => 5167983,
'workflow_state' => 'created'
};
Page 27 / 253
Provisioning Canvas
18 June 2014
A Word About batch_mode
• The “batch_mode” parameter is
available for SIS CSV file uploads.
• Don’t use it unless you know exactly
what it does. (It overwrites everything.)
• Make sure you test it on BETA / TEST.
• More information about batch_mode:
– http://guides.instructure.com/m/4214/l/80
122-what-are-sis-imports
Page 28 / 253
Provisioning Canvas
18 June 2014
A Word About Stickiness
• Stickiness in Canvas is the idea that
changes to information made through
the GUI will not be overwritten by SIS
imports.
• Useful for manual tweaks via CSV file
• Not all fields respect stickiness
Page 29 / 253
Provisioning Canvas
18 June 2014
A Word About Stickiness
Not all fields are “Sticky” – These are the Sticky fields
Account
name
Abstract_course
Name
short_name
enrollment_term_id
Course
Section
course_id
name
name
start_at
start_at
end_at
end_at
Group
restrict_enrollments_to
name
_section_dates
Enrollment
name
start_at
course_code
end_at
start_at
conclude_at
restrict_enrollments_to_course_dates
enrollment_term_id
workflow_state
Page 30 / 253
Term
Provisioning Canvas
User
name
sortable_name
short_name
Pseudonym (Login)
unique_id (login_id,
username...)
18 June 2014
APIs for Batches - Status
• Now that you’ve uploaded it, you’ll want
to see if it finishes
https://canvas.instructure.com/doc/api/si
s_imports.html#method.sis_imports_api.s
how
Page 31 / 253
Provisioning Canvas
18 June 2014
APIs for Batches - Status
• Request (GET)
– Use the SIS Upload ID from the status
object returned from the file upload
GET
https://webcourses2c.beta.instructure.co
m/api/v1/accounts/89347/sis_imports/51
67983
Page 32 / 253
Provisioning Canvas
18 June 2014
APIs for Batches - Status
• Response (JSON)– In Progress
{ "created_at": "2014-06-16T18:06:07Z",
"ended_at": null,
"updated_at": "2014-06-16T18:06:08Z",
"progress": 1,
"id": 5167983,
"workflow_state": "importing",
"data": {
"import_type": "instructure_csv",
"supplied_batches": ["user"] }
}
Page 33 / 253
Provisioning Canvas
18 June 2014
APIs for Batches - Status
COMPLETED
{"created_at": "2014-06-16T07:00:11Z",
"ended_at": "2014-06-16T10:31:18Z",
"updated_at": "2014-06-16T10:31:18Z",
"progress": 100,
"id": 5167983,
"workflow_state": "imported_with_messages",
"data": { "import_type": "instructure_csv",
"supplied_batches": ["user"],
"counts": {"accounts": 0, "terms": 0,
"abstract_courses": 0,
"courses": 0,
"sections": 0,
"xlists": 0,
"users": 249999,"enrollments": 0, "groups": 0,
"group_memberships": 0,
"grade_publishing_results": 0}},
"processing_warnings": [
["attachment_3703675020140616-22926-1h0xf.CSV", "user 3600989 has
already claimed 3619372's requested login information, skipping"]
]}
Page 34 / 253
Provisioning Canvas
18 June 2014
APIs for Batches - Show All
• Canvas will tell you about all your SIS
imports
https://canvas.instructure.com/doc/api/si
s_imports.html#method.sis_imports_api.i
ndex
Page 35 / 253
Provisioning Canvas
18 June 2014
APIs for Batches - Show All
• Request (GET)
GET
https://webcourses2c.beta.instructure.co
m/api/v1/accounts/89347/sis_imports
Page 36 / 253
Provisioning Canvas
18 June 2014
APIs for Batches - Show All
• Response (JSON)
• List of JSON objects
– In Progress
– Completed
Page 37 / 253
Provisioning Canvas
18 June 2014
APIs for Transactions
• Far too many to give examples
• I’ll list the APIs that could be used for
provisioning Canvas
Page 38 / 253
Provisioning Canvas
18 June 2014
APIs for Transactions Users
• Create a user
• Update user settings
• Edit a user
• Delete a user
• Merge user into another user
https://canvas.instructure.com/doc/api/us
ers.html
Page 39 / 253
Provisioning Canvas
18 June 2014
APIs for Transactions Sub-accounts
• List accounts
• Get a single (sub)account
• Get the sub-accounts of an account
• Update a (sub)account
• Create a new sub-account
https://canvas.instructure.com/doc/api/ac
counts.html
Page 40 / 253
Provisioning Canvas
18 June 2014
APIs for Transactions Groups
• Get a single group
• Create a group
• Edit a group
• Delete a group
• Invite others to a group
https://canvas.instructure.com/doc/api/gr
oups.html
Page 41 / 253
Provisioning Canvas
18 June 2014
APIs for Transactions Terms
• List Enrollment Terms
(That’s all- can’t create or edit with APIs)
https://canvas.instructure.com/doc/api/en
rollment_terms.html
Page 42 / 253
Provisioning Canvas
18 June 2014
APIs for Transactions Courses
• Create a new course
• Conclude a course
• Get course settings
• Update course settings
• Get a single course
• Update a course
• Update courses
https://canvas.instructure.com/doc/api/courses.
html
Page 43 / 253
Provisioning Canvas
18 June 2014
APIs for Transactions Sections
• List course sections
• Create course section
• Cross-list a Section
• De-cross-list a Section
• Edit a section
• Get section information
• Delete a section
https://canvas.instructure.com/doc/api/sections
.html
Page 44 / 253
Provisioning Canvas
18 June 2014
APIs for Transactions Enrollments
• Enroll a user
• Conclude an enrollment
– Deleted  Active
– Active  Concluded
– Concluded  Deleted
– Active  Deleted
https://canvas.instructure.com/doc/api/en
rollments.html
Page 45 / 253
Provisioning Canvas
18 June 2014
APIs for Transactions Crosslisting
• Cross-list a Section
• De-cross-list a Section
https://canvas.instructure.com/doc/api/se
ctions.html
Page 46 / 253
Provisioning Canvas
18 June 2014
Combination of Techniques
• Manual:
– Handle things not in the SIS (Training…)
– Manage some sub-accounts
• Allows for delegation of responsibility
– Crosslisting
• Batch:
– Users: creation & changes - Once a day
– Course / Section Creation - Multiple times a day
• Transaction:
– Enrollments
Page 47 / 253
Provisioning Canvas
18 June 2014
Questions?
Comments?
Suggestions?
Brent Shaw
bs@ucf.edu
If you liked it …
Please tell people you saw Brent
from the
University of Central Florida
Page 49 / 253
Provisioning Canvas
18 June 2014
If you didn’t like it …
Please tell people you saw someone’s
random Central Florida vacation pictures…
Page 50 / 253
Provisioning Canvas
18 June 2014