feat: add course authoring migration and rollback scripts by dwong2708 · Pull Request #218 · openedx/openedx-authz

dwong2708 · 2026-02-18T03:12:04Z

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 · 2026-02-18T03:12:09Z

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:

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.

openedx_authz/constants/roles.py

openedx_authz/engine/utils.py

CHANGELOG.rst

openedx_authz/engine/utils.py

- Add `authz_migrate_course_authoring` command to migrate legacy CourseAccessRole data to the new Authz (Casbin-based) system - Add `authz_rollback_course_authoring` command to rollback Authz roles back to legacy CourseAccessRole - Support optional `--delete` flag for controlled cleanup of source permissions after successful migration - Add `migrate_legacy_course_roles_to_authz` and `migrate_authz_to_legacy_course_roles` service functions - Add unit tests to verify migration and command behavior

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?

bmtcril · 2026-02-25T20:44:34Z

openedx_authz/engine/utils.py

    return permissions_with_errors
+
+
+def migrate_legacy_course_roles_to_authz(CourseAccessRole, course_id_list, org_id, delete_after_migration):


I can see why CourseAccessRole is named that, but it's pretty confusing to read. Would you be ok renaming it to something like course_access_role_model and putting a note in as to why we pass it this way?

bmtcril · 2026-02-25T20:54:26Z

openedx_authz/engine/utils.py

+    return permissions_with_errors, permissions_with_no_errors
+
+
+def migrate_authz_to_legacy_course_roles(CourseAccessRole, UserSubject, course_id_list, org_id, delete_after_migration):


Same thing as above with these names

bmtcril · 2026-02-26T14:23:46Z

openedx_authz/engine/utils.py

+                    continue
+
+                # If we successfully created the legacy role, we can unassign the new role
+                if delete_after_migration:


In the other direction we only do this on roles_with_no_errors, should we do the same here?

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Feb 18, 2026

openedx-webhooks added this to Contributions Feb 18, 2026

github-project-automation bot moved this to Needs Triage in Contributions Feb 18, 2026

mphilbrick211 added the mao-onboarding Reviewing this will help onboard devs from an Axim mission-aligned organization (MAO). label Feb 18, 2026

mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Feb 18, 2026

rodmgwgu requested changes Feb 19, 2026

View reviewed changes

dwong2708 force-pushed the dwong2708/migration-script-for-course-roles branch from b605933 to 0b8547b Compare February 19, 2026 17:52

dwong2708 marked this pull request as ready for review February 20, 2026 22:03

dwong2708 requested review from bmtcril, rodmgwgu and wgu-taylor-payne February 20, 2026 22:05

dwong2708 added 7 commits February 20, 2026 16:13

fixup! feat: add course authoring migration and rollback scripts

bf5d76c

fixup! feat: add course authoring migration and rollback scripts

ac7acef

fixup! feat: add course authoring migration and rollback scripts

e627dd7

fixup! feat: add course authoring migration and rollback scripts

ec9785f

fixup! feat: add course authoring migration and rollback scripts

1cda364

fixup! feat: add course authoring migration and rollback scripts

c8f1c73

dwong2708 force-pushed the dwong2708/migration-script-for-course-roles branch from b0463fa to c8f1c73 Compare February 20, 2026 22:16

mphilbrick211 moved this from Waiting on Author to In Eng Review in Contributions Feb 25, 2026

fixup! feat: add course authoring migration and rollback scripts

37149a8

bmtcril reviewed Feb 26, 2026

View reviewed changes

dwong2708 added 2 commits February 26, 2026 09:16

fixup! feat: add course authoring migration and rollback scripts

1753f8e

fixup! feat: add course authoring migration and rollback scripts

0a21eb5

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add course authoring migration and rollback scripts#218

feat: add course authoring migration and rollback scripts#218
dwong2708 wants to merge 10 commits intoopenedx:mainfrom
WGU-Open-edX:dwong2708/migration-script-for-course-roles

dwong2708 commented Feb 18, 2026 •

edited

Loading

Uh oh!

openedx-webhooks commented Feb 18, 2026 •

edited

Loading

Uh oh!

rodmgwgu left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bmtcril left a comment

Uh oh!

bmtcril Feb 25, 2026

Uh oh!

bmtcril Feb 25, 2026

Uh oh!

bmtcril Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		return permissions_with_errors


		def migrate_legacy_course_roles_to_authz(CourseAccessRole, course_id_list, org_id, delete_after_migration):

		return permissions_with_errors, permissions_with_no_errors


		def migrate_authz_to_legacy_course_roles(CourseAccessRole, UserSubject, course_id_list, org_id, delete_after_migration):

Conversation

dwong2708 commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Course Authoring Roles Migration to Authz

Overview

What’s Included

authz_migrate_course_authoring

authz_rollback_course_authoring

Uh oh!

openedx-webhooks commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rodmgwgu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bmtcril left a comment

Choose a reason for hiding this comment

Uh oh!

bmtcril Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

bmtcril Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

bmtcril Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

dwong2708 commented Feb 18, 2026 •

edited

Loading

`authz_migrate_course_authoring`

`authz_rollback_course_authoring`

openedx-webhooks commented Feb 18, 2026 •

edited

Loading