Obsolete:Groupings OU

IMPORTANT: This page was part of a debate about how these features should be implemented. If you want to know what was finally implemented, Development: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

• Enrique Castro group specification and bug MDL-10383 (Uni of Las Palmas ULPGC).
• Petr Skodak group specification.
• Old Moodle meta bug MDL-7380.
• Forum discussion: Possible groups features, J.White, June-November 2006.
• How groups work in Moodle, J.White, old.
• Groups documentation for module developers, J.White, old.
• JISC JoinIn project: Sharing Groups between LAMS and Moodle, December 2006, original collaboration by the Open University's Institute of Education Technology/Juliette White et al.

Glossary/ key

Grouping

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

DEL/ D

Proposal to delete files and/or functions and/or code.

MV

Proposal to move files and/or functions and/or code.

OU

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

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?

groups_groupings

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?

groups

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.

groups_members

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.

groups_courses_groups

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)

groups_courses_groupings

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)

groups_groupings_groups

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

course_modules

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)

db/upgrade.php:

• 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,

lib/basicgrouplib.php:

• 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,

lib/groupinglib.php:

• Constants/ defines: GROUP_NOT_IN_GROUPING, GROUP_ANY_GROUPING.
• 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,

lib/legacylib.php:

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

lib/modulelib.php:

• 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,

lib/utillib.php:

• 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

simpletest/test_basicgrouplib.php:

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

simpletest/test_groupinglib.php:

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

Others

backup/backuplib.php:

• backup_groups_info, backup_groups_members_info, backup_groupings_info, backup_groupids_info.

backup/restorelib.php:

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

lib/moodlelib.php

• MV Constants/ defines: NOGROUPS, SEPARATEGROUPS, VISIBLEGROUPS.

lib/weblib.php

• 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!)

course/lib.php:

• function set_coursemodule_grouping.

course/moodleform_mod.php:

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

lib/db/install.xml

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

lib/db/upgrade.php

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

lib/form/modgrouping.php:

• class MoodleQuickForm_modgrouping extends MoodleQuickForm_select.

lib/formslib.php:

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

mod/data/mod_form.php

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

... mod/data/view.php

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

Future requirements

Objectives

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!

Target

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.

Scope

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

Comment

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

• Enrique Castro group specification.
• Petr Skoda group specification.