How can I retrieve a list of users in an enrollment term

[vicker]

Currently, I retrieve all courses with an enrollment term first, followed by all users enrolled in the list of courses. It works well, but given that 1 user may enroll into multiple courses, the amount of duplicated information seems to be a large overhead. If there's a more straightforward way that will be awesome.

[James · Accepted solution]

vicker​,

That is a lot of duplication and it's slow. Is your data created by a SIS import? If so, it might be easier to get a list from your Student Information System than from Canvas using the API.

I generate an unduplicated count of students by getting a list of all the courses that are in the current term. Our system imports those into Canvas, so it's already part of my system and I don't need to fetch the list from Canvas. My system is separate from our SIS which doesn't know which courses are in Canvas.

I then grab a list of all the students in those courses from the SIS. There's a lot duplication, but it's pretty quick since it's all done locally -- no need to go across the internet like you would with the API.

Then I collate the data and generate the list, and because my system contains all the data that was imported into Canvas in the first place, it's all without making a single Canvas API call.

If you have to use Canvas to get the data, then one option is to use the Provisioning Report to generate the list. I explained how to combine the users, courses, and enrollments tables in Excel here: How to list teachers who have published/unpublished courses

That's specifically about finding teachers in courses, but it could easily be modified (change a filter) to find students.

If you don't need names and just want counts, then you could just use the enrollments table of the Provisioning Report. If you need a list of names but don't care about what courses they're in, you could use the enrollments and users tables of the report.

If you have to use the API, be sure to specify per_page=100 in the query string to minimize the number of calls. You may also want to store the results locally to make it faster in the future.

If you can get the data from the SIS, that's probably the easiest. If you only need it once a semester, the Provisioning Report method isn't too bad. If you need it often and can't get it from the SIS, then you're on the right track -- it's just slow.

[vicker]

Thanks, James. Very detailed explanation.

We do have a full list of users in SIS but that is too many. Using Provisioning Report is a good suggestion but that requires manually clicking through the admin interface. I think I will stick with my current solution at the moment.

[James]

Sometimes getting a good night's sleep gives you clarity of thought -- and yesterday was a day where I hadn't had much sleep but I went to bed early last night.

I forgot to mention that with the Provisioning Report, you can specify the Enrollment Term so you just get the information for a specific term. That assumes that you're putting courses into terms, which it sounds like you were. So if you go into the provisioning report and configure it, you can select just the term you want. The users table will select just the current users, but not which ones are students. The enrollment report will give you the roles so you can limit it to just students.

None of that changes that you would have to go through the web-interface, but if you are just after a count, you could pull just the enrollments.csv file into a spreadsheet and get a count of unique values.

The Provisioning Report is available through the API, but it because it takes time to generate the report, it will be a delayed process, but a lot less network traffic. Since you're spending time getting your list of students anyway, you're probably used to waiting. But we're talking a two-part process here, not a run it all at once one.

The Account Reports API is what you'll want to use.

List Available Reports gives you a list of the reports and what the parameters are.

     GET /api/v1/accounts/:account_id/reports

You'll want the Provisioning Report, and the relevant parameters are

• enrollment_term_id: The canvas id of the term of courses to report on
• users: Get the Provisioning file for users
• enrollments: Get the Provisioning file for enrollments

You can select other information if you like.

The other important thing is the name of the report, provisioning_csv, which you'll need later.

You can get the Canvas ID of the term using the List enrollment terms endpoint of the Enrollment Terms API

     GET /api/v1/accounts/:account_id/terms

For us, Fall 2015 has name:"Fall 2015", sis_term_id:"2015c", and id:6937. Make sure you use the id and not the sis_term_id

Putting those two together, you would make a call to the Start a Report endpoint of the Account Reports API

     POST /api/v1/accounts/:account_id/reports/:report

So, assuming you're using our enrollment id, you would make this API request, sending the indicated data:

POST /api/v1/accounts/:account_id/reports/provisioning_csv

{

     enrollment_term_id: 6937,

     users: true,

     enrollments: true

}

Edit: Although that's the information you need to send, you need to send it as a single string under the parameters key.

     parameters:enrollment_term_id=6937&users=1&enrollments=1

Once you submit that, you'll get a JSON return that has an ID in it. You need that id for later.

Now we wait for the report to finish. How long it takes depends on a lot of factors like how busy the system is and how many students you have.

You can check the Status of the Report and see how it's doing.

     GET /api/v1/accounts/:account_id/reports/:report/:id

The :report is provisioning_csv and the :id is the id returned when you created the report.

When the report is generated, you'll have a progress of 100 and there will be an extra section called attachment. If there isn't, then you wait longer and try again (unless there's an error).

The attachment information will contain an URL that you can use to download the file. Really important note -- the URL is not part of the API, do NOT send your Authorization: Bearer header with the request or it will fail. Just download the file from the supplied URL.

I don't know what SIS you're using, so I don't understand your statement about there being too many students. I've heard of cases where one group doesn't have access to the SIS directly and so they have to use Canvas to get the data or where you have to justify that you need the list of students and without it they won't give it to you, But If you, or someone you know, has direct access to the SIS, it should contain the enrollments and someone should be able to write some SQL code or perform similar filtering to get just the students for a current term.

Thankfully, I'm at a small college and have access to the SIS directly, so it's faster for me to just query it.

Anyway, good luck.