Technical Exploration of Existing User Grouping Mechanisms
Introduction
This document presents a preliminary analysis of the current user grouping mechanisms available in the Open edX platform. The goal is to better understand how existing systems such as Cohorts, Teams, and Enrollment Tracks function, their use cases, limitations, and how they are implemented. This will inform future architectural decisions related to the unification and potential migration of user grouping strategies.
Cohorts
General Description
Cohorts are a mechanism for segmenting learners within a course into mutually exclusive groups. They are defined in the course_groups django app in edx-platform. The primary use of Cohorts is to restrict access to certain course content (units and components) and discussions to specific groups of learners.
Each learner can only belong to one Cohort per course. A Cohort can be linked to a Content Group to control the visibility of course units or components, making them accessible only to members of that Cohort. Similarly, course discussions can be restricted to Cohorts so that learners only see and participate in discussions within their assigned group.
Learners may be assigned to Cohorts either manually by instructors or automatically by the system when they access content if automatic assignment is enabled. Manual assignment allows instructors to place learners in Cohorts even before they enroll in the course.
Once a learner is assigned to a new Cohort, they are removed from their previous one. Cohorts cannot be deleted but can be edited. There is also support for assigning unregistered users to Cohorts using email addresses.
Code in edx-platform
Model:
openedx/core/djangoapps/course_groups/models.pyViews:
openedx/core/djangoapps/course_groups/views.pyUrls:
openedx/core/djangoapps/course_groups/urls.py
Models
CourseUserGroup
Represents a group of users within a course. Currently, the only supported type is Cohort.
Fields:
name: Group name (unique per course).users: List of users.course_id: Course identifier.group_type: Type of group, currently onlycohort.
Key Method:
create(name, course_id): Creates a new groupCourseUserGroupof typecohortif it does not already exist.
CohortMembership
Associates a learner with a CourseUserGroup of type cohort. Ensures that a learner belongs to only one Cohort per course.
Fields:
user: Assigned learner.course_user_group: Cohort group.course_id: Course identifier.
Key Method:
assign(cohort, user): Assigns a learner to a Cohort, removing them from any existing one.
CourseCohort
Links a CourseUserGroup to Cohort-specific data.
Fields:
assignment_type:randomormanual.random: Learners are automatically assigned when accessing content.manual: Only manually assigned by instructors.
Key Method:
create(name, course_id): Creates aCourseUserGroupwith itsCourseCohort.
CourseCohortsSettings
Course-level configuration.
Fields:
is_cohorted: Whether cohorts feature is enabled.course_id: Course identifier.
CourseUserGroupPartitionGroup
Relates Cohorts with partitions to restrict content.
UnregisteredLearnerCohortAssignments
Allows assigning cohorts to learners not yet registered, using their email.
Teams
General Description
Teams are used to organize learners into small collaborative groups within a course. Managed by the teams django app in edx-platform and by the teams_config, which handles Team-Sets and general teams configuration. The primary use of Teams is to enable learners to collaborate and interact in small groups and allow instructors to restrict access to certain course content (units and components) and assign custom Open Response Assessments (ORA).
A course can have multiple Team-Sets (also referred to as Topics or Groups in some contexts), each containing multiple Teams. Learners may join one Team per Team-Set. This allows for simultaneous groupings based on different criteria or learning activities.
Teams can be configured to be open (learners can join/leave freely), instructor-managed, or hybrid. Team membership can also control access to course content through Content Groups.
Code in edx-platform
Model:
lms/djangoapps/teams/models.pyViews:
lms/djangoapps/teams/views.pyUrls:
lms/djangoapps/teams/api_urls.py
Models
Team-Set / Topics / Groups
Each Team-Set contains multiple Teams. The configuration is stored in the course's Advanced Settings via a teams_configuration JSON field.
Fields:
enabled: Whether Teams are enabled.max_team_size: Maximum number of learners per Team.team_sets: List of Team-Sets, each with:id: Team-Set identifier.name: Team-Set name.description: Team-Set description.max_team_size: Maximum number of users that each Team can have in the Team-Set (overrides default value).type: Team-Set type:open: Learners can freely create/join/leave Teams.public_managed: Only instructors manage Teams; visible to all.private_managed: Only instructors manage Teams; team content is private.open_managed: Instructors create Teams; learners can join/leave (requires MFE config).
user_partition_id: User partition identifier.
CourseTeam
Represents a team in a course.
Fields:
team_id: Team identifier.discussion_topic_id: Discussion topic identifier.name,description,country,language: Basic team information.topic_id: Team-Set identifier (is the sameteamset_id).course_id: Course identifier.organization_protected: Defines if the team is exclusive of an organization.
Key Methods:
create(...): Creates an instance of aCourseTeam.add_user(user): Adds a user to the Team.reset_team_size(): Recalculates the Team size.
CourseTeamMembership
Associates a learner with a team.
Fields:
user: Associated user.team: Associated team.date_joined: Date the user joined the team.last_activity_at: Last activity date of the user in the team.
Key Methods:
save(...): Updates the team’s activity and size.delete(...): Delete a member from a team. The team size is recalculated.get_memberships(...): Filters memberships by user, course, or team.
Partitions
TeamUserPartition
Inherits from UserPartition. Dynamically defines groups based on teams in the course.
Key Method:
groups(): Generates groups based on existing teams.
TeamPartitionSchema
Implements a schema that maps learners to groups based on their team membership.
Key Methods:
get_group_for_user(...)Returns the group to which the user belongs within the partition.create_user_partition(...): Creates an instance of theTeamUserPartition.
Enrollment Tracks
General Description
Enrollment Tracks group learners according to their enrollment mode—such as audit, verified, professional, etc. These groups are automatically created and assigned using CourseMode settings defined in the platform.
Enrollment Tracks are useful for differentiating access to course content (units and components) depending on the learner's enrollment choice.
Unlike Cohorts or Teams, Enrollment Tracks are not manually configured for individual learners. Instead, the assignment is based solely on the learner’s enrollment path selected during registration. If a learner or an instructor changes the learner’s enrollment mode at any time (e.g., upgrading from audit to verified), the learner's group assignment is updated accordingly to reflect the new Enrollment Track.
Partitions
EnrollmentTrackUserPartition
Inherits from UserPartition. Dynamically generates groups based on CourseMode definitions.
Key Method:
groups(): Creates groups based on the course's enrollment modes.
EnrollmentTrackPartitionSchema
Defines a schema that maps learners to groups based on their enrollment track.
Key Methods:
get_group_for_user(...): Returns the group to which the user belongs within the partition.create_user_partition(...): Creates an instance of theEnrollmentTrackUserPartitionpartition.