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

Groupings OU

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.

Since Moodle 1.8, the groups work has drifted somewhat, and The Open University hopes to do some further re-factoring during our current development phase with the Moodle community to get things back on track. To make the best use of limited time, we need to assess the current situation, where we want to go, and what are suitable self-contained tasks.

IMPORTANT: this 'specification' is not trying to compete with Enrique Castro's or Petr Skodak's (links below) - I hope we can reach a concensus.

(Also, still some gaps to fill!)

Relevant Links

Glossary/ key

The perhaps confusing term for a collection of groups, think groups for a particular purpose/activity, course categories. Do you have a better suggestion?
groupings is a bit confusing to any teacher i talk to (please consider that we are not native English speakers) 
so how about cluster / a set / unit / super-group ? or any other synonym for group ?
Not in a grouping
NIAG/ orphaned groups resulted from the ill-advised decision not to create a default grouping for a course during the upgrade to Moodle 1.8 (1.8.1).
Proposal to delete files and/or functions and/or code.
Proposal to move files and/or functions and/or code.
Files, functions or code that are either specific to the Open University, or currently only in ou-moodle.

Current specification

The current specification is based on Moodle 1.8.1 (also see 1.9 dev), and highlights where there are differences in ou-moodle 'r18' (OU VLE 1.5?)

Database schema

The current schema is below.

Petr's proposal

Proposed schema

The proposed database schema diagram above is currently in a state of change - the details below refer to the version from 8:27 18 July 2007 (Enrique). Petr has changed the table names to use plurals to make it more compatible with 1.7 or earlier.

This list is a way of clarifying Petr's specification - we're in agreement with most of it, but just finalising details! Existing columns in for example the 'group/groups' table remain (name, description, enrolmentkey... timemodified), except where indicated against a specific table below.

  1. Modify table: groups,
    • Add column/key: courseid int(10); import data from 'groups_courses_groups' or 'course'.
  2. No change to table: groups_members,
  3. Rename table: groups_groupings TO groupings,
    • Add column/key: courseid int(10); from 'groups_courses_groupings'.
    • Add column: exclusivegroups, flag?
    • Add column: maxgroupsize int(10).
    • Add column: timemodified int(10); set to 'now' or use 'timecreated'.
    • Note: column name=NULL indicates default course grouping (display name from language pack + course shortname).
  4. Rename table: groups_groupings_groups TO groupings_groups,
    • Columns/keys: groupingid, groupid.
  5. Delete table: groups_courses_groups.
  6. Delete table: groups_courses_groupings.
  7. Modify table: course,
    • Add column/key: groupingid, int(10); from 'groups_courses_groupings', default 0 "Any grouping/all groups".
  8. Modify table: course_modules,
    • Add column/key: groupingid, int(10), from 'groups_courses_groupings', default 0 "Any grouping/all groups" (as the OU and ecastro propose).
    • Add column: grouponly, flag?


This table describes a grouping, or collection of groups.
Field Type Default Info
id int(10) autoincrementing
name varchar(255) Short grouping name
description text NULL
timecreated int(10) 0 The time this grouping was first created
viewowngroup int(1) 1 Unused permission flag - DEL?
viewallgroupsmembers int(1) 0 Unused permission flag - DEL?
viewallgroupsactivities int(1) 0 Unused permission flag - DEL?
teachersgroupmark int(1) 0 Unused permission flag - DEL?
teachersgroupview int(1) 0 Unused permission flag - DEL?
teachersoverride int(1) 0 Unused permission flag - DEL?
teacherdeletable int(1) 0 Unused permission flag - DEL?


A pre-Moodle 1.8 table with some 1.8 changes, represents a group.
Field Type Default Info
id int(10) autoincrementing
name varchar(255) ' ' Short group name, unique to course (or site for site-wide group).
description text NULL
enrolmentkey varchar(50) Was mis-named/mis-used 'password' pre-Moodle 1.8.
lang varchar(30) en Override course/site language for this group.
theme varchar(50) Override course/site theme for this group.
picture int(10) 0 Flag to indicate presence of picture, should be int(1) ?
hidepicture int(1) 0 Flag to show/hide group picture.
timecreated int(10) 0 The time this group was first created.
timemodified int(10) 0 Time of last modification.


A pre-Moodle 1.8 table, connects a user to a group.
Field Type Default Info
id int(10) autoincrementing
groupid int(10) 0 Foreign key (table: groups)
userid int(10) 0 Foreign key (table: user)
timeadded int(10) 0 The time this user was first added to a group.


