feat: implement course authoring migration functionality

Author: BryanttV

openedx_authz/admin.py

@@ -1,10 +1,24 @@
 """Admin configuration for openedx_authz."""
 
+import json
+
 from casbin_adapter.models import CasbinRule
 from django import forms
 from django.contrib import admin
+from django.utils.html import format_html
+
+from openedx_authz.models import AuthzCourseAuthoringMigrationRun, ExtendedCasbinRule
 
-from openedx_authz.models import ExtendedCasbinRule
+
+def pretty_json(value) -> str:
+    """Return an indented JSON representation of a value."""
+    if value is None:
+        return "-"
+    try:
+        formatted = json.dumps(value, indent=2, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return str(value)
+    return format_html("<pre>{}</pre>", formatted)
 
 
 class CasbinRuleForm(forms.ModelForm):
@@ -48,3 +62,28 @@ 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 = (
+        "scope_type",
+        "scope_key",
+        "migration_type",
+        "status",
+        "pretty_metadata",
+        "completed_at",
+        "created_at",
+        "updated_at",
+    )
+    fields = readonly_fields
+
+    @admin.display(description="Metadata")
+    def pretty_metadata(self, obj):
+        """Return formatted JSON for the metadata field."""
+        return pretty_json(obj.metadata)

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

@@ -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,
+    )

openedx_authz/handlers.py

@@ -0,0 +1,83 @@
+# Generated by Django 5.2.12 on 2026-04-14 20:21
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("openedx_authz", "0007_coursescope"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="AuthzCourseAuthoringMigrationRun",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                (
+                    "migration_type",
+                    models.CharField(
+                        choices=[("forward", "Legacy to AuthZ"), ("rollback", "AuthZ to Legacy")],
+                        help_text="Direction of migration: forward (legacy → authz) or rollback (authz → legacy)",
+                        max_length=20,
+                    ),
+                ),
+                (
+                    "scope_type",
+                    models.CharField(
+                        choices=[("course", "Course"), ("org", "Organization")],
+                        help_text="Type of scope being migrated: course or organization",
+                        max_length=20,
+                    ),
+                ),
+                (
+                    "scope_key",
+                    models.CharField(
+                        help_text="Identifier for the scope (e.g., course-v1:edX+DemoX+DemoCourse or org name)",
+                        max_length=255,
+                    ),
+                ),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("running", "Running"),
+                            ("completed", "Completed"),
+                            ("partial_success", "Partial Success"),
+                            ("failed", "Failed"),
+                            ("skipped", "Skipped"),
+                        ],
+                        default="running",
+                        help_text="Current status of the migration run",
+                        max_length=20,
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True, help_text="When the migration run was created")),
+                (
+                    "updated_at",
+                    models.DateTimeField(auto_now=True, help_text="When the migration run was last updated"),
+                ),
+                (
+                    "completed_at",
+                    models.DateTimeField(blank=True, help_text="When the migration run was completed", null=True),
+                ),
+                (
+                    "metadata",
+                    models.JSONField(
+                        blank=True,
+                        default=dict,
+                        help_text="Additional metadata about the migration run (e.g., counts, warnings, errors)",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Course Authoring Migration Run",
+                "verbose_name_plural": "Course Authoring Migration Runs",
+                "ordering": ["-created_at"],
+                "indexes": [
+                    models.Index(fields=["scope_type", "scope_key"], name="openedx_aut_scope_t_d43a35_idx"),
+                    models.Index(fields=["status"], name="openedx_aut_status_e34b60_idx"),
+                    models.Index(fields=["-created_at"], name="openedx_aut_created_ab3e0a_idx"),
+                ],
+            },
+        ),
+    ]

openedx_authz/migrations/0008_authzcourseauthoringmigrationrun.py

@@ -16,5 +16,6 @@
 """
 
 from openedx_authz.models.core import *
+from openedx_authz.models.migrations import *
 from openedx_authz.models.scopes import *
 from openedx_authz.models.subjects import *