If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Groupings and Groups

From MoodleDocs
Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.

This page was part of a debate about how these features should be implemented. If you want to know what was finally implemented, Groups is the best page to read.

Improving the Groups design in Moodle

Summary of problems:

  • Groupings enabled in 1.8 but not used for anything productive
  • Can not define groupings at site level
  • Groupings not implemented in modules
  • Concept of orphaned groups
  • Missing enrolment option
  • Not integrated into Moodle core
  • Unfinished and partially broken code

Required features

The groupings/groups infrastructure should be finished to allow these features:

  • Organize groups into groupings. Groupings are sets of groups related in use or functional logic. Use of groupings should be optional, not mandatory (preserve old-style, pre-1.8, groups usage). A group may belong to several groupings. Real use is easier to setup if this flexibility is allowed.
This is done as by 1.8, but UI imposes the extra requirement of each group to belong to a single grouping. Groupings are not used for any of the logical purposes (see below)
  • Use different sets of groups (groupings) in each individual activity instance in a course. Activities can declare a grouping to use. This means that when that particular activity is set as visible/separate groups, the particular groups used are those belonging to the declared grouping. Hence, we can have simultaneous activities where users are distributed according to different criteria, activities & resources may be targeted to different audiences.
  • Group-based access to activities or resources. Only members of groups within GroupingX may see a resource or perform an activity set to use Separate Groups. Users not belonging to any group (in the given grouping) cannot access the activity instance.
This is different to and cannot be managed by Roles & Permissions. Teachers can manage groups but teachers cannot create/delete roles. It would be impossible for large site like a university to manage hundreds or thousands of groups as course-based roles: arbitrary roles from each course would polute the roles-namespace ad infinitum.
  • Flexible and easy interface for adding users to groups. Simulation of subgroups: being able to easily select users that are members of a given group and split them into several other groups, while maintaining membership to the first one. Batch creation of multiple groups in a grouping and rules for assigning users to them (each next n users, n random users etc.). A way for users to self-enrol into groups of teacher-selected groupings should be added.
  • Display restricted lists of users selected according to membership to specified groupings/groups. In any page presenting lists of users (such as those of Participants list, Assign roles or Group management) there should be possible for the teacher/user to limit the listing to only those users that are members of a given grouping or group, thus allowing the display of only selected users as “potential users” in such lists.
  • Define global groups/groupings. Only Admins can create site-wide global groups, organized into groupings for convenience. These global groups may be used for:
    • Controlling dinamically the enrolment of group-members into courses.
    • Restricting the display of users in lists of available or potential users
    • As any other local course-defined group for activities and resources
The list of site-wide global groups may be quite large. Teachers may decide optionally if they use or not global groups at course level; They may "import" or "use" selected groups or groupings inti the course context from the site-wide level.

Putting groupings to work needs some additional work at module level, and small fixing of groups/groupings libraries --Enrique Castro 19:12, 08 July 2007

Examples & use cases

Activities & Resources targeted to different audiences:

We have a course composed of two sections (Grouping Sections: Section01, Section02 each with a teacher) and the same users distributed into Lab groups (Grouping Labs: Lab01. Lab02, Lab03 maybe with assistants as non-editing teachers). You may set the course as “separate groups” using the Sections criterium, and have a separate groups forum for class discussions. Simultaneously you may have a Wiki using Lab grouping to collaboratively construct the laboratory reports within each three Lab groups (so, different and unrelated to Sections groups).

Group-based content delivery:

The teachers want to add special content for lagging students but in way that do not embarrass them, privately, not available for the rest of users. A grouping Special may be defined containing just one group (with students of any section) or several groups of “special” students, one from each section/lab. This may be used to get private content by each teacher in a course. Let say professorA teaches Section1 theory and Lab2 practices. He may set up a grouping called “ProfA” comprising just those two groups (hence, convenience of a group been associated to several groupings).

Defining subgroups:

