Using API to Create Groups Based on Number of Students and Have Unique Names

[agatten1]

Hi all - I posted this in the general question forum but realized this group might be a better place. Apologies if this was wrong to do. I'm not a developer per se, but I'm an instructional designer at a relatively large school. I am relatively new to tapping into Canvas APIs, but I think I am getting the hang of it. I use Postman primarily.

I am looking to create groups in sections of courses prior to course migration and I am running into two problems/questions I can't find answers to.

1) I would use the create group category call, but it generates groups that all have the same name as the group category. Some courses have groups with unique names (eg the group will be titled an assigned topic for the students, which will be different than the category title which might just be "Project Name"). So I was thinking I could create a group category with no groups, then use a different call to create the individual groups, and then after, run a call to assign unassigned members, which seems like it might work. Does that sound right?

2) The second problem I am having that I don't know how to resolve is that Canvas allows you to create however many groups are needed in order for there to be 4 students per group, for example (the option says "Split students into groups with X number of students per group"). Some of our courses use this option, and I can't see a way to get that to work through the API. When creating a group category, the parameter group_limit says "Limit the maximum number of users in each group (Course Only). Requires self signup." But I want it to be randomized and automatic when the category is created in the course, not self sign-up, and I want it to generate however many groups are needed for that section for there to be 4 students in each group. Since Canvas can do it, I'd assume there would be a way to do it through the API, but I can't find documentation on it.

I saw that there is an option to export groups from an existing course and then import them, but since I am working from user-less templates for the copy process, it exports a blank data sheet.

[agatten1]

I am looking to create groups in sections of courses prior to course migration and I am running into two problems/questions I can't find answers to.

1) I would use the create group category call, but it generates groups that all have the same name as the group category. Some courses have groups with unique names (eg the group will be titled an assigned topic for the students, which will be different than the category title which might just be "Project Name"). So I was thinking I could create a group category with no groups, then use a different call to create the individual groups, and then after, run a call to assign unassigned members, which seems like it might work. Does that sound right?

2) The second problem I am having that I don't know how to resolve is that Canvas allows you to create however many groups are needed in order for there to be 4 students per group, for example (the option says "Split students into groups with X number of students per group"). Some of our courses use this option, and I can't see a way to get that to work through the API. When creating a group category, the parameter group_limit says "Limit the maximum number of users in each group (Course Only). Requires self signup." But I want it to be randomized and automatic when the category is created in the course, not self sign-up, and I want it to generate however many groups are needed for that section for there to be 4 students in each group. Since Canvas can do it, I'd assume there would be a way to do it through the API, but I can't find documentation on it.

I saw that there is an option to export groups from an existing course and then import them, but since I am working from user-less templates for the copy process, it exports a blank data sheet.

[James]

@agatten1 

Can I get a little clarification on "I am looking to create groups in sections of course prior to course migration?" In my experience, copying a course to another one does not copy existing groups. I copied a course with two different group sets and neither of them copied over to the new course. However, I did have a single "Project Groups" group set with no groups under it. If I copy a course with no group sets, then the copy has a "Groups" tab and a message about student groups being useful.

This lack of copying makes some sense because students are in the groups and the enrollments are not copied. The calls to automatically assign students to groups won't be applicable until there are students in the course as it wouldn't know how many groups to create.

What it seems like you're trying to do is automatically create groups in an existing course. This may mean that you need to create the course, add the students, and then run the group creation process.

I would use the Group Categories and Groups APIs.

If I'm understanding what you're trying to do properly, then this is what you will need to do for each course that has students in it (not the empty shell). This sounds like what you're describing. I did walk through the steps to verify that this works.

1. Create a group category with a name and nothing else. This will create a group category (group set) with no groups under it. Make a note of the id in the response because this will become the group_category_id for other calls.
2. Create a group and specify any unique names that you need. Use the id from step 1 as the group_category_id for this call. You will need to create the name so it is appropriate to the course. You may also need to incorporate a group number as part of the name so that you can distinguish the groups. If you are going to manually assign members, then note the id from the response because this will become the group_id for the next step. Repeat this step for each group that you need.
3. Assign unassigned members will take distribute the students across the groups that you have created. Alternatively, if you want to assign people on your own, you would need to Create a membership using the group_id from step 2.

As for the second question, not everything that Canvas does is available through the API. If you want to have Canvas automatically create groups, then you are forced to live with group names that match the group set name with a number at the end. There is a create_group_count parameter when you create the group set.

