[ARCHIVED] Revising an API Call

[talway]

I am attempting to revise an API call that resides in a PowerShell script and am looking for some direction/advice (full disclosure, I have inherited someone else's program).  We have a course called New Student Orientation that students must complete prior signing up for classes.  Once they complete the NSO, a PowerShell script looks at the NSO and looks for an assignment to be completed.  If the assignment is complete, then the script removes a hold in the SIS.  The PowerShell script is using an API to look at Canvas and seeing who completed the assignment.  The line of code is this:  $url = "https://" + $domain + "/api/v1/courses/[course number]/assignments/[assignment number]/submissions?page2&per_page=100".  The course number and assignment number is removed for security purposes. 

We are in the process of revising the course and eliminating the assignment and the submission and replacing it with a quiz.  I am assuming that by using a similar API call that I can determine if a student has completed the quiz.  However, can someone please provide some insight as to what the language might be for the code?  I am not looking at a particular student but all students who have completed the quiz.

Thank you.

[robotcars]

Tagging Canvas Developers‌ for more support. I don't have any experience with PowerShell.

Are you asking what language the code is in, or just what new endpoint you might need to request the data from?

If it's a single quiz, for a single course, I believe that this one should do it.

Quiz Submissions - Canvas LMS REST API Documentation 

GET /api/v1/courses/:course_id/quizzes/:quiz_id/submissions

You'd then have to update the code to handle the values returned that are different than Assignment Submissions - Canvas LMS REST API Documentation 

It looks like the script is doing some Pagination, but I can't tell if it's looking for additional submissions if it hasn't found the last page. If not... Handling Pagination 

You can also preview the response using the Canvas Live API, just change the subdomain to match your Canvas instance and your own token.

You can also test your code against Beta or Test via edu.beta.instructure.com or edu.test.instructure.com

[James]

carroll-ccsd I really wish I could type as fast as you. When I started writing this, there were no responses and you beat me by 12 minutes. Thankfully, we contributed different things so I don't feel like mine was a total waste.

It also most sounds like Tom's school is doing something very similar to what  @kona  wrote about the way we handle things.

• Developing and Implementing a Mandatory Online Student Orientation (Published) 
• Mandatory Orientation Programming 
• Canvas Instructor Training and Student Orientation 

[robotcars]

I really wish I could come up with as much detail and dissection as you do as quickly, but I often only get surface deep until the conversation expands. It's fantastic that there's starting to be enough presence around here that multiple developers are responding on the day of original posting for a lot of topics and less questions going stale.

I actually posted at 8:57, but then realized a bit later than I bolded 'page' and not 'last'.

I also wish there was an original timestamp and edit timestamp.

[James]

 @talway  

The URL you provided is incorrectly formed. I'm going to hope that's just a typo. The page2 should be page=2, except that the number varies and should be obtained from the next Link header that is returned when you make the API call. It should not be hard-coded into the URL. The per_page=100 is commonly found as Canvas normally defaults to only 10 results; it's an attempt to reduce the amount of pagination.

We have a similar setup, including the use of a quiz as the checkpoint assignment. It doesn't matter whether it's a quiz or an assignment. You still use the submissions API and the assignment ID, not the quiz ID.

I don't use PowerShell, but the line you're asking about doesn't have anything to do with PowerShell.

I also limit the call so that it only returns the students who have a graded quiz. Actually, I get it once with graded and once with submitted, I never get the notice about submitted showing up. I think I put that in there in case there was a delay with the grading -- but that delay just doesn't happen much if at all in the years we've been using this. 

Then we remove the enrollment from the course once they have completed the orientation. This keeps the list of submissions short and quicker to obtain. Another option that is available now, but I don't remember it being available when we started, was the graded_since parameter. It allows you to get just the recent changes. Still, we don't want the students to be left in the orientation, we move them to a student resources / FAQ course that is the same without the quizzes.

Here is some documentation from the API.

• Pagination
• List assignment submissions is the call you're using.
• List submissions for multiple assignments allows you to be more selective in what you get returned, which makes it faster. It allows you to specify the workflow_state=graded and workflow_state=submitted or the submitted_since and graded_since flags.

My request looks something like this (line breaks supplied for readability). Replace ${variable_name} by however you do variables in PowerShell

/api/v1/courses/${course_id}/students/submissions

?student_ids[]=all

&assignment_ids[]=${assignment_id}

&workflow_state=graded

&per_page=25

I use per_page=25 because we run this every 20 minutes and so there are rarely more than a couple and I have pagination set up to handle if there are. You can specify per_page=100, but the requests feel like they take longer with 100 specified, even if there are still only just a couple to fetch.

One note about the pagination on the multiple assignment endpoint -- it does not use the page= parameter at all. It uses a bookmark, so you'll really need to follow the next link header -- or take actions (like we do with removing the accounts) to make sure that your list of students is always less than the per_page setting (which maxes at 100 for many/most things, so don't think you can get around it by specifying 1000 or some other arbitrarily large number). If the pagination issue still confuses you, you might start with this thread from Canvas Developers group: Handling Pagination 

