Skip to content

Commit 1b083ba

Browse files
rodmgwgurodmgwgu
authored
docs: add ADR on Course Authoring Migration Process Details (openedx#213)
* docs: add ADR on Course Authoring Migration Process Details
1 parent f284f1c commit 1b083ba

2 files changed

Lines changed: 174 additions & 0 deletions

File tree

‎CHANGELOG.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ Unreleased
1717
Added
1818
=====
1919

20+
* ADR on the AuthZ for Course Authoring Migration Process Details.
21+
2022
0.22.0 - 2026-02-19
2123
********************
2224

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

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
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+
The following legacy roles won't be handled by the migration process:
87+
88+
- finance_admin
89+
- sales_admin
90+
- library_user
91+
- ccx_coach
92+
- org_course_creator_group
93+
- course_creator_group
94+
- support
95+
96+
New planned roles for AuthZ won't be handled by the migration process.
97+
98+
**Execution Methods**
99+
100+
**Automatic Execution**
101+
Django ``pre_save`` signal handlers trigger migration when flag state changes via Django
102+
Admin or management commands. See `Authoring Waffle Flag Implementation Spike`_ for details.
103+
104+
**Management Commands**
105+
106+
*Flag Management (triggers automatic migration):*
107+
108+
- Enable globally: ``./manage.py cms waffle_switch authz.enable_course_authoring on
109+
--create``
110+
- Disable globally: ``./manage.py cms waffle_switch authz.enable_course_authoring off``
111+
112+
*Manual Migration (for debugging):*
113+
114+
- Forward migration: ``./manage.py cms authz_migrate_course_authoring
115+
[course_key|org_name]``
116+
- Rollback migration: ``./manage.py cms authz_rollback_course_authoring
117+
[course_key|org_name]``
118+
119+
120+
Consequences
121+
************
122+
123+
- Comprehensive migration documentation will be created for site operators
124+
- Database transactions ensure data consistency during migration operations
125+
- Site operators must test migration processes before legacy system deprecation
126+
- Automatic migration will execute for remaining courses when the feature flag is
127+
deprecated post-Willow (Specific mechanism for automatic execution will be defined later)
128+
129+
Rejected Alternatives
130+
*********************
131+
132+
**Instance-level migration only**
133+
Prevents granular testing on individual courses or organizations, increasing adoption
134+
risk.
135+
136+
**Management command-only approach**
137+
Creates operational overhead and increases risk of inconsistent role assignments during
138+
transition.
139+
140+
**Dual-write approach**
141+
Maintaining role assignments in both systems simultaneously would create data
142+
synchronization complexity and potential inconsistencies.
143+
144+
**Copy-only migration**
145+
Keeping role assignments in both systems would lead to data duplication, confusion about
146+
source of truth, and potential security risks.
147+
148+
**No rollback capability**
149+
Would make migration irreversible and increase adoption risk for site operators.
150+
151+
References
152+
**********
153+
154+
* `Understand current course authoring roles and permissions logic Spike`_
155+
* `Authoring Waffle Flag Implementation Spike`_
156+
* `CourseAccessRole model`_
157+
* `ADR 0010`_
158+
159+
160+
.. _Understand current course authoring roles and permissions logic Spike:
161+
https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5639602177/Spike+-+RBAC+AuthZ
162+
+-+Understand+current+course+authoring+roles+and+permissions+logic+and+propose+reusable
163+
+solution
164+
.. _CourseAccessRole model:
165+
https://github.com/openedx/edx-platform/blob/e6deac0cf12226c0b8d744ad17395373cfe0de03
166+
/common/djangoapps/student/models/user.py#L1046
167+
.. _ADR 0010:
168+
https://github.com/openedx/openedx-authz/blob/main/docs/decisions/0010-course-authoring
169+
-flag.rst
170+
.. _Authoring Waffle Flag Implementation Spike:
171+
https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5646221313/Spike+-+RBAC+AuthZ+-+
172+
Authoring+Waffle+Flag+Implementation

0 commit comments

Comments
 (0)