You participate as a teacher in a three-sections course. You are in charge of Section01. The course is configured to use grouping Sections groups (Section01, Section02, Section03) as separate groups. As part of your teaching you want to separate students into 5-members groups to hold discussions in a forum. You create a grouping “Discussions” as exclusive-membership, containing 6 groups (Diss01-Diss06). While adding students to each DissN group you want that only users of Section01 are listed as potential users and that when added to a group, users disappear of the “potential” listing.

Using global groups:

You are a moodle admin at a university. You define a global group "Foreign Students" and want that all members of that group become enroled into "University primer for foreign students" course, in addition to their regular courses. You are a teacher in a course. Foreign students need special help due to language, you decide to create extra content available only for them: set some resource to separate groups using a custom grouping containing only "Foreign Students" group. You use "News" forum in separate groups mode to send messages to each of you course sections. Those foreigners require special messages, you add "Foreign students" as another group into sections grouping.

Database structure

As of current HEAD (1.9) there are six tables devoted to groups. One each for definitions of groups and groupings , two more for taking care of membership, users into groups and groups into groupings. Two other tables keep the association of courses and groups or groupings. This arrangement is the most flexible as allows both groups existing without being part of a grouping and global groups/and groupings that may be associated to several independent courses. The separation of groups_courses_groups and groups_courses_groupings is imposed by the simultaneous requirements of

  • allowing groups to exist and be used without being members of a grouping (i.e. traditional way pre-1.8)


  • the optional use of global groupings/groups locally at course level.

If any of these two requirements is dropped a simpler schema is possible.


This database scheme allows to search for course groups or user groups in a single query, as in pre-1.8 moodle. Any required group-data may be obtained by either a join of usually just two tables, or two separate queries, one for grouping and other for groups in grouping.

To make possible to associate a grouping to a module instance a “groupingid” field must be added to the course_modules table. In the same way course table declare a “groupingid” field to hold the default grouping to use in visible/separate group modes. In both cases, there should be no obligation to declare or use a grouping at any level. A default value groupingid=0 must be used in both tables. Groupings/groups managing functions must understand groupingid=0 as meaning to use ALL groups belonging to a course in a flat list (default function in pre-1.8 versions)

Changes into current tables

Now the table groups_groupings include a series of fields intended for controlling access permissions to a group (student/teacher view, grading etc.) These should be eliminated and managed through the regular permissions infrastructure.

Conversely, some other fields should be added to allow more convenient use of groups by teachers.

  • editable - to allow users to edit or now their own group
  • exclusive - to allow multiple-group membership within a grouping or impose single-group membership: a user can be member of just one an d only one group of this grouping.
  • publish - teacher decides when a grouping is enabled to be used in the course (important if group self-selection is to be managed)
  • sizelimit - number of places for groups in this grouping (important if group self-selection is to be managed)

Putting these as grouping attributes rather than individual groups makes coding easier because then all groups in a grouping are expected to behave in the same way and can be treated alike.

Alternative, Reduced schemes

If the above requirements are not be met simultaneously, simpler schemes for the database tables are For instance, if global groups are always available at course level (or no global groups at all) then a courseid field may be introduced into groups and groups_groupings permanently associating a courseid with any group or grouping. Courseid=0 would label global groups. Tables groups_courses_groups and groups_courses_groupings would be no longer needed. Special logic should be introduced into functions in groups libraries to manage this exception, global groups.


On the other hand, if “free” groups are dropped and all groups are required to belong to a grouping another reduced scheme with only four tables has been proposed by Petr Skodak. However, adopting this scheme would implicate to re-write radically groups/groupings libraries.

Backward compatibility with pre-1.8 groups

Before version 1.8 all groups within a course were managed in a single flat list, without groupings. Multiple-group membership was introduced in version 1.6. To maintain compatibility we must not insist on having each group to belong to a grouping. Groupings should be viewed as an optional feature used only if needed. When the teaching requires them, not imposed. The main actors in the groups/grouping dichotomy should be groups, not groupings: the teacher should create groups at first, and only if needed those groups could be placed into gropings.

