feat: implement course authoring migration functionality

Author: BryanttV

openedx_authz/admin.py

@@ -4,7 +4,7 @@
 from django import forms
 from django.contrib import admin
 
-from openedx_authz.models import ExtendedCasbinRule
+from openedx_authz.models import AuthzCourseAuthoringMigrationRun, ExtendedCasbinRule
 
 
 class CasbinRuleForm(forms.ModelForm):
@@ -48,3 +48,13 @@ class CasbinRuleAdmin(admin.ModelAdmin):
     # TODO: In a future, possibly we should only show an inline for the rules that
     # have an extended rule, and show the subject and scope information in detail.
     inlines = [ExtendedCasbinRuleInline]
+
+
+@admin.register(AuthzCourseAuthoringMigrationRun)
+class AuthzCourseAuthoringMigrationRunAdmin(admin.ModelAdmin):
+    """Admin for AuthzCourseAuthoringMigrationRun to display additional metadata."""
+
+    list_display = ("id", "scope_type", "scope_key", "migration_type", "status", "created_at", "updated_at")
+    search_fields = ("scope_type", "scope_key", "migration_type", "status")
+    list_filter = ("scope_type", "migration_type", "status")
+    readonly_fields = ("completed_at", "created_at", "updated_at")

openedx_authz/api/roles.py

