Cross-System Synchronization Proposal
This proposal involves building a new user grouping system, maintaining synchronization with existing legacy mechanisms (such as cohorts, teams, or enrollment track groups) through an abstraction layer. The new system will be responsible for defining and managing the grouping logic, while the abstraction layer will translate that logic into the behavior of the legacy mechanisms to ensure backward compatibility. The goal is to enable a structural evolution of the grouping model without breaking existing functionality, allowing for a gradual transition and preserving consistency between systems during the adoption process.
Phase 1: Adding the New Model (MVP)
This phase is planned to be completed during the Ulmo Release.
Objective
Implement the new unified user grouping system without interrupting the functionality of existing mechanisms (Cohorts, Teams, and Enrollment Tracks). By validating the new user grouping model's functionality and key criteria, the goal is to establish a solid foundation for a seamless transition.
This phase introduces the foundational structures of the unified system without replacing existing ones. The following models should be evaluated, as they are not yet final until a design proposal is selected. More details in the Unified User Group Model Technical Approach.
Specific Actions
1. Implementation of the Unified Model
Create data models (
UserGrouping,GroupCriterion,Membership, etc.) and their basic validation logic.Define evaluators according to the registry-based model.
2. Controlled Activation
The new user grouping system will be disabled by default. It will support activation at different levels (course, organization, or platform) through a configurable flag by operators. This enables controlled testing without affecting full production instances.
UI Available
A new tab will be added within the instructor panel to manage the new user grouping system.
The legacy interfaces for the current user grouping mechanisms will remain unchanged.
Completion Criteria
The first phase of the new user grouping system will be considered complete when the following conditions are met:
The user grouping system is implemented and integrated into the platform, with controlled activation via a feature flag.
Users can be grouped accurately and without errors based on custom criteria defined by administrators or instructors.
A tab in the instructor dashboard is available for managing user groups.
The user grouping system operates independently without affecting legacy systems like Cohorts, Teams, or Enrollment Tracks.
Completion of this phase means the launch of the MVP.
Phase 2: Integration with Legacy Groups
This phase is planned to be completed during the Verawood Release.
Objective
Begin integrating the new system with legacy mechanisms. Using an abstraction layer, the unified model will continue to rely on legacy logic for normal use cases (content restriction, discussion division, custom ORA assignment, etc.). This phase allows testing and validating the integration without disrupting the end-user experience, while identifying necessary changes to fully adopt the new system as the source of truth.
Specific Actions
1. Implement an Abstraction Layer
Register equivalent criterion types for legacy mechanisms: EnrollmentTrackCriterion, CohortCriterion, TeamCriterion.
Register specific evaluators according to the legacy mechanisms:
EnrollmentTrackEvaluator,CohortEvaluator,TeamEvaluator.Create an abstraction layer from user groups that reuses legacy logic. Evaluators will connect to legacy systems to filter and update users.
2. Backward Compatibility
All changes must be backward compatible with existing platform structures and flows.
APIs and integrations must continue to respond as usual for Cohorts, Teams, and Enrollment Tracks.
Business logic visible to users (content visibility, discussions, ORA assignments, Studio configurations) must not be altered.
If the new system is enabled in some courses, it must be possible to disable it without data or functionality loss in legacy mechanisms.
3. Identify Changes Needed to Make the New Model the Source of Truth
Identify all changes required to support legacy functionalities in the new user grouping system:
Content Gating: Modify the partition logic to work with any group in the unified system.
Discussions: Adapt the discussion segmentation logic to function with any group.
ORA: Modify task assignment logic to support any group in the unified model.
For more details, see: Support for Legacy Functionalities
UI Available
Both interfaces coexist on the platform, although the new one will only be visible if the flag is activated:
The new tab in the instructor dashboard will remain unchanged.
The legacy interfaces for the current user grouping mechanisms will remain unchanged.
Completion Criteria
The new user grouping system replicates the behavior of existing mechanisms (Cohorts, Teams, and Enrollment Tracks) in core functionalities such as content visibility, discussions, and custom ORA assignments, without affecting the current user experience.
The system supports compatibility through an abstraction layer, allowing use either the legacy logic transparently.
The new grouping system can be enabled or disabled, without causing data loss or functionality issues in the legacy mechanisms.
Full API and platform compatibility is maintained while the new system is active.
The system has been tested in real scenarios, ensuring stability, consistency, and no regressions for instructors or learners.
All technical adaptations required to fully replace the legacy models have been identified and documented for future implementation.
Phase 3: New Model as the Source of Truth
This phase is planned to be completed during the W Release.
Objective
Consolidate the new unified system as the sole source of truth for user grouping logic. This phase aims to fully replace functional dependency on legacy mechanisms (cohorts, teams, enrollment track groups), ensuring all platform features only use the new model. It also includes identifying and resolving deviations in behavior to guarantee a smooth transition without loss of functionality.
Specific Actions
1. Adapt Legacy Features
Update all identified legacy features so the new model becomes the source of truth:
Content Gating
Divided Discussions
ORA Assignments
2. Identify Issues and Limitations
During the transition, identify:
Cases where exclusivity rules, size limits, or visibility don’t match the old model.
Unexpected functionality losses in assignment, segmentation, or sync logic.
Negative impacts on external integrations, XBlocks, or existing APIs.
Performance testing.
This phase must be accompanied by functional and technical validations, as well as feedback from instructors or admins working with the new system.
3. Implement Solutions
Based on the issues identified, apply fixes or add new features that guarantee:
Functional compatibility with current critical cases.
Equivalent or improved behavior compared to legacy mechanisms.
UI Available
Both interfaces coexist on the platform, although the new one will only be visible if the flag is activated:
The new tab in the instructor dashboard will remain unchanged.
The legacy interfaces for the current user grouping mechanisms will remain unchanged.
Completion Criteria
The third phase will be considered complete when the following conditions are met:
The new grouping model serves as the single source of truth for all grouping logic across the platform and is the sole system used by all features, such as content gating, discussions, and ORA assignments.
All grouping use cases previously supported by Cohorts, Teams, and Enrollment Tracks are fully addressed through the new interface.
Extensive testing (functional, compatibility, and performance) has been completed, including validation in courses with large user bases and complex setups.
Feedback from instructors and admins has been gathered and used to resolve any usability or workflow issues.
Phase 4: Legacy Groups Removal
This phase is planned to be completed during the X Release.
Objective
Complete the migration to the new system by fully removing everything related to legacy grouping mechanisms (Cohorts, Teams, Enrollment Tracks), both in the backend and frontend. By this stage, there should be no remaining technical or functional dependency on legacy models. The focus shifts to cleaning old code, updating documentation, and validating the system at scale to ensure no regression in user or instructor experience.
This phase will be executed gradually, in the following order:
Enrollment Track Groups
Cohorts
Teams
Specific Actions
1. Elimination of Enrollment Track Groups
Remove old models, serializers, signals, managers, and utilities related.
Cleanup of views, endpoints, and logic in services.
Remove legacy UI and MFE (Studio and LMS), such as Group Configuration Settings.
2. Elimination of Cohorts
Remove old models (
CourseUserGroup,CohortMembership,CourseCohort,CourseCohortSettings, etc.), serializers, signals, managers, and utilities related.Cleanup of views, endpoints, and logic in services.
Remove legacy UI and MFE (Studio and LMS)
3. Elimination of Teams
Remove old models (
CourseTeam,CourseTeamMembership, etc.), serializers, signals, managers, and utilities related.Cleanup of views, endpoints, and logic in services.
Remove legacy UI and MFE (Studio and LMS).
4. Remove Flag
Remove the flag that enables/disables the new grouping model. The new user grouping system will be enabled by default.
5. Testing and Validation
Validate learner experience: correct content visibility, access to discussions, and ORA assignment functionality.
Validate instructor experience: proper user group management through the new interface.
Run performance and functionality tests in high-enrollment courses.
6. Documentation
Update technical and functional documentation (for devs, operators, and course authors).
Include guides for using the new model and examples of how to apply the criteria.
Offer comparative material between the previous model and the new one.
7. Formal Closure of the Migration
Mark milestones in Confluence/GitHub with a completed status.
Officially communicate the end of support for legacy mechanisms.
UI Available
Only the new UI for the new user grouping system will remain available. No flag will be required to display the new interface.
The legacy interfaces for the legacy systems were completely removed.
Completion Criteria
The third phase of the new user grouping system will be considered complete when the following conditions are met:
All legacy components (models, endpoints, views, and interfaces related to Cohorts, Teams, and Enrollment Tracks) have been removed from the codebase without impacting critical functionality.
Legacy grouping interfaces in both LMS and Studio have been retired. All grouping operations are now performed solely through the new tab in the instructor dashboard.
The platform has been successfully validated at scale, including courses with many users, with no performance degradation or functional regressions.
All related technical and functional documentation has been fully updated to reflect the new architecture.
Phase 5: New Admin Panel Integration
This phase is planned to be completed during the Y Release.
Objective
Migrate all user group management functionalities from the instructor tab to a new centralized admin panel. This new panel will serve as the single point of interaction for administrators and course authors, enabling broader management capabilities with greater visibility, control, and scalability.
Specific Actions
1. Migration of group management functionalities
Move all user grouping features previously available in the instructor tab to the new panel:
Creation and editing of groups.
Management of criteria (manual and automatic).
Manual user assignment or CSV-based bulk assignment.
Display of all metadata related to the group.
2. Enable organization and platform-level scope
Allow group management and configuration at the organization and platform levels.
3. Removal of the instructor tab
Remove the user grouping tab from the instructor panel.
4. Documentation
Provide updated guides for operators and course teams on the new workflows.
Include comparative material between the instructor tab and the new panel.
Offer optionally video tutorials, FAQs, and examples of advanced use cases.
UI Available
Only the new centralized admin panel will be used to manage user groups. It will replace the instructor tab in the LMS.
Completion Criteria
The fourth phase of the user grouping system will be considered complete when the following conditions are met:
All user group management functionalities and metadata display have been successfully migrated from the instructor tab to the new centralized admin panel.
The new panel supports group management at the course, organization, and platform levels, enabling broader visibility and control.
The user grouping tab in the instructor dashboard has been fully removed, and all interactions now occur exclusively through the centralized panel.
The new admin panel is fully functional and accessible, providing a clear, scalable, and intuitive interface for administrators and course authors.
Documentation and training materials have been completed and distributed, including:
Updated guides for administrators and course teams.
Comparative materials outlining the differences between the instructor tab and the new panel.
Optional resources such as video tutorials, FAQs, and advanced use case examples.
The platform has been validated post-migration to ensure functional parity, no regressions, and improved usability.