Recently I had a faculty member ask if there was a way to get a breakdown of a rubric showing how many students scored in each rating of a criteria. This would be a useful view to help determine where students were having trouble. The modified view of the rubric might look something like this:
Here you can see in red the number of students that scored in each of the ratings associated with the criteria "Requirements". This is a simple example, but hopefully illustrates how this might be useful.
I exposed a feature to faculty to access this report through our LTI application. LTI is a subject for another time, but I'll walk through the API calls that I used to pull this view together.
Note: There is more than one way to code a solution, and more than one language code it with. The purpose of this post is to give you general guidance on where to find the information needed, implementation is in your hands.
Get the Course Details
Given the course id, or the sis id, get the course definition so you can have the short name, full name, and any other course details you would like to include in the output. Documentation on the API call to get course details can be found here:
Courses - Canvas LMS REST API Documentation
If you are using the Canvas course id:
/api/v1/courses/:id
If you are using the sis id the API call will look like this:
/api/v1/courses/sis_course_id:[your_sis_id]
The schema for a course can be found here:
Get List of Assignments
The next step is to get a list of assignments for the course. You will inspect each assignment to determine if there is an associated rubric. Documentation on the API call to get a list of assignments can be found here:
Assignments - Canvas LMS REST API Documentation
GET /api/v1/courses/:course_id/assignments
The schema for an assignment can be found here:
Where is the rubric definition?
So exactly where do you find the rubric? The Assignment definition contains the variable rubric. This is the full definition of the criteria and associated ratings that will be used to generate the final report.
If you look at the Assignments Schema you will see a property name rubric. I recommend that you use something like Postman (Postman - Chrome Web Store ) to manually call the API to retrieve details of an assignment that uses a rubric, and inspect the results. It will be much easier to see the structure of the rubric if you look at the actual results.
Get Assignment Submissions
Now you will need to iterate through the assignments, and load all submissions associated with each assignment. Documentation on the API call to get submissions can be found here:
Submissions - Canvas LMS REST API Documentation
GET /api/v1/courses/:course_id/assignments/:assignment_id/submissions
IMPORTANT: Be sure to read the section on "Request Parameters", you will need to include a parameter to tell Canvas to send back the "rubric_assessment". The API call with the parameter will look like this:
GET /api/v1/courses/:course_id/assignments/:assignment_id/submissions?include[]=rubric_assessment
The schema for a submission can be found here:
I recommend that you use something like Postman (Postman - Chrome Web Store ) to manually call the API to retrieve details of a submission that has been graded with a rubric, and inspect the results to see the structure of rubric_assessment. This variable contains the results of the graded rubric for the submission, which you will need.
If you are using dynamic objects, it will be easy to store a list of submissions with each assignment.
Generate Rubric Data
Now that you have assignments and submissions, you can start to gather the data.
Inspect each assignment for the use of a rubric, look for the value assignment.use_rubric_for_grading to be "true".
Also confirm that the assignment has submitted work, i.e. assignment.submissions.Count > 0.
If there are no submissions you likely want to skip this rubric as there is no associated work.
For each assignment that you are going process:
Create a rubric dictionary
Each criteria in the rubric has a unique id, this will come in handy. Create a dictionary using the criteria id as the key, and the criteria as the value. You will see later that the submission references the criteria by id. Creating the dictionary will allow you to quickly find the correct criteria to update without having to constantly iterate through the items.
As I added the criteria to the dictionary, I added a variable to each rating: rating.students = 0
This is the value we will use to count how many students scored in each criteria rating.
Inspect Submissions
Assuming we have found an assignment with a rubric, and there is submitted work to inspect, start iterating through the submissions. Each submission will have a rubric_assessment variable containing the rating values for each criteria.
NOTE: The API documentation was not clear on the structure of the rubric_assessment variable. I suggest using Postman to make an API call for a submission that was graded with a rubric, and inspect the results to get a clear picture of the structure.
Steps I took to tie it all together:
- Iterate through each submission and look at the rubric_assessment value.
- Iterate through each element of the rubric_assessment and use the rubric dictionary to find the criteria:
- Using the criteria from the dictionary, then you will need to find the rating that matches the points in the assessment.
- Using the rating, increment the value for rating.students (this is the variable we injected into the rating object when we built the dictionary)
By using dynamic objects to represent the rubric and all of the internal pieces, the rubric object that we started with in the Assignment is now updated with the student count for each criteria rating, and can be used to generate report output.
Rinse and repeat... do this for each assignment that you would like to report on.
I kept it simple, and report on all graded assignments period.
Report the results
The rubric for each assignment is now updated with the student count for each rating in each criteria. You can dump the rubrics to a simple CSV file, or you can format an HTML report, the choice is yours.
Regardless of what data you are trying to pull out of Canvas using the API, I strongly recommend using something like Postman or DHC REST Client so you can manually make the API calls and inspect the results to make sure you are getting the expected results.
If people find this useful, I will work on a write-up on my gradebook analysis report, which allows faculty to request a summary report outlining potential errors that should be corrected before posting grades back to the SIS.
2016.11.14 - Update
If you would like to see source code demonstrating how to make API calls in .NET, I have posted a blog with source code here:
From this example you can derive your own workflows to automate admin tasks or reports.