Actually, making mandatory to put each group in a grouping creates some problems:

  • A "default grouping" must be created whenever groups are to be used
    • Teachers using only a flat list of groups as course sections with separate groups mode must not be compelled to create a "default grouping" just to hold them.
    • This requirement is also a problem when restoring groups from old versions: an exception must be added to create a grouping non-existent in the backup zip.
  • Deleting a grouping will create "orphan groups" that needs exceptional pseudo-grouping to manage them.

If groups are main actors, not groupings, the concept or necessity of "orphan groups" pseudo-grouping can ve avoided at all.

When groupings are created and populated with groups the API functions must return/operate on a flat list of ALL course-associated groups if no groupingid is specified or groupingid=0. Legacy group functions must be modified to operate by default on groups of the “currentgrouping” or all groups if no groupingid is specified or groupingid=0.

Activities declare a grouping to use groups

The configuration form for each activity includes a setting for groupmode: “no groups”, “visible groups” or “separate groups”. If the activity (or resource) is configured in any of the later two (visible/separate) then a new option “Use grouping” must be set. This parameter controls the particular set of groups to be used within the activity.

Module instances keep the groupingid parameter in course_modules table. This parameter should be added to "common module settings" to be managed by all modules in the same way as groupmode and visibility settings.

All calls to groups/groupings-managing functions within a module code must ensure to pass the groupingid parameter (0 o null meaning no groupings i.e.: all groups).

Group-based content delivery

If a module instance is set to use separate groups then ONLY those users that are members of a group included in the grouping used by that particular module instance may access to the module content (either resource or activity): “non-grouped” users are excluded. This should be implemented both for Activity modules and Resource module. Visibility and accessibility of module instances should be checked before printing in UI. Activities and resources at which the user access is forbidden must not be showed to the user.

Global Groups

Separate global and course groupings, add global tag to group/grouping table. Each global group/grouping has world wide unique identifier. Benefits:

  • allows implementation of access control – local course groupings editable by course teachers, special capability in CONTEXT_SYSTEM for managing of global groupings
  • easier backup/restore implementation – local groupings (+groups) always backed up, global groupings handled differently

This separation would make the coding much easier because the two parts would be independent - local grouping would not be breaking the course separation rule (anything outside of course breaks normal backup/restore).

Local groups/groupings would be attached to exactly one course, global groups/grouping could be used in many courses at the same time. These limitations are not built into the database schema but imposed by UI: all groups created within a course are automatically associated with that course, only global groups displayed in import page.

The global tag must be associated with a manageglobalgroups capability checked by groups-API function to enforce that only admins and alike can modify global groups/groupings.

Define global groups/groupings.

Only Admins and users with moodle/site:manageglobalgroups can create site-wide global groups and groupings. A UI must be provided in Site Administration to manage those groups.

Group-based enrolment

Global groupings can partially replace metacourses in some scenarios. They should support synchronization of enrolments based on group membership. Global groupings should allow:

  • automatic or manual sync of enrolments – reuse code from metacourses
  • setting of default sync role id with possible exception for teachers, tutors, etc.
  • import/export of grouping definitions
  • mapping of global groupings during course restore (course groupings always backed/restored)

Use selected global groups in local course-based activities

Global groups should not be available as default within a course group UI. That only contributes to polute namespace and confuse teachers. Courses may “import” selected global groups to use in local course-based activities. A UI must be provided for importing either whole groupings (with their groups) or individual global groups to course context. "Importing" may consists merely in associating a particular groups/grouping with the course (a new entry in groups_groupings_courses or groups_courses table).

Imported groups and groupings must be locked (no users or groups added/removed at course level). Imported groups may be added to local groupings just as any regular, local, group. Then those activities are open for users that happen to be enroled in the course and are members of a site-defined group: a two way checking. Functions in groups/groupings API must enforce this double checking by reading the "global" flag.

Groups/grouping management UI at course level

The user interface must emphasize the Groups management and add Groupings as an option in a separate, secondary, tab. Additional tabs may be added for extra functions like batch creation of groups and import of global groups/groupings

Groups Tab