Instead, what you need to do is to do the calculation on your own to determine the number of groups. The calculations vary based on whether you want a minimum of 4 students, a maximum of 4 students, or approximately 4 students in each group. There is no option for exactly 4 students per group (3 out of 4 sample sizes don't allow for exactly 4).

If you are willing to accept the Canvas generated names, then you can specify the number of groups to get a minimum of 4 students per group (assuming there are at least 4 students) or you can specify the limit on the number of students to get a maximum of 4.

Manually, generating a minimum of 4 involves something like this: number of groups = math.max(1,math.floor(number of students / 4)). You could have up to 7 students in one group this way.

Generating it so there is a maximum of 4 involves a calculation like: number of groups = math.ceil(number of students/4). Canvas tries to balance the groups so that 9 students would get groups of 3, 3, 3 rather than 4, 4, 1. The requirement is that it cannot exceed 4 in a group.

If you want about 4, but don't care if some groups go over a little, then you could use: number of groups = math.max(1,math.round(number of students/4)). Provided there are at least 3 students in the class, you never get more than 5 or less than 3 in a group this way. A group with 5 students occurs 1 time out of 4 while groups with 3 occur half the time.

Replace the math calculations by the appropriate function for whatever programming language you're using.

The number of groups you calculate manually factors into step 2 of the 3 step process above.

Note that all of this needs done in the Canvas course where there are students, not in a shell before a content migration. If your institution allows add/drops, it would be best to wait until close to the time when the groups are set to begin to make sure they are as accurate as they can (groups created early might experience students dropping so a group ends up with just one person).

[agatten1]

Thanks very much for your detailed reply. Essentially, what I'm trying to resolve is exactly what you pointed out - groups don't copy during the migration process. We have template courses that get copied to 10-20 live sections that the instructors then use in an online program. When there are groups, when we do the course migration process, the groups don't copy and don't link to the assignment, so we have to manually create the groups in all of the live courses before the course migration process so that the assignments are linked to the correct group when they finish importing, which is tedious. I was looking for ways to shorten the time spent on this by creating groups in the target courses through the API (rather than by hand). However, they have to match how they're set up in the template courses exactly.

It sounds like my instincts were right for the first case - thank you! In the second case, I'm using Postman rather than a programming language. I'll have to see if there's a way to do it that way.

[James]

Not sure why it has to be exactly the same (seems like the number of groups would vary depending on enrollment count), but you're making a great case for using a programming language. You could fetch the current group categories and groups information from the template course and then duplicate that in the live courses. You could even store ID numbers in a database so that you could later combine results from the various courses back into one report.

I don't use Postman, so I don't know what it's capable of and whether you can perform multiple GET statements and then turn that into multiple POST / PUT statements and save the data somewhere for future reference.

If you don't want to match off of IDs, then you could match off of names, provided the instructor doesn't change them.

[melodyc_lam]

If you're using Postman, you can use a Collections Runner. https://learning.postman.com/docs/running-collections/intro-to-collection-runs/

If you know some JS you can also write a script directly in Postman. https://learning.postman.com/docs/writing-scripts/intro-to-scripts/

I highly recommend writing a script for this, though, like James suggests.

Good luck!

[AndrewYardy]

Hi James,

What permissions are required to create a group category? 

[James]

@AndrewYardy 

The Canvas Course Role Permissions document lists the permissions needed.

Under Assignments and Quizzes - add, it says "Allows user to add assignment groups in a course."

If you're looking to create groups of students, see the Manage Groups - add / delete / manage permissions.

[AndrewYardy]

Many thanks @James.

[AndrewYardy]

Sorry to clarify,  I want to set the group category using API calls. 

Does Scope: url:POST|/api/v1/accounts/:account_id/group_categories

accounts / account id mean I need to be an account admin to make the call?

I am getting 

401
{'errors': [{'message': 'Invalid access token.'}]} when making the call to...

url = f"{canvas_host}api/v1/courses/{course_id}/group_categories"

Thank you.

[James]

@AndrewYardy 

Sorry I missed what you were asking. I've never heard of anyone wanting to make account-level group categories, so I didn't think of that. I always do things at the course level. We create courses for communities rather than putting them into group categories. As a teacher, I only use group categories for assignments. I also wasn't sure (I read this at 2 am when I needed to be sleeping) whether you were talking about assignment groups or user groups.

If you're using the account level, then you need to look at the Canvas Account Role Permissions instead.

There is a Manage Groups - add / delete /manage set of permissions for the account as well as for the course. The Groups - add allows you to create account groups.

If you're a Canvas Admin, then you should have the ability to create group categories at the account level. If you're not an admin, you should make sure that whatever role you have has that permission.

Permissions are sometimes related to each other and I stopped looking through the documentation as soon as I found the obvious answer. There might be something else that needs set.

I'm still a little confused, though, as you set the scope to be the account group categories, but then you're calling the course group categories with your API call. If you're enabling an API key and setting the scope to the account level and then calling it for the course, you won't be authorized. You would need to set that scope under group categories for the whichever API you're actually using.