Showing results for 
Show  only  | Search instead for 
Did you mean: 
New Member

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

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.

0 Kudos
4 Replies
Community Champion


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).

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.

Community Champion

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.

If you're using Postman, you can use a Collections Runner.

If you know some JS you can also write a script directly in Postman.

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

Good luck!