Used to add groups to the course. The classic three pane page has proven very convenient and powerful to manage groups. There is no reason to change it radically, but improve its usability. This UI may be a problem in courses with large number of groupings and groups (as used by teachers that work with several small teams simultaneously). The proposed changes are:

  • Show only people in group: A selector to limit the "potential users" list (leftmost pane) to those users that happens to be members of a given group. In this way those users, and only those, can be distributed into other groups that become functionally subgroups of the former.
  • Show only groups in: A selector to only display groups of a particular grouping in the central pane, rather than all groups associated with the course. All groups created while this selector is pointing to a specific grouping are automatically added to that grouping
  • Exclusive groupings: Code logic should be adapted to read and enforce "exclusive" membership parameter for the grouping in use. If set, users may be members of just a unique group in the grouping. Thus, when users are assigned to a group in this grouping they are eliminated from the "potential users" list (pre-1.6 behavior). This facilitates enormously to distribute users.

This is an example of the proposed UI


An essential point is that groups can be created without creating previously a grouping, and groups are un-associated to any grouping by default.

Grouping Tab

Used to manage groupings (create/edit/delete, adding/removing groups to grouping) A UI similar to that used to manage quiz question categories could be used. Attributes of each grouping could be set by clicking on open/close eye icon meaning yes/no.

This is an example of the proposed Groupings Tab


For global groupings a non-editable rows would be added to the table.

Groupings are populated with groups using a two pane page to pass groups from "potential" to "used" boxes. groups-UI-addgroups01.png

Global Groups

This tab displays a list of Global groupings and groups allows to associate any of them with the course

Capabilities and Permissions

A new permission is needed at site level

  • moodle/site:manageglobalgroups – user can create/edit/delete global groups

In addition, a new context moodle/group might be added, depending on the granularity of the desired behavior

  • moodle/group:viewallgroups - view other groups in the same grouping
  • moodle/group:viewgroupinggroups – view other groups in the same grouping
  • moodle/group:editowngroup – edit profile and image for groups the user is member of

In a future each user may have specific roles within a group, for instance group leader (enroling other users in the group), submitting member (if groups are used as small teams submitting assignments and alike) etc.

  • moodle/group:canmanagegroup – user can enrol and unenrol other users in this group
  • moodle/group:cansubmit – user can submit in the name of all members of the group

Development Tasks and Tracking

Using the current database structure most of these features are independent of each other and can be added independently and separately. In particular adding support for Activity level groupings and Group-based content delivery would be very easy and straightforward. We at ULPGC already have a working implementation of these two features and UI. Please see issue [ MDL-10383].

Adding support for Global Groups would require extra modification of the API to make functions to check and manage separately "exception" (flagged) global groups.

Other issues in tracker related to groups/groupings are [ MDL-7380] - Meta issue relating several pending tasks related to groups/groupings [ MDL-8735] - Missing a way to add groupings to activities

Development Subtasks

This is a possible fine grained subdivision into independent subtasks

  1. Make Activities to use Groupings
    1. Add "Use Grouping" support in config form for all modules
    2. Adapt code in each module to set, read and use grouping when in groupmode visible/separate
  2. Group-based content delivery
    1. group based access checking within each module (beginning of view.php)
    2. visibility checking in course page
  3. Refactor groups UI to use formslib library
    1. Groups page
    2. Groupings page
    3. Extra features: batch group creation, random assignment of users to groups
    4. Group self-selection by users
  4. Add support for Global groupings/groups
    1. Design a working scheme for backup/restore of global groups/groupings
    2. Add a UI for site-level managements of groups/groupings (reuse course level one?)
    3. Global groups-based metacourses: enrolement controlled by global group membership
    4. Add a UI for importing global-groups to course level
    5. Add global-group selection into user lists in several pages

For 1.9 I see as feasible to implement tasks 1.1 & 1.2, 2.1 and 3.1, 3.2. With this Groupings would have a purpose and function in Moodle and teachers may see new opportunities to organize virtual teaching. The point 2.2 is trivial but not essential. Since it involves repeated new and additional queries to DB in course page, this feature could wait until its scalability it's tested.

Other tasks may wait for 2.0.

See also