feat: add course authoring migration and rollback scripts

[dwong2708]

Resolves: #179

Course Authoring Roles Migration to Authz

Overview

This PR introduces migration and rollback support for course authoring roles between the legacy CourseAccessRole model and the new Authz (Casbin-based) authorization system.

It provides:

• Forward migration (legacy → Authz)
• Rollback migration (Authz → legacy)
• Optional cleanup of source permissions
• Management commands for operational control
• Automated data migration (The Django migration will be added once it is released)
• Full test coverage

What’s Included

1️⃣ Management Commands

authz_migrate_course_authoring

Migrates legacy CourseAccessRole entries to the new Authz system.

./manage.py authz_migrate_course_authoring (--course-id-list <id> [<id> ...] | --org-id <org>) [--delete]

• Requires either --course-id-list or --org-id (mutually exclusive)
• Filters migration by the provided course IDs or organization
• Maps legacy roles to their equivalent Authz roles
• Logs unmapped/invalid roles
• Runs inside a database transaction
• Optional --delete flag:
  • Prompts for confirmation
  • Removes successfully migrated legacy entries

authz_rollback_course_authoring

Rolls back Authz course authoring roles into legacy CourseAccessRole.

./manage.py cms authz_rollback_course_authoring (--course-id-list <id> [<id> ...] | --org-id <org>) [--delete]

• Requires either --course-id-list or --org-id (mutually exclusive)
• Filters rollback by the provided course IDs or organization
• Recreates legacy entries from Authz assignments
• Runs inside a database transaction
• Optional --delete flag:
  • Prompts for confirmation
  • Removes Authz role assignments after successful rollback

2️⃣ Service Layer

Added two migration service functions:

• migrate_legacy_course_roles_to_authz
• migrate_authz_to_legacy_course_roles

These encapsulate the migration logic and are reusable by:

• Management commands
• Data migrations
• Tests

3️⃣ Data Migration

A Django data migration has been added to automatically trigger the forward migration.

This ensures legacy course authoring roles are migrated during deployment without requiring manual intervention.

4️⃣ Test Coverage

Added comprehensive unit tests that verify:

• Correct role mapping (legacy ↔ Authz)
• Error handling for invalid roles
• Behavior with and without --delete
• Management command execution and flag handling
• Idempotency (no duplicate legacy roles on rollback)

🧠 Design Considerations

• Migration and rollback are symmetrical
• Deletion is always explicit and controlled via --delete
• Invalid roles are logged and skipped safely
• get_or_create ensures rollback does not create duplicates
• Commands wrap logic in transactions for safety

⚠️ Operational Notes

• Recommended to run migration without --delete first for validation.
• Rollback is fully supported in case of unexpected issues.
• Data migration runs automatically during deployment.

✅ Result

This PR provides a safe, reversible, and production-ready migration path from legacy course authoring roles to the new Authz system.

Merge checklist:
Check off if complete or not applicable:

• Version bumped
• Changelog record added
• Documentation updated (not only docstrings)
• Fixup commits are squashed away
• Unit tests added/updated
• Manual testing instructions provided
• Noted any: Concerns, dependencies, migration issues, deadlines, tickets

[openedx-webhooks]

Thanks for the pull request, @dwong2708!

This repository is currently maintained by @openedx/committers-openedx-authz.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[rodmgwgu]

We should make sure to only apply the migrations on courses that are covered by the feature flag.

If we cannot access the feature flag from here (as it is defined in edx-platform), we should add a parameter to the migration commands and functions to specify a list of courses to work on, so edx-platform can specify which courses to migrate.

[bmtcril]

Overall this is looking good. I think there is some tension between the need to use these commands for testing and for production migrations. For instance being able to migrate permissions when the waffle flag is not set which can cause perms to get out of sync and might cause confusion when an operator runs the command but nothing changes on the frontend.

Maybe we can add a flag that makes sure the waffle flag for the course(s) is set correctly for the direction that the migration is happening so the state stays locked to the permissions? I think I would make the operator version the default (change the waffle flag and delete) and make testing the exceptional case. What do you think?

[dwong2708]

Overall this is looking good. I think there is some tension between the need to use these commands for testing and for production migrations. For instance being able to migrate permissions when the waffle flag is not set which can cause perms to get out of sync and might cause confusion when an operator runs the command but nothing changes on the frontend.

Maybe we can add a flag that makes sure the waffle flag for the course(s) is set correctly for the direction that the migration is happening so the state stays locked to the permissions? I think I would make the operator version the default (change the waffle flag and delete) and make testing the exceptional case. What do you think?

Hello @rodmgwgu and @bmtcril ,

Based on what Rodrigo and I discussed, we are not using waffle flags here because doing so would require us to simulate waffle functionality, which currently lives in Open edX Platform. Bringing it here would likely require workarounds or introduce unnecessary complexity. That’s why we decided to exclude it.

The next step is to place this tool somewhere that listens to waffle flag events and triggers it accordingly. This will likely require changes in the Open edX Platform, since that’s where waffle functionality resides. I also agree with running the operator version by default. What do you think?

[rodmgwgu]

Just some minor corrections.

[rodmgwgu]

I tested it in my local and it's working great.

Just please remove the things added to the Django admin and make sure to create a follow-up issue to handle org assignments later before merging.

[wgu-taylor-payne]

Overall looks good. I didn't go too deep, but here are some suggestions.

[wgu-taylor-payne]

Calling a batch function with only one user works, but is also unexpected. Are there ways to batch or is there another function that just expects one user?

[dwong2708]

I added a way to do it on batch. Thanks

[bmtcril]

Based on what Rodrigo and I discussed, we are not using waffle flags here because doing so would require us to simulate waffle functionality, which currently lives in Open edX Platform. Bringing it here would likely require workarounds or introduce unnecessary complexity. That’s why we decided to exclude it.

The next step is to place this tool somewhere that listens to waffle flag events and triggers it accordingly. This will likely require changes in the Open edX Platform, since that’s where waffle functionality resides. I also agree with running the operator version by default. What do you think?

Ah right, the course/org flags were never broken out as a proper library. Ok. That might be an argument to move these scripts into edx-platform eventually but I think this is fine for now.

[bmtcril]

This is good for me when the other feedback is addressed, thanks!