Skip to content

Commit d777a06

Browse files
UsamaSadiqUsamaSadiq
authored
Merge branch 'master' into dependabot/github_actions/actions/setup-python-6
2 parents 2303a16 + 6268d46 commit d777a06

15 files changed

Lines changed: 1932 additions & 322 deletions

‎docs/source/decisions/0003-implementation-of-views-for-external-grader-integration.rst‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
3. Implementation of XQueue Compatible Views for External Grader Integration
2+
############################################################################
3+
4+
Status
5+
******
6+
7+
**Provisional** *2025-02-21*
8+
9+
Implemented by https://github.com/openedx/edx-submissions/pull/284
10+
11+
Context
12+
*******
13+
14+
Following the creation of ExternalGraderDetail (ADR 1) and SubmissionFile (ADR 2) models, we need to implement the API
15+
endpoints that will allow external graders (xqueue-watcher) to interact with the system. The current XQueue implementation
16+
provides three critical endpoints that need to be replicated:
17+
18+
1. Authentication Service:
19+
- Secure login mechanism for external graders
20+
- Session management
21+
- CSRF handling for specific endpoints
22+
23+
2. Submission Retrieval (get_submission):
24+
- Queue-based submission distribution
25+
- Status tracking and locking mechanism
26+
- File information packaging for graders
27+
28+
3. Result Processing (put_result):
29+
- Score validation and processing
30+
- Status updates
31+
- Error handling and retry mechanisms
32+
33+
The current XQueue implementation has these services spread across multiple systems, requiring complex HTTP communication
34+
and session management. The existing workflow:
35+
36+
1. Authentication Flow:
37+
- Basic username/password authentication
38+
- Session-based token management
39+
- Manual CSRF handling for specific endpoints
40+
41+
2. Submission Processing:
42+
- Manual queue status checks
43+
- Complex state transitions
44+
- Synchronous HTTP-based file retrieval
45+
46+
3. Result Handling:
47+
- Direct database updates
48+
- Limited error recovery
49+
- Complex retry logic
50+
51+
Decision
52+
********
53+
54+
We will implement a unified service approach that brings together all the functionality needed for external grader integration. This approach will:
55+
56+
1. Simplify Authentication:
57+
- Create a more straightforward login process for external graders
58+
- Make session handling more reliable
59+
- Ensure security while reducing technical complexity
60+
61+
2. Improve Submission Handling:
62+
- Create a more efficient way to distribute submissions to graders
63+
- Track the status of submissions more reliably
64+
- Provide all necessary information to graders in a consistent format
65+
66+
3. Enhance Results Processing:
67+
- Process scores more reliably
68+
- Handle errors gracefully
69+
- Provide better feedback to both graders and the platform
70+
71+
The solution will be built as a consolidated service that external graders can interact with through standard REST API endpoints. This will make integration easier for external services while providing better monitoring and control for the platform.
72+
73+
Key Benefits:
74+
75+
1. External graders will have a single, consistent interface
76+
2. The platform will have better visibility into the grading process
77+
3. Error handling will be improved across the entire workflow
78+
4. Security will be enhanced through better authentication practices
79+
80+
This approach connects directly with the previously created data models for external graders and submission files, providing a complete end-to-end solution for the grading workflow.
81+
82+
Administrative Interface Implementation
83+
***************************************
84+
85+
The ExternalGraderDetailAdmin provides comprehensive monitoring and management capabilities:
86+
87+
Status Management
88+
-----------------
89+
90+
- Visual status badges with color coding (pending/yellow, pulled/blue, failed/red, retired/gray)
91+
- Bulk action to reset failed submissions to pending status
92+
- Status transition validation (only failed → pending allowed)
93+
- Read-only fields for data integrity
94+
95+
Search and Filtering
96+
--------------------
97+
98+
- Advanced search across queue names, pullkeys, grader files, and submission details
99+
- Filtered search including student_id, course_id, and item_id from related submissions
100+
- Optimized queryset with select_related for performance
101+
- List filters by status, queue_name, failures, and timestamps
102+
103+
Information Display
104+
-------------------
105+
106+
- Comprehensive submission information formatting (student, course, item details)
107+
- Failure count tracking for retry logic monitoring
108+
- Timestamp tracking for status changes and creation
109+
- Direct links to related submission records
110+
111+
Security and Permissions
112+
------------------------
113+
114+
- Read-only access for individual records (prevents accidental data modification)
115+
- Superuser-only deletion permissions
116+
- Change permissions enabled for bulk actions and viewing
117+
118+
Operational Features
119+
--------------------
120+
121+
- Error handling with user feedback messages for bulk operations
122+
- Database query optimization through select_related
123+
- Fieldset organization for logical information grouping
124+
- Integration with Django's admin messaging system
125+
126+
Consequences
127+
************
128+
129+
Positive:
130+
---------
131+
132+
1. Architecture:
133+
- Consolidated service endpoints
134+
- Clean separation of concerns
135+
- Improved error handling
136+
- Better session management
137+
138+
2. Security:
139+
- Robust authentication
140+
- Secure file handling
141+
- Protected state transitions
142+
143+
3. Operations:
144+
- Simplified deployment
145+
- Better monitoring capabilities
146+
- Improved error visibility
147+
- Automatic retry handling
148+
149+
4. Administrative Interface:
150+
- Comprehensive monitoring dashboard for external grader operations
151+
- Bulk recovery operations for failed submissions
152+
- Enhanced visibility into grading pipeline status
153+
- Optimized database queries for large-scale operations
154+
- User-friendly status indicators and search capabilities
155+
156+
Negative:
157+
---------
158+
159+
1. Complexity:
160+
- More complex session management
161+
- Additional state validation required
162+
- Complex transaction handling
163+
164+
2. Performance:
165+
- Additional database operations
166+
- Session verification overhead
167+
168+
3. Migration:
169+
- Changes required in external graders
170+
- New deployment procedures needed
171+
172+
References
173+
**********
174+
175+
Implementation References:
176+
177+
* XQueue ViewSet Implementation: Link to PR
178+
* External Grader Integration Guide: Link to documentation
179+
180+
Related ADRs:
181+
182+
* ADR 1: Creation of ExternalGraderDetail Model
183+
* ADR 2: File Handling Implementation
184+
185+
Documentation:
186+
187+
* XQueue API Specification
188+
* External Grader Integration Guide
189+
* Session Management Documentation
190+
191+
Architecture Guidelines:
192+
193+
* Django REST Framework Best Practices
194+
* Open edX API Guidelines

‎requirements/base.txt‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,24 +6,24 @@
66
#
77
asgiref==3.9.1
88
# via django
9-
django==4.2.23
9+
django==4.2.25
1010
# via
11-
# -c requirements/common_constraints.txt
12-
# -r requirements/base.in
11+
# -c common_constraints.txt
12+
# -r base.in
1313
# django-model-utils
1414
# djangorestframework
1515
# edx-django-release-util
1616
# jsonfield
1717
django-model-utils==5.0.0
18-
# via -r requirements/base.in
18+
# via -r base.in
1919
djangorestframework==3.16.1
20-
# via -r requirements/base.in
20+
# via -r base.in
2121
edx-django-release-util==1.5.0
22-
# via -r requirements/base.in
22+
# via -r base.in
2323
jsonfield==3.2.0
24-
# via -r requirements/base.in
24+
# via -r base.in
2525
pytz==2025.2
26-
# via -r requirements/base.in
26+
# via -r base.in
2727
pyyaml==6.0.2
2828
# via edx-django-release-util
2929
six==1.17.0

0 commit comments

Comments
 (0)