[talway]

Thank you both for your responses.  I shall review the material that you both provided and see if I can get it to work in the parameters of our script.  My strength is in the LMS.  However, because of our department structure, I get programming by default.  While not familiar with API's, I'm learning.

[robotcars]

You're in good company here, come back and ask questions, we're happy to help.

[talway]

One a related note, are there any good websites, videos, documentation that you would recommend for a newbe?  Maybe APIs for Dummies?  I found a bunch of stuff on LinkedIn Learning but not if applies directly to Canvas.

[robotcars]

 @stuart_ryan ‌'s Encyclopedia of Canvas APIs: Getting started, the practical ins and outs, gotchas, tips, and tricks is it. Some more examples and topics are available on the Awesome List #CanvasAPI. The community has shared examples for interacting with the API in many languages and technologies.

The Canvas API is REST format, so search for REST tutorials. I guess the easiest way to think about it is as a headless/UI-less version of Canvas. Almost any page you see in Canvas can be returned as an API request, even within the browser. For example, take any course url and insert /api/v1 into the URL after .com/

http://edu.instructure.com/courses/123 

http://edu.instructure.com/api/v1/courses/123 and you can see a JSON response of that page.

The trick is using the Canvas LMS REST API Documentation to determine your task and pray there an endpoint that will allow you to complete it.

Here's a quick tutorial to play around with the API within the browser, but modifying the front end of Canvas has a different purpose than writing background automation tasks. But this is a decent starter without having to worry about Authentication and other choices. Developer Tools #2 - Update a course nickname with the API 

If playing around with the Canvas API seems scary, remember there are Test and Beta instances. I also sometimes tinker with https://reqres.in/ when what I'm trying to work on isn't Canvas specific.

[talway]

Robert:

Taking you up on your response about asking questions.  I have made the necessary changes to my script however, I get no results.  Basically to recap here is what is going on.  In our NSO course, we have changed the last step from an assignment whereby the student submits something to a quiz whereby the student must complete the quiz.  The script in it's present state, reads the assignment, looks at the list of students who have submitted the assignment (workflow_state equals "submitted") and then runs some SQL commands to update the SIS and remove the orientation hold.  This works as expected and designed.  So, I figured by updating the script to read the quiz, look for a list of students who have completed the quiz (workflow_state = "complete") that I would be good.  I used the methods as described in this post and the Canvas documentation to code with.  I can place the GET in a browser window and get a result.  I get no errors in my script but I also do not get any results.  I keep going back to the documentation thinking that I am missing something. 

In looking at my script I am just wondering if it is doing too much.  It first looks at the quiz submissions, it then takes a look a who has completed it.  It then looks at the names of the students to determine what ID is of the student who is enrolled and converts the Canvas ID to the SIS ID, and on and on.  It makes a lot of For Each passes through the data.  As I stated early on, I didn't write it but I believe that there's a much easier way to do it.  Hiring the Canvas development team is not an option.

[robotcars]

Hi Tom,

Friday was a bit busy for me.

It looks like what you described can be done with 1 endpoint now. I took a look at the API and found that the endpoint to get all quiz submissions might be all you need. This endpoint takes an additional parameter defined as an Association with include[]. Adding user I found that the API returned the quiz submission and user information, including the users name and user's sis id. 

Quiz Submissions - Canvas LMS REST API Documentation 

GET /api/v1/courses/:course_id/quizzes/:quiz_id/submissions

GET /api/v1/courses/:course_id/quizzes/:quiz_id/submissions?include=user

The associations come separately, which means in code or somewhere you'll have to merge them together. I'm not sure how to do this with PowerShell.

[James]

This shows that there are often multiple ways to get at something.

I go back what I wrote on December 17 and still say use Submissions instead of Quiz Submissions. You can get those submitted since the last time you checked and it makes for a really quick API call if no one has done anything recently. If you are removing them from the course once they've completed it, then it won't matter much, but if you're leaving them in the course, that can save a lot of time. Adding in include[]=user gives you the user information as part of the submission object, not as a separate array like quiz submissions does.

You can also get this information through GraphQL, which allows you to pull in information from multiple tables into one request. Start off with the assignment and then add a submissionsConnection to get those who have submitted it. There are some user properties there; unfortunately SIS ID is not one of them. If you get the submissions and include[]=user, then that does include the sis_user_id (provided the token being used is tied to someone with the required permissions).

In the end, Tom is trying to patch something that already exists, so it may be quicker to stick with Quiz Submissions, but I wouldn't start out that way with a new process.

[talway]

Thank you James.  Multiple ways indeed.  You all have been great with the information provided.  However, I'm about ready to punt this down the road as the frustration level is growing.  I have used your suggestions and I have found what works and what doesn't...by just using the web browser.  However, when I replace what is in my script with what I have found to work, it returns no results.  It just acts like no one has submitted the assignment, or in this case, completed the quiz, which I know not to be true.  I will keep working on it.  At this point I'm convinced that something else in the programming is tripping it up.

Thank you very much.