@@ -571,6 +571,5 @@ def get_all_role_assignments_per_scope_type(scope_types: tuple[type[ScopeData],
         list[RoleAssignmentData]: All assignments whose scope is an instance of any of the given scope types.
     """
     return [
-        role_assignment for role_assignment in get_role_assignments()
-        if isinstance(role_assignment.scope, scope_types)
+        role_assignment for role_assignment in get_role_assignments() if isinstance(role_assignment.scope, scope_types)
     ]

openedx_authz/engine/utils.py

@@ -8,10 +8,11 @@
 from collections import defaultdict
 
 from casbin import Enforcer
+from django.db import IntegrityError, transaction
 from django.db.models import Q
 from opaque_keys.edx.django.models import CourseKeyField
 
-from openedx_authz.api.data import CourseOverviewData, OrgCourseOverviewGlobData
+from openedx_authz.api.data import CourseOverviewData, OrgCourseOverviewGlobData, RoleAssignmentData
 from openedx_authz.api.roles import get_all_role_assignments_per_scope_type
 from openedx_authz.api.users import (
     assign_role_to_user_in_scope,
@@ -24,6 +25,7 @@
     LIBRARY_AUTHOR,
     LIBRARY_USER,
 )
+from openedx_authz.models.migrations import AuthzCourseAuthoringMigrationRun, MigrationType, ScopeType
 
 logger = logging.getLogger(__name__)
 
@@ -264,8 +266,7 @@ def migrate_legacy_course_roles_to_authz(course_access_role_model, course_id_lis
 
         # Permission applied to individual user
         logger.info(
-            f"Migrating permission for User: {permission.user.username} "
-            f"to Role: {role} in Scope: {scope_external_key}"
+            f"Migrating permission for User: {permission.user.username} to Role: {role} in Scope: {scope_external_key}"
         )
 
         is_user_added = assign_role_to_user_in_scope(
@@ -296,7 +297,7 @@ def migrate_legacy_course_roles_to_authz(course_access_role_model, course_id_lis
 
 def migrate_authz_to_legacy_course_roles(
     course_access_role_model, user_subject_model, course_id_list, org_id, delete_after_migration
-):
+) -> tuple[list[RoleAssignmentData], list[RoleAssignmentData]]:
     """
     Migrate permissions from the new Casbin-based authorization model back to the legacy CourseAccessRole model.
     This function reads permissions from the Casbin enforcer and creates equivalent entries in the
@@ -322,25 +323,23 @@ def migrate_authz_to_legacy_course_roles(
     _validate_migration_input(course_id_list, org_id)
 
     role_assignments = get_all_role_assignments_per_scope_type(
-        scope_types=(CourseOverviewData, OrgCourseOverviewGlobData,)
+        scope_types=(CourseOverviewData, OrgCourseOverviewGlobData)
     )
 
     # Two cases here:
     # 1. org_id provided: filter by org — includes org-level glob and course-level scopes for that org.
     # 2. only course_id_list provided: filter by course_id — org-level glob scopes are excluded (no course_id).
     if org_id:
         role_assignments = [
-            role_assignment
-            for role_assignment in role_assignments
-            if role_assignment.scope.org == org_id
+            role_assignment for role_assignment in role_assignments if role_assignment.scope.org == org_id
         ]
 
     if course_id_list and not org_id:
         role_assignments = [
             role_assignment
             for role_assignment in role_assignments
-            if isinstance(role_assignment.scope, CourseOverviewData) and
-            role_assignment.scope.course_id in course_id_list
+            if isinstance(role_assignment.scope, CourseOverviewData)
+            and role_assignment.scope.course_id in course_id_list
         ]
 
     roles_with_errors = []
@@ -350,13 +349,10 @@ def migrate_authz_to_legacy_course_roles(
     user_external_keys = {assignment.subject.external_key for assignment in role_assignments}
     users_by_username = {
         subject.user.username: subject.user
-        for subject in user_subject_model.objects.filter(
-            user__username__in=user_external_keys
-        ).select_related("user")
+        for subject in user_subject_model.objects.filter(user__username__in=user_external_keys).select_related("user")
     }
 
     for role_assignment in role_assignments:
-
         # Per valid role assignment, create corresponding CourseAccessRole entry
         # depending on whether the scope is course-level or org-level glob
         try:
@@ -410,7 +406,7 @@ def migrate_authz_to_legacy_course_roles(
         logger.info(f"Total of {total_unassignments} role assignments unassigned after successful rollback migration.")
         for (role_external_key, scope), users in unassignments.items():
             logger.info(
-                f"Unassigned Role: {role_external_key} from {len(users)} users \n"
+                f"Unassigned Role: {role_external_key} from {len(users)} users "
                 f"in Scope: {scope} after successful rollback migration."
             )
             batch_unassign_role_from_users(
@@ -420,3 +416,97 @@ def migrate_authz_to_legacy_course_roles(
             )
 
     return roles_with_errors, roles_with_no_errors
+
+
+# pylint: disable=too-many-positional-arguments
+def run_course_authoring_migration(
+    migration_type: MigrationType,
+    scope_type: ScopeType,
+    scope_key: str,
+    course_access_role_model,
+    user_subject_model=None,
+    course_id_list=None,
+    org_id=None,
+    delete_after_migration=True,
+) -> None:
+    """Run a course authoring migration with full tracking and concurrency guard.
+
+    TODO: Add better documentation.
+
+    Args:
+        migration_type (MigrationType): Direction of the migration
+            (``FORWARD`` = legacy → authz, ``ROLLBACK`` = authz → legacy).
+        scope_type (ScopeType): Whether the scope is a single course or an org.
+        scope_key (str): Course ID string or org name used as the tracking key.
+        course_access_role_model: The ``CourseAccessRole`` model class (passed
+            explicitly to avoid import issues inside Django migrations).
+        user_subject_model: The ``UserSubject`` model class. Required for
+            ``ROLLBACK`` migrations; ignored for ``FORWARD`` migrations.
+        course_id_list (list[str] | None): List of course-v1 keys to filter.
+        org_id (str | None): Organisation name to filter.
+        delete_after_migration (bool): Whether to delete/unassign successfully
+            migrated entries from the source system after migration.
+    """
+    try:
+        with transaction.atomic():
+            run = AuthzCourseAuthoringMigrationRun.create_running(migration_type, scope_type, scope_key)
+    except IntegrityError:
+        logger.warning(
+            "Skipping %s migration for %s:%s — an active run already exists.", migration_type, scope_type, scope_key
+        )
+        AuthzCourseAuthoringMigrationRun.create_skipped(migration_type, scope_type, scope_key)
+        return
+
+    logger.info("Started %s migration run [%s] for %s:%s", migration_type, run.id, scope_type, scope_key)
+
+    try:
+        with transaction.atomic():
+            if migration_type == MigrationType.FORWARD:
+                errors, successes = migrate_legacy_course_roles_to_authz(
+                    course_access_role_model, course_id_list, org_id, delete_after_migration
+                )
+            else:
+                errors, successes = migrate_authz_to_legacy_course_roles(
+                    course_access_role_model, user_subject_model, course_id_list, org_id, delete_after_migration
+                )
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        # The inner atomic block is rolled back on exception; mark_failed() runs
+        # outside it so the tracking record is always persisted.
+        logger.exception(
+            "Unexpected error in migration run [%s] for %s:%s", run.id, scope_type, scope_key, exc_info=exc
+        )
+        run.mark_failed(exception=exc)
+        return
+
+    metadata_updates = {"successes": len(successes), "errors": len(errors)}
+
+    # TODO: Add details of each error in the metadata.
+    if errors:
+        error_metadata = {}
+        for idx, error in enumerate(errors):
+            error_metadata[f"error_{idx}"] = {
+                "subject": error.subject.external_key,
+                "role": error.roles[0].external_key,
+                "scope": error.scope.external_key,
+            }
+        metadata_updates["errors"] = error_metadata
+        run.mark_partial_success(metadata_updates=metadata_updates)
+        logger.warning(
+            "Partial success in %s migration run [%s] for %s:%s — successes=%d, errors=%d",
+            migration_type,
+            run.id,
+            scope_type,
+            scope_key,
+            len(successes),
+            len(errors),
+        )
+    else:
+        run.mark_completed(metadata_updates=metadata_updates)
+        logger.info(
+            "Completed %s migration run [%s] for %s:%s — successes=%d",
+            migration_type,
+            run.id,
+            scope_type,
+            scope_key,
+            len(successes),
+        )

openedx_authz/handlers.py

@@ -4,19 +4,33 @@
 These handlers ensure proper cleanup and consistency when models are deleted.
 """
 
+from __future__ import annotations
+
 import logging
 
 from casbin_adapter.models import CasbinRule
-from django.db.models.signals import post_delete
+from django.conf import settings
+from django.db.models.signals import post_delete, post_save
 from django.dispatch import receiver
 
 from openedx_authz.api.users import unassign_all_roles_from_user
+from openedx_authz.engine.utils import run_course_authoring_migration
 from openedx_authz.models.core import ExtendedCasbinRule
+from openedx_authz.models.migrations import MigrationType, ScopeType
+from openedx_authz.models.subjects import UserSubject
 
 try:
+    from common.djangoapps.student.models import CourseAccessRole
     from openedx.core.djangoapps.user_api.accounts.signals import USER_RETIRE_LMS_CRITICAL
+    from openedx.core.djangoapps.waffle_utils.models import WaffleFlagCourseOverrideModel, WaffleFlagOrgOverrideModel
+    from openedx.core.toggles import AUTHZ_COURSE_AUTHORING_FLAG
 except ImportError:
     USER_RETIRE_LMS_CRITICAL = None
+    WaffleFlagCourseOverrideModel = None
+    WaffleFlagOrgOverrideModel = None
+    AUTHZ_COURSE_AUTHORING_FLAG = None
+    CourseAccessRole = None
+
 
 logger = logging.getLogger(__name__)
 
@@ -82,3 +96,99 @@ def unassign_roles_on_user_retirement(sender, user, **kwargs):  # pylint: disabl
 # Only register the handler if the signal is available (i.e., running in Open edX)
 if USER_RETIRE_LMS_CRITICAL is not None:
     USER_RETIRE_LMS_CRITICAL.connect(unassign_roles_on_user_retirement)
+
+
+def handle_course_waffle_flag_change(sender, instance, **kwargs) -> None:
+    """
+    Handle changes to course-level waffle flags.
+
+    When the authz.enable_course_authoring flag is changed for a course,
+    trigger the appropriate migration run. Only trigger if automatic migration
+    is enabled in the settings.
+
+    Args:
+        sender: The model class (WaffleFlagCourseOverrideModel)
+        instance: The flag override instance being saved
+        **kwargs: Additional keyword arguments from the signal
+    """
+    trigger_course_authoring_migration(sender=sender, instance=instance, scope_key=str(instance.course_id))
+
+
+def handle_org_waffle_flag_change(sender, instance, **kwargs) -> None:
+    """
+    Handle changes to organization-level waffle flags.
+
+    When the authz.enable_course_authoring flag is changed for an organization,
+    trigger the appropriate migration run. Only trigger if automatic migration
+    is enabled in the settings.
+
+    Args:
+        sender: The model class (WaffleFlagOrgOverrideModel)
+        instance: The flag override instance being saved
+        **kwargs: Additional keyword arguments from the signal
+    """
+    trigger_course_authoring_migration(sender=sender, instance=instance, scope_key=str(instance.org))
+
+
+# Only register the handlers if the models are available (i.e., running in Open edX)
+if WaffleFlagCourseOverrideModel is not None:
+    post_save.connect(handle_course_waffle_flag_change, sender=WaffleFlagCourseOverrideModel)
+
+if WaffleFlagOrgOverrideModel is not None:
+    post_save.connect(handle_org_waffle_flag_change, sender=WaffleFlagOrgOverrideModel)
+
+
+def trigger_course_authoring_migration(
+    sender: type[WaffleFlagCourseOverrideModel | WaffleFlagOrgOverrideModel],
+    instance: WaffleFlagCourseOverrideModel | WaffleFlagOrgOverrideModel,
+    scope_key: str,
+) -> None:
+    """
+    Trigger a migration run in response to a waffle flag change.
+
+    Determines the migration direction from the flag state, guards against
+    no-op saves, and delegates execution to ``run_course_authoring_migration``
+    which handles tracking and concurrent-run protection.
+
+    Args:
+        sender: The model class (WaffleFlagCourseOverrideModel or WaffleFlagOrgOverrideModel).
+        instance: The waffle flag instance that triggered the migration.
+        scope_key (str): Course ID or organization name.
+    """
+    if not settings.ENABLE_AUTOMATIC_AUTHZ_COURSE_AUTHORING_MIGRATION:
+        logger.info("ENABLE_AUTOMATIC_AUTHZ_COURSE_AUTHORING_MIGRATION is set to False, skipping migration")
+        return
+
+    if instance.waffle_flag != AUTHZ_COURSE_AUTHORING_FLAG.name:
+        return
+
+    course_id_list, org_id, scope_type = None, None, None
+    filter_kwargs = {"waffle_flag": AUTHZ_COURSE_AUTHORING_FLAG.name}
+    if isinstance(instance, WaffleFlagCourseOverrideModel):
+        filter_kwargs["course_id"] = instance.course_id
+        course_id_list = [scope_key]
+        scope_type = ScopeType.COURSE
+    elif isinstance(instance, WaffleFlagOrgOverrideModel):
+        filter_kwargs["org"] = instance.org
+        org_id = scope_key
+        scope_type = ScopeType.ORG
+
+    prev_record = sender.objects.filter(**filter_kwargs).exclude(id=instance.id).order_by("-change_date").first()
+
+    if prev_record and prev_record.enabled == instance.enabled:
+        logger.info("No change in waffle flag, skipping course migration")
+        return
+
+    migration_type = MigrationType.FORWARD if instance.enabled else MigrationType.ROLLBACK
+
+    logger.info("Triggering %s migration for %s:%s due to waffle flag change", migration_type, scope_type, scope_key)
+
+    run_course_authoring_migration(
+        migration_type=migration_type,
+        scope_type=scope_type,
+        scope_key=scope_key,
+        course_access_role_model=CourseAccessRole,
+        user_subject_model=UserSubject,
+        course_id_list=course_id_list,
+        org_id=org_id,
+    )