Connects a group to a course (redundant if all groups are in a grouping).
Field Type Default Info
id int(10) autoincrementing
courseid int(10) 0 Foreign key (table: course)
groupid int(10) 0 Foreign key (table: groups)


Connects a group to a course.
Field Type Default Info
id int(10) autoincrementing
courseid int(10) 0 Foreign key (table: course)
groupingid int(10) 0 Foreign key (table: groups_groupings)


Connects a group to a grouping.
Field Type Default Info
id int(10) autoincrementing
groupingid int(10) 0 Foreign key (table: groups_groupings)
groupid int(10) 0 Foreign key (table: groups)
timeadded int(10) 0 The time this group was first added to grouping


Pre-Moodle 1.8 table, OU additional column.
Field Type Default Info
id int(10) autoincrementing
course int(10) 0 Course ID, index (table: course)
groupmode int(4) 0
groupingid int(10) 0 OU-only, should be foreign key/index (table: groups_groupings)

Core group/grouping files, functions, constants

Folder: group

Mostly user-interface, except lib.php, version.php

  • assign.php - add/remove group members.
  • edit_form.php - formslib file.
  • edit.php - create/edit groups.
  • grouping_edit_form.php - formslib file.
  • grouping.php
  • index.php
  • lib.php - includes group/lib/* files
  • printgrouping.php
  • version.php - Moodle component version.

Folder: group/db

db/dbbasicgrouplib.php MV:

  • groups_db_get_user, groups_db_get_groups, groups_db_get_members, groups_get_member_users, groups_db_get_groups_for_user, groups_db_get_group_settings,
  • groups_db_users_in_common_group, groups_db_group_exists, groups_db_group_matches, groups_db_group_name_exists, groups_db_is_member, groups_db_group_belongs_to_course,
  • groups_db_create_group, groups_db_upgrade_group, groups_db_add_member, groups_db_set_group_settings, groups_db_remove_member, groups_db_delete_group, groups_db_set_group_modified,
  • groups_members_from_sql, groups_members_join_sql, groups_members_where_sql,

db/dbcleanup.php DEL:

  • groups_remove_user_from_all_groups, groups_remove_all_group_members, groups_remove_all_groups, groups_cleanup_groups,

db/dbcourselib.php DEL:

  • groups_db_get_forced_grouping, groups__db_set_forced_grouping,

db/dbgroupinglib.php MV:

  • groups_db_get_groupings, groups_db_get_groups_in_grouping, groups_db_get_groupings_for_group, groups_db_get_grouping_settings, groups_db_get_grouping_for_coursemodule,
  • groups_db_grouping_exists, groups_db_belongs_to_any_grouping, groups_db_belongs_to_grouping, groups_db_is_member_of_some_group_in_grouping, groups_db_grouping_belongs_to_course,
  • groups_db_create_grouping, groups_db_add_group_to_grouping, groups_db_set_grouping_settings, groups_db_set_grouping_for_coursemodule, groups_db_remove_group_from_grouping, groups_db_delete_grouping,

db/dbmodulelib.php DEL/ MV:

  • groups___db_m_get_groupingid, groups_db_m_set_groupingid, groups_db_m_get_group,

db/dbsetup.php DEL:

  • groups_create_database_tables, groups_db_copy_moodle_group_to_imsgroup,

db/install.xml (XMLDB database schema)


  • install_group_db, undo_groupings, upgrade_group_db, groups_transfer_db, groups_drop_keys_indexes_db, groups_revert_db, xmldb_group_upgrade,

Folder: group/lib

lib/automaticgroupinglib.php DEL:

  • groups_seed_random_number_generator, groups_create_automatic_grouping, groups_distribute_in_random_sets, groups_random_list, groups_last_element_in_set,


  • groups_get_groups, groups_get_members, groups_get_member_records, groups_get_groups_for_user, groups_get_all_groups_for_user, groups_get_groups_for_current_user,
  • groups_get_group_settings, groups_get_group_image_path, groups_get_group_name, groups_get_users_not_in_group,
  • groups_users_in_common_group, groups_group_exists, groups_group_matches, groups_group_name_exists, groups_is_member, groups_group_belongs_to_course, groups_is_member_of_group_in_course, groups_set_default_group_settings,
  • groups_create_group, groups_restore_group, groups_set_group_settings, groups_add_member, groups_restore_member, groups_delete_group, groups_remove_member, groups_remove_all_members, groups_update_group,

lib/clientlib.js (Javascript):

  • function UpdatableGroupsCombo(..), success: function(o), failure: function(o), UpdatableGroupsCombo.prototype.refreshGroups = function(..)
  • function UpdatableMembersCombo(..), success: function(o), failure: function(o), UpdatableMembersCombo.prototype.refreshMembers = function(..)
  • var createLoaderImg = function(..), var removeLoaderImgs = function(..)

lib/courselib.php DEL:

  • groups_get_forced_grouping, groups_set_forced_grouping, groups_course_print_group_selector,


  • groups_get_groupings, groups_get_grouping_records, groups_get_groups_in_grouping, groups_get_groups_in_grouping_records, groups_get_groupings_for_group,
  • groups_get_grouping_settings, groups_set_grouping_settings, groups_get_grouping_name, groups_get_groups_for_user_in_grouping,
  • groups_get_groups_not_in_grouping, groups_get_groups_not_in_any_grouping, groups_get_users_not_in_any_group_in_grouping,
  • groups_user_is_in_multiple_groups, groups_set_default_grouping_settings, groups_get_grouping_for_coursemodule,
  • groups_grouping_exists, groups_grouping_matches, groups_belongs_to_grouping, groups_is_member_of_some_group_in_grouping, groups_grouping_belongs_to_course,
  • groups_create_grouping, groups_add_group_to_grouping, groups_set_grouping_for_coursemodule, groups_update_grouping, groups_remove_group_from_grouping, groups_delete_grouping, groups_delete_all_groupings,


  • groups_get_group_by_name, get_groups, user_group, ismember, get_group_users, add_user_to_group, mygroupid, groupmode,
  • set_current_group, get_current_group, get_and_set_current_group, setup_and_print_groups,
  • D oldgroups_print_user_group_info, groups_get_group, groups_get_groups_names, groups_get_groups_users,
  • OU ou_is_old_group_dataload, ou_is_auto_group, ou_auto_groups_visible, ou_remove_auto_groups, ou_user_remove_auto_groups.


  • D groups_m_uses_groups, groups_m_print_group_selector,
  • groups_m_get_selected_group, groups_m_get_groups_for_user, groups_m_get_my_group,
  • D groups_m_has_permission, groups_m_get_members_with_permission,
  • groups_m_get_group, groups_m_get_groups, groups_m_get_members, groups_m_get_and_set_current, groups_m_get_current, groups_m_setup_and_print,


  • groups_count_group_members, groups_count_groups_in_grouping,
  • groups_get_user_displayname, groups_get_group_displayname, groups_get_grouping_displayname,
  • (D) groups_users_to_userids, groups_userids_to_user_names, groups_groups_to_groupids, groups_groupids_to_groups, groups_groupids_to_group_names,
  • groups_compare_name, D groups_groupingids_to_groupings, groups_get_user, groups_get_course_info, groups_get_course,
  • groups_group_edit_url, groups_grouping_edit_url, groups_members_add_url, groups_home_url, groups_param_action,

Folder: group/simpletest


  • __construct, test_get_user, test_get_course_info, test_create_group, test_group_matches, test_add_member, test_remove_member, test_delete_group.


  • __construct, __destruct, setUp, tearDown, test_create_grouping, test_groups_grouping_matches, test_add_group_to_grouping, test_remove_group_from_grouping, test_delete_grouping.



  • backup_groups_info, backup_groups_members_info, backup_groupings_info, backup_groupids_info.


  • backup_ids table reference: "groups".
  • restore_read_xml_groups, restore_read_xml_groupings,
  • restore_create_groups, restore_create_groups_members, restore_create_groupings, restore_create_groupings_groups.




  • print_group_picture, update_group_button, update_groups_button, print_group_menu

Groupings for course modules

These are currently only in ou-moodle. We now have grouping support in these course modules: data, forum, quiz (reports), wiki. For brevity, only mod/data is shown below. (There may be ommissions!)


  • function set_coursemodule_grouping.


  • function standard_coursemodule_elements($supportsgroups=true, $supportsgroupings=false)


  • <TABLE NAME="course_modules" ...>
  • ... <FIELD NAME="groupingid" TYPE="int" LENGTH="10" NOTNULL="true" ...DEFAULT="0" ...PREVIOUS="groupmode"/> ...


  • ... $table = new XMLDBTable('course_modules');
  • $field = new XMLDBField('groupingid');
  • ... add_field($table, $field); ...


  • class MoodleQuickForm_modgrouping extends MoodleQuickForm_select.


  • ... MoodleQuickForm::registerElementType('modgrouping' ...)


  • $this->standard_coursemodule_elements(true, true);

... mod/data/view.php

  • groups_m_setup_and_print($cm ...); ...

Future requirements


  1. Improve the confidence of Martin D, Petr Skodak and the community in groups.
  2. Maintain backwards compatibility with 1.8 and 1.8.1 - so no significant removal of high-level functionality (in time we want groupings, site-wide groups etc - these are additions).
  3. Make upgrade, backup and restore (from 1.8, 1.7, 1.6 etc.) more robust.
  4. Make database access more efficient - fewer queries per page.
  5. Simplification of database schema - but not at the expense of future-proofing and flexibility.
  6. Simplification of group libraries, so code is easier to maintain and use.
  7. Simplification/ improvement to group management user interface - "Not in a grouping" (NIAG)/ orphaned groups will go!
  8. Add groupings support for course modules - already in ou-moodle.
  9. Investigate synchronisation with enrollments, and fix group import.
  10. Minimise differences between core Moodle and ou-moodle.

Proposed tasks

(Order to be discussed.)

  1. Create additional (simpletest) unit tests - how many do we have time for? To ensure that subsequent steps don't break things!
  2. Delete unused/ unfinished code, functions and files from the libraries (see DEL above). [Simplify]
  3. Merge some library fixes and module-grouping specific code from OU to core Moodle. [OU diff]
  4. Move code from db/db*lib.php files to lib/*lib.php files - so groups_db_create_group etc. will go, just leaving groups_create_group. General refactor of code and PHP doc-comments. [Simplify]
  5. Rewrite groups_get_groups functions etc. so that they return arrays of group objects (group ID used as key), not groupids. Delete inefficient groups_groupids_to_groups etc. [Efficiency]
  6. New upgrade, creating default grouping for a course - NIAG will go/ DB schema changes (stabilisation).
  7. (OU-specific: modify group dataload.)


Proposed process

  • Discuss/ modify this specification until a concensus is reached.
  • One meta/tracking-bug, and a 'sub-task' bug per task above.
  • One or more patches per task, to be reviewed by Martin D and/or Petr Skodak and others, committed by Martin, Petr, NDF or other.
  • Modifications on core Moodle HEAD.

Groups optional backup/restore

Related Moodle bug MDL-2674 | Open University bug 3132.

The Open University needs the option to not backup (and/or not restore) groups, and possibly groupings for our course "roll-forward". There is also a longstanding Moodle bug, MDL-2674, which hints at some of the challenges regarding restoring group activities, without groups. I was looking at giving the option only on backup to backup or not groups and groupings. As restore also needs changing, this was getting quite big and ambitious, so I intend scaling back, not changing the backup and only giving the user an option on restore.

Comments welcome!


Primarily OU-moodle/OUVLE 2.0 - so a tight time frame. Secondarily, core Moodle (bug MDL-2674) HEAD/2.0 only - we want to keep our code as close as possible to core.


  1. The user (Service-Delivery at OU, teachers at other institutions, etc.) has no option about backing up groups and groupings - backup stays the same.
  2. Give the user the option to restore groups, and groupings if groupings are enabled for the target site, none/groupingsonly/groupsgroupings (all). Default, all.
  3. Groupings may be restored without groups (Service-Delivery think this is most useful at present) - so on restore there will be empty groupings.
  4. Do not give the use the option to restore group files, yes/no - this does not need to be a separate option - the only files are group images.
  5. If groups are not to be restored, group activities will become none-group activities (groupmode of course: no change; groupmode of course mod: no change ?; group ID of mod: 0) Content needs concatenating from different groups - scary!
  6. Grouping activities retain their grouping ID - so on backup there may be activities that are inaccessible to students until the grouping contains groups, or the activity settings are edited.
  7. OU AACS/auto-created tutor groups are handled in the same way as any other group.
  8. Backup can be modified later to give more flexibility (this supposes a flag in the moodle.xml file - MOODLE_BACKUP - INFO - DETAILS - GROUPS, set to one of [none,groupsonly,groupingsonly,groupsgroupings]).


This is getting ambitious, and all the group activity backup issues have not been resolved. Now looking at giving user options on restore instead of backup.

See also