Skip to content

Commit 385e76d

Browse files
rodmgwgurodmgwgu
committed
docs: add ADR on Course Authoring Migration Process Details
1 parent ced9562 commit 385e76d

2 files changed

Lines changed: 161 additions & 0 deletions

File tree

‎CHANGELOG.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Added
1919

2020
* ADR on the AuthZ for Course Authoring implementation plan.
2121
* ADR on the AuthZ for Course Authoring Feature Flag Implementation Details.
22+
* ADR on the AuthZ for Course Authoring Migration Process Details.
2223

2324
0.20.0 - 2025-11-27
2425
********************

‎docs/decisions/0011-course-authoring-migration-process.rst‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
0011: AuthZ for Course Authoring - Migration Process Details
2+
#############################################################
3+
4+
Status
5+
******
6+
7+
**Draft**
8+
9+
Context
10+
*******
11+
12+
The legacy course authoring roles and permissions system stores role assignments in the
13+
MySQL ``student_courseaccessrole`` table, represented by the `CourseAccessRole model`_.
14+
15+
To preserve existing role assignments during the transition to the new openedx-authz system,
16+
we need a bidirectional data migration process that:
17+
18+
- Supports course, organization, and instance-level migrations (compatible with the feature
19+
flag functionality in `ADR 0010`_)
20+
- Enables rollback capability when the feature flag is disabled
21+
- Maintains data consistency by removing role assignments from the source system after
22+
migration
23+
- Ignores roles that exist in the new system but have no legacy equivalent
24+
25+
*Note: New system roles without legacy equivalents will be preserved but not enforced until
26+
the flag is re-enabled.*
27+
28+
29+
Decision
30+
********
31+
32+
**Automatic Migration Triggers**
33+
34+
Migration occurs immediately when the feature flag state changes:
35+
36+
- **Flag enabled**: Legacy role assignments migrate to new system and are removed from
37+
legacy system
38+
- **Flag disabled**: New system role assignments migrate to legacy system and are removed
39+
from new system
40+
41+
*Note: Roles without legacy equivalents remain in the new system and are not migrated*
42+
43+
**Forward Migration Process** (Legacy → openedx-authz)
44+
45+
- **Parameters**: Optional course or organization filter
46+
- **Process**:
47+
48+
1. Query CourseAccessRole instances matching the specified filter (or all if no filter)
49+
2. Create equivalent role assignments in openedx-authz for each CourseAccessRole
50+
3. Remove successfully migrated CourseAccessRole instances
51+
4. Execute within database transaction for consistency
52+
53+
**Rollback Migration Process** (openedx-authz → Legacy)
54+
55+
- **Parameters**: Optional course or organization filter
56+
- **Process**:
57+
58+
1. Query openedx-authz role assignments for specified scope (or all course authoring
59+
roles)
60+
2. Create equivalent CourseAccessRole assignments for roles with legacy equivalents
61+
3. Log warnings for roles without legacy equivalents (these remain in openedx-authz)
62+
4. Remove successfully migrated openedx-authz assignments
63+
5. Execute within database transaction for consistency
64+
65+
**Role Mapping**
66+
67+
The following role equivalences define the migration logic:
68+
69+
+----------------------------------+---------------------------+
70+
| Legacy Role (internal name) | New AuthZ Role* |
71+
+==================================+===========================+
72+
| Admin (instructor) | Course Admin |
73+
+----------------------------------+---------------------------+
74+
| Staff (staff) | Course Staff |
75+
+----------------------------------+---------------------------+
76+
| Limited Staff (limited_staff) | Course Limited Staff |
77+
+----------------------------------+---------------------------+
78+
| Course Data Researcher | Course Data Researcher |
79+
| (data_researcher) | |
80+
+----------------------------------+---------------------------+
81+
| Beta Testers (beta_testers) | Course Beta Tester |
82+
+----------------------------------+---------------------------+
83+
84+
*New AuthZ role names are subject to change.*
85+
86+
**Execution Methods**
87+
88+
**Automatic Execution**
89+
Django ``pre_save`` signal handlers trigger migration when flag state changes via Django
90+
Admin or management commands. See `Authoring Waffle Flag Implementation Spike`_ for details.
91+
92+
**Management Commands**
93+
94+
*Flag Management (triggers automatic migration):*
95+
96+
- Enable globally: ``./manage.py cms waffle_switch authz.enable_course_authoring on
97+
--create``
98+
- Disable globally: ``./manage.py cms waffle_switch authz.enable_course_authoring off``
99+
100+
*Manual Migration (for debugging):*
101+
102+
- Forward migration: ``./manage.py cms authz_migrate_course_authoring
103+
[course_key|org_name]``
104+
- Rollback migration: ``./manage.py cms authz_rollback_course_authoring
105+
[course_key|org_name]``
106+
107+
108+
Consequences
109+
************
110+
111+
- Comprehensive migration documentation will be created for site operators
112+
- Database transactions ensure data consistency during migration operations
113+
- Site operators must test migration processes before legacy system deprecation
114+
- Automatic migration will execute for remaining courses when the feature flag is
115+
deprecated post-Willow (Specific mechanism for automatic execution will be defined later)
116+
117+
Rejected Alternatives
118+
*********************
119+
120+
**Instance-level migration only**
121+
Prevents granular testing on individual courses or organizations, increasing adoption
122+
risk.
123+
124+
**Management command-only approach**
125+
Creates operational overhead and increases risk of inconsistent role assignments during
126+
transition.
127+
128+
**Dual-write approach**
129+
Maintaining role assignments in both systems simultaneously would create data
130+
synchronization complexity and potential inconsistencies.
131+
132+
**Copy-only migration**
133+
Keeping role assignments in both systems would lead to data duplication, confusion about
134+
source of truth, and potential security risks.
135+
136+
**No rollback capability**
137+
Would make migration irreversible and increase adoption risk for site operators.
138+
139+
References
140+
**********
141+
142+
* `Understand current course authoring roles and permissions logic Spike`_
143+
* `Authoring Waffle Flag Implementation Spike`_
144+
* `CourseAccessRole model`_
145+
* `ADR 0010`_
146+
147+
148+
.. _Understand current course authoring roles and permissions logic Spike:
149+
https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5639602177/Spike+-+RBAC+AuthZ
150+
+-+Understand+current+course+authoring+roles+and+permissions+logic+and+propose+reusable
151+
+solution
152+
.. _CourseAccessRole model:
153+
https://github.com/openedx/edx-platform/blob/e6deac0cf12226c0b8d744ad17395373cfe0de03
154+
/common/djangoapps/student/models/user.py#L1046
155+
.. _ADR 0010:
156+
https://github.com/openedx/openedx-authz/blob/main/docs/decisions/0010-course-authoring
157+
-flag.rst
158+
.. _Authoring Waffle Flag Implementation Spike:
159+
https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5646221313/Spike+-+RBAC+AuthZ+-+
160+
Authoring+Waffle+Flag+Implementation

0 commit comments

Comments
 (0)