From 652390874d4eab00d93b0954663a3ede1ee8378b Mon Sep 17 00:00:00 2001
From: sarina <sarina@axim.org>
Date: Tue, 24 Mar 2026 13:42:58 -0400
Subject: [PATCH] Update and refactor XQueue documentation

---
 .../exercise_tools/about_external_graders.rst |  46 +--
 .../exercise_tools/add_external_grader.rst    |  74 +++-
 .../navigation/components_activities.rst      |   1 -
 .../external_grader_requirements.rst          | 231 ------------
 source/site_ops/how-tos/enable_xqueue.md      | 339 ++++++++++++++++++
 .../references/xqueue_custom_watcher.rst      | 101 ++++++
 .../references/xqueue_external_grader.rst     | 179 +++++++++
 7 files changed, 693 insertions(+), 278 deletions(-)
 delete mode 100644 source/educators/references/course_development/exercise_tools/external_grader_requirements.rst
 create mode 100644 source/site_ops/how-tos/enable_xqueue.md
 create mode 100644 source/site_ops/references/xqueue_custom_watcher.rst
 create mode 100644 source/site_ops/references/xqueue_external_grader.rst

diff --git a/source/educators/concepts/exercise_tools/about_external_graders.rst b/source/educators/concepts/exercise_tools/about_external_graders.rst
index bcb39a96d..38e8a619a 100644
--- a/source/educators/concepts/exercise_tools/about_external_graders.rst
+++ b/source/educators/concepts/exercise_tools/about_external_graders.rst
@@ -62,59 +62,19 @@ following example.
  :alt: A learner's view of a programming problem that uses an external grader,
      with an incorrect result.
 
-.. _External Grader Requirements:
 
 External Grader Requirements
 ============================
 
-The course team builds and deploys the external grader.
+Your site operations team :ref:`builds and deploys the external grader <Enable XQueue>`.
 
-When you build your external grader, keep the following requirements in mind.
-
-* To communicate with XQueue, the grader must accept and return JSON objects.
-  For more information, see :ref:`XQueue JSON Objects`.
-
-* The external grader must actively retrieve, or pull, submissions from the
-  XQueue through a RESTful interface at regular intervals.
-
-* The grader must be scalable. Many learners might submit responses at one
-  time, such as shortly before an exam is due. The grader must be able to
-  process many submissions in a limited time, without failure or unexpected
-  delays.
-
-* The grader must not constantly send queries unless the grader detects that
-  the ``queuelen`` value is growing. If XQueue receives too many requests from
-  a grader, the XQueue system administrator may apply throttling to the grader.
-
-* The grader must implement security features.
-
-  You are responsible for the server that runs the code that learners submit.
-  Your system must protect against learners who might submit malicious code and
-  ensure that the external grader runs only code that is relevant to the course
-  problems. Your specific security implementation depends on the programming
-  language that you are using and your deployment architecture. You must ensure
-  that malicious code will not damage your server.
-
-
-* You must have a plan to immediately notify the team that operates your
-  grader, as well as your Open edX system administrator, if the grader fails.
-  You must also have a process to quickly identify the cause of the failure,
-  whether the problem is with your grader or XQueue.
-
-  If you know the grader will be unavailable at a certain time for maintenance,
-  you should :ref:`add a course update <Add a Course Update>`.
-
-* You must test the grader thoroughly before your course starts. Be sure to
-  test incorrect code as well as correct code to ensure that the grader
-  responds with appropriate scores and messages.
 
 .. seealso::
- 
-
- :ref:`External Grader Problem Requirements` (reference)
 
  :ref:`Add an External Grader Problem` (how-to)
 
+ :ref:`Enable XQueue` (site operators how-to)
+
 
 **Maintenance chart**
 
diff --git a/source/educators/how-tos/course_development/exercise_tools/add_external_grader.rst b/source/educators/how-tos/course_development/exercise_tools/add_external_grader.rst
index e7d21eaa2..8887947f1 100644
--- a/source/educators/how-tos/course_development/exercise_tools/add_external_grader.rst
+++ b/source/educators/how-tos/course_development/exercise_tools/add_external_grader.rst
@@ -15,7 +15,7 @@ To create a code response problem in Studio, follow these steps.
 
 #. In the new component, select **Edit**.
 
-#. In the problem editor, enter the online learning XML (OLX) definition for
+#. In the problem editor, enter the :ref:`online learning XML (OLX) definition <OLX Definition>` for
    the problem that you created.
 
 #. Select **Save**.
@@ -23,16 +23,84 @@ To create a code response problem in Studio, follow these steps.
 #. Test the problem in the LMS.
 
 .. note::
+
    To validate your external grader and test a problem, you must view the
    component in a published unit in the LMS. If you test a problem in Studio,
    you receive an “Error: No grader has been set up for this problem” message.
 
+.. _OLX Definition:
+
+OLX Definition
+==============
+
+To create an external grader problem in Studio, you create an Open Learning XML
+(OLX) definition of the problem, and then add the code to a problem component.
+
+.. note::
+
+   Your site operations team will need to first :ref:`Enable XQueue`, and then give you the ``queuename`` to use in your problem.
+
+The OLX definition of a problem contains the following information.
+
+* A ``queuename`` attribute that specifies the name of the XQueue that your site operations team
+  created.
+
+* A ``<label>`` element that contains the instructions for the problem.
+
+* The type of input that the problem accepts, specified as one of two elements.
+
+  * ``<textbox>``: The learner enters code in a browser field while the learner
+    views the course unit.
+
+  * ``<filesubmission>``: The learner  attaches and submits a code file in the
+    unit.
+
+* (optional) An element that contains a JSON object that you send to the
+  external grader. For example, you can use the ``<grader_payload>`` element to
+  tell the grader which tests to run for a problem.
+
+The following example shows the OLX definition of a problem that uses an
+external grader.
+
+::
+
+  <problem>
+    <coderesponse queuename="my_course_queue">
+      <label>Write a program that prints "hello world".</label>
+      <textbox rows="10" cols="80" mode="python" tabsize="4"/>
+      <codeparam>
+        <initial_display>
+          # students write your program here
+          print ""
+        </initial_display>
+        <answer_display>
+          print "hello world"
+        </answer_display>
+        <grader_payload>
+          {"output": "hello world", "max_length": 2}
+        </grader_payload>
+      </codeparam>
+    </coderesponse>
+  </problem>
+
+.. _Testing the Grader:
+
+Testing the Grader
+==================
+
+You must test the grader thoroughly, via the LMS interface, before your course
+starts. Be sure to test incorrect code as well as correct code to ensure that
+the grader responds with appropriate scores and messages.
+
+If you know the grader will be unavailable at a certain time for maintenance,
+you might consider :ref:`adding a course update <Add a Course Update>`.
+
+
 .. seealso::
- 
 
  :ref:`About External Grader Problems` (concept)
 
- :ref:`External Grader Problem Requirements` (reference)
+ :ref:`Enable XQueue` (site operators how-to)
 
 
 **Maintenance chart**
diff --git a/source/educators/navigation/components_activities.rst b/source/educators/navigation/components_activities.rst
index b5040b082..63bc62a75 100644
--- a/source/educators/navigation/components_activities.rst
+++ b/source/educators/navigation/components_activities.rst
@@ -127,7 +127,6 @@ External Grader
    :glob:
 
    ../concepts/exercise_tools/about_external_graders.rst
-   ../references/course_development/exercise_tools/external_grader_requirements.rst
    ../how-tos/course_development/exercise_tools/add_external_grader.rst
 
 Gene Explorer Tool
diff --git a/source/educators/references/course_development/exercise_tools/external_grader_requirements.rst b/source/educators/references/course_development/exercise_tools/external_grader_requirements.rst
deleted file mode 100644
index ac2b9c9f2..000000000
--- a/source/educators/references/course_development/exercise_tools/external_grader_requirements.rst
+++ /dev/null
@@ -1,231 +0,0 @@
-.. _External Grader Problem Requirements:
-
-External Grader Problem Requirements
-####################################
-
-.. tags:: educator, reference
-
-An external grader problem in Studio must have the following requirements.
-
-* A :ref:`GNU PG key <GPG Key>`.
-* An :ref:`XQueue name <XQueue Name>`.
-* :ref:`XQueue JSON objects <XQueue JSON Objects>`.
-* An :ref:`external grader <External Grader Requirements>` that meets platform
-  requirements.
-* An :ref:`OLX definition <OLX Definition>` for the external grader.
-
-.. _GPG Key:
-
-GPG Key
-*******
-
-Before you can add an external grader problem, you must obtain a public GNU
-Privacy Guard (GPG) key. For information about how to obtain a GPG key, see the
-`GnuPG website`_.
-
-.. _XQueue Name:
-
-XQueue Name
-***********
-
-The external grader problems in your course must use a specific XQueue name.
-You create the name for the XQueue that your course uses when you request
-account credentials.
-
-To request account credentials, contact the system administrator for your
-instance of the Open edX platform.
-
-
-.. _Testing the XQueue Credentials:
-
-Testing Your XQueue Credentials
-*******************************
-
-We strongly recommend that you test your XQueue credentials when you receive
-them. To test your XQueue credentials, run the following commands at a command
-prompt. Replace the placeholder values with the values for your credentials.
-
-::
-
-  curl -v -d "username=&password=" "https://xqueue.edx.org/xqueue/login/"
-  curl -v -b "sessionid=returnedbylogin"   "https://xqueue.edx.org/xqueue/get_queuelen/?queue_name=your_q"
-
-  curl -v -d "username=&password=" "https://xqueue.edx.org/xqueue/login/"
-  curl -v -b "sessionid=returnedbylogin"   "https://xqueue.edx.org/xqueue/get_queuelen/?queue_name=your_queue_name"
-
-.. _XQueue JSON Objects:
-
-===================
-XQueue JSON Objects
-===================
-
-Both the learner submission that XQueue sends to the grader, and the response
-that the grader sends to XQueue, are JSON objects.
-
-.. note::
-  XQueue does not send the learner ID to the external grader. Your grader
-  cannot access IDs or associate learner IDs with submissions.
-
-.. _XQueue Learner Submissions:
-
-Learner Submissions
-*******************
-
-The grader must receive a JSON object as a learner submission. The JSON object
-has the following keys.
-
-* ``xqueue_header``: A dictionary that the grader uses to identify the
-  submission when the grader returns the submission to XQueue. Do not edit this
-  dictionary. Return this dictionary to XQueue in the same ``xqueue_header``
-  part of the JSON object.
-
-* ``xqueue_files``: A dictionary of key/value pairs that contains a list of
-  files that the learner submitted. In this dictionary, each key is a file
-  name, and each value is the location of the file.
-
-* ``xqueue_body``: A dictionary that contains the actual submission as JSON.
-
-  * ``student_info``: A dictionary that contains the following information
-    about the student in relation to this submission.
-
-    * ``anonymous_student_id``: A string that contains an anonymized identifier
-      of the student.
-
-    * ``submission_time``: A string that contains a timestamp with the time of
-      submission in ``YYYYMMDDHHMMSS`` format.
-
-    * ``random_seed``: If a randomization script is attached to the problem,
-      ``random_seed`` is an integer that contains the seed that initializes the
-      randomization script.
-
-  * ``student_response``: A string that contains the learner’s code submission.
-    A learner can submit code by entering a string in the LMS or by attaching a
-    file. XQueue stores files that learners upload in ``xqueue_files``.
-
-  * ``grader_payload``: An optional string that you can specify when you create
-    the problem. For more information, see :ref:`Add an External Grader Problem`.
-
-An example JSON object for a learner submission follows.
-
-::
-
-  {
-    "xqueue_header": {
-      "submission_id": 72,
-      "submission_key": "ffcd933556c926a307c45e0af5131995"
-    }
-    "xqueue_files": {
-      "helloworld.c": "http://download.location.com/helloworld.c"
-    }
-    "xqueue_body":
-    "{
-      "student_info": {
-        "anonymous_student_id": "106ecd878f4148a5cabb6bbb0979b730",
-        "submission_time": "20160324104521",
-        "random_seed": 334
-      },
-      "student_response": "def double(x):\n return 2*x\n",
-      "grader_payload": "problem_2"
-     }"
-  }
-
-
-.. _XQueue External Grader Responses:
-
-External Grader Responses
-*************************
-
-After the grader runs tests and records the results for a submission, the
-grader must return information by posting a JSON response. The JSON string
-contains a value that indicates the following information.
-
-* Whether the submission was correct.
-* The score for the problem.
-* Any message that the tests create.
-
-In the following example external grader response, the learner’s submission was
-correct, the score was 1, and the tests created a brief message.
-
-::
-
-  {
-  “xqueue_header”: {
-    Identical to what was received from the xqueue
-  },
-  “xqueue_body”: {
-   "correct": true,
-   "score": 1,
-   "msg": "<p>The code passed all tests.</p>"
-  }
-  }
-
-.. _OLX Definition:
-
-==============
-OLX Definition
-==============
-
-To create an external grader problem in Studio, you create an Open Learning XML
-(OLX) definition of the problem, and then add the code to a problem component.
-
-The OLX definition of a problem contains the following information.
-
-* A ``queuename`` attribute that specifies the name of the XQueue that you
-  created. For more information, see :ref:`XQueue Name`.
-
-* A ``<label>`` element that contains the instructions for the problem.
-
-* The type of input that the problem accepts, specified as one of two elements.
-
-  * ``<textbox>``: The learner enters code in a browser field while the learner
-    views the course unit.
-
-  * ``<filesubmission>``: The learner  attaches and submits a code file in the
-    unit.
-
-* (optional) An element that contains a JSON object that you send to the
-  external grader. For example, you can use the ``<grader_payload>`` element to
-  tell the grader which tests to run for a problem.
-
-The following example shows the OLX definition of a problem that uses an
-external grader.
-
-::
-
-  <problem>
-    <coderesponse queuename="my_course_queue">
-      <label>Write a program that prints "hello world".</label>
-      <textbox rows="10" cols="80" mode="python" tabsize="4"/>
-      <codeparam>
-        <initial_display>
-          # students write your program here
-          print ""
-        </initial_display>
-        <answer_display>
-          print "hello world"
-        </answer_display>
-        <grader_payload>
-          {"output": "hello world", "max_length": 2}
-        </grader_payload>
-      </codeparam>
-    </coderesponse>
-  </problem>
-
-.. seealso::
- 
-
- :ref:`About External Grader Problems` (concept)
-
- :ref:`Add an External Grader Problem` (how-to)
-
-
-
-
-
-**Maintenance chart**
-
-+--------------+-------------------------------+----------------+--------------------------------+
-| Review Date  | Working Group Reviewer        |   Release      |Test situation                  |
-+--------------+-------------------------------+----------------+--------------------------------+
-|              |                               |                |                                |
-+--------------+-------------------------------+----------------+--------------------------------+
diff --git a/source/site_ops/how-tos/enable_xqueue.md b/source/site_ops/how-tos/enable_xqueue.md
new file mode 100644
index 000000000..507d64905
--- /dev/null
+++ b/source/site_ops/how-tos/enable_xqueue.md
@@ -0,0 +1,339 @@
+(Enable XQueue)=
+
+# Enable and Test Event Bus–Based XQueue Submissions
+
+```{tags}
+site operator, reference
+```
+
+This guide explains how to enable and test **event bus–based XQueue submissions** in `openedx-platform`.
+It is written for Open edX contributors and operators who want to validate event-driven external grading on the `master` branch.
+
+```{contents} Contents
+:depth: 1
+:local:
+```
+
+## Architecture Overview
+
+With event bus enabled, submission flow changes from direct polling to event-driven routing:
+
+Learner Submission
+
+→ LMS stores submission
+
+→ LMS publishes submission event
+
+→ Event bus distributes event
+
+→ XQueue worker / watcher consumes event
+
+→ Watcher posts result via edx-submissions API
+
+→ LMS updates grade
+
+The watcher authenticates using a Django superuser that must belong to the `xqueue` group.
+
+---
+
+## Prerequisites
+
+* Local clone of `openedx-platform` (master branch recommended)
+* Custom watcher script (e.g., {ref}`XQueue Custom Watcher`)
+* Django superuser account
+* Superuser added to group named `xqueue`
+* Event bus enabled in LMS settings
+* edx-submissions service available
+
+---
+
+## Environment Setup
+
+### Option A (Using Tutor (Recommended Modern Setup))
+
+Repository reference: [https://github.com/overhangio/tutor](https://github.com/overhangio/tutor)
+
+### Step 1. Install Tutor
+
+```bash
+pip install tutor
+```
+
+Initialize:
+
+```bash
+tutor local quickstart
+```
+
+Start platform:
+
+```bash
+tutor local start
+```
+
+---
+
+### Step 2. Create Superuser
+
+```bash
+tutor local run lms ./manage.py createsuperuser
+```
+
+---
+
+### Step 3. Create `xqueue` Group
+
+```bash
+tutor local run lms ./manage.py shell
+```
+
+Then:
+
+```python
+from django.contrib.auth.models import Group
+Group.objects.get_or_create(name="xqueue")
+```
+
+Add user to group:
+
+```python
+from django.contrib.auth import get_user_model
+User = get_user_model()
+user = User.objects.get(username="your_username")
+user.groups.add(Group.objects.get(name="xqueue"))
+```
+
+---
+
+### Step 4. Ensure Event Bus is Running
+
+Tutor uses RabbitMQ by default.
+
+Verify:
+
+```bash
+tutor local ps
+```
+
+RabbitMQ should be listed.
+
+---
+
+### Step 5. Enable XQueue Event Bus Waffle Flag
+
+Open LMS admin:
+
+```
+http://localhost:8000/admin
+```
+
+Go to:
+
+Waffle → Flags
+
+Create flag:
+
+Name: `enable_xqueue_event_bus`
+
+Active: True
+
+Rollout: 100
+
+Optional: course override via Waffle → Overrides.
+
+---
+
+### Option B (Using Deprecated Legacy Devstack)
+
+Repository reference: [https://github.com/edx/devstack](https://github.com/edx/devstack)
+
+### Step 1. Clone and Start Devstack
+
+```bash
+git clone https://github.com/edx/devstack.git
+cd devstack
+make dev.up
+```
+
+This brings up LMS, CMS, MySQL, Mongo, RabbitMQ, etc.
+
+To rebuild after changes:
+
+```bash
+make dev.build
+make dev.up
+```
+
+---
+
+### Step 2. Create Superuser
+
+```bash
+make lms-shell
+```
+
+Inside container:
+
+```bash
+./manage.py createsuperuser
+```
+
+---
+
+### Step 3. Create `xqueue` Group
+
+Inside LMS shell:
+
+```python
+from django.contrib.auth.models import Group
+Group.objects.get_or_create(name="xqueue")
+```
+
+Add superuser to group:
+
+```python
+from django.contrib.auth import get_user_model
+User = get_user_model()
+user = User.objects.get(username="your_username")
+user.groups.add(Group.objects.get(name="xqueue"))
+```
+
+---
+
+### Step 4. Enable Event Bus
+
+Ensure RabbitMQ container is running:
+
+```bash
+docker ps | grep rabbit
+```
+
+If needed:
+
+```bash
+make dev.up
+```
+
+Confirm event bus settings in LMS environment file.
+
+---
+
+## Create Advanced `code_response` Problem
+
+In Studio, add Advanced problem with:
+
+```xml
+<problem display_name="XQueue Event Bus Test Problem">
+  <response
+      response_type="code_response"
+      label="Enter any code"
+      language="python"
+      max_attempts="5"
+      grader="xqueue">
+  </response>
+</problem>
+```
+
+Ensure:
+
+* `grader="xqueue"`
+* The course is published
+
+---
+
+## Running the Custom Watcher
+
+Ensure credentials inside watcher:
+
+```python
+LMS_URL = "http://localhost:8000"
+USERNAME = "admin"
+PASSWORD = "password"
+```
+
+Run:
+
+```bash
+python custom_watcher.py
+```
+
+Expected output:
+
+Connected to LMS
+Polling for jobs
+Graded submission with score = 1
+
+---
+
+## Submit as Learner
+
+1. Log in as learner
+2. Open problem
+3. Submit response
+4. Wait a few seconds
+
+You should see score update automatically.
+
+---
+
+## Verification and Debugging
+
+### Check Submissions in Django Shell
+
+```python
+from submissions.models import Submission
+Submission.objects.all()
+```
+
+### Check Logs
+
+Tutor:
+
+```bash
+tutor local logs lms
+```
+
+Legacy Devstack:
+
+```bash
+docker logs lms
+```
+
+### Common Issues
+
+403 Forbidden → User not in xqueue group
+
+No grading → Watcher not running
+
+No event → Waffle flag disabled
+
+Auth failure → Wrong credentials
+
+---
+
+## Final Checklist
+
+* Tutor (or Devstack) running
+* Superuser created
+* xqueue group exists
+* User added to xqueue group
+* Waffle flag enabled
+* Advanced problem created
+* Watcher running
+* Submission graded successfully
+
+---
+
+```{seealso}
+{ref}`XQueue Reference` (reference)
+
+{ref}`About External Grader Problems` (concept)
+
+{ref}`Add an External Grader Problem` (how-to)
+```
+
+**Maintenance Chart**
+
+| Review Date | Working Group Reviewer | Release | Test Situation |
+|-------------|------------------------|---------|----------------|
+| 2025-03-25  | Usama S                |Verawood | Pass           |
diff --git a/source/site_ops/references/xqueue_custom_watcher.rst b/source/site_ops/references/xqueue_custom_watcher.rst
new file mode 100644
index 000000000..ce17d6986
--- /dev/null
+++ b/source/site_ops/references/xqueue_custom_watcher.rst
@@ -0,0 +1,101 @@
+.. _XQueue Custom Watcher:
+
+XQueue Custom Watcher Script
+############################
+
+As part of :ref:`enabling XQueue submissions <Enable XQueue>`, you'll need to
+develop a custom Python script to evaluate a learner's submission. What follows
+is an example of one such script.
+
+
+.. code-block:: python
+
+   '''
+   Custom script to evaluate learner submissions using event bus.
+   Set to always return ok for a submission. 
+
+   Note: Needs to be placed inside xqueue-watcher at root for work.
+   '''
+   import json
+   import logging
+
+   from xqueue_watcher.client import XQueueClient
+
+   logging.basicConfig(
+      level=logging.INFO,
+      format="%(asctime)s %(levelname)s %(name)s: %(message)s"
+   )
+   log = logging.getLogger("mini-watcher")
+
+   def always_ok_handler(content: dict) -> dict:
+      """
+      content structure (from /xqueue/get_submission/):
+         {
+         "xqueue_body": "<json str>",
+         "xqueue_header": "<json str>",
+         "xqueue_files": "<json str>"
+         }
+
+      We ignore everything and return a valid result body the LMS understands.
+      """
+      try:
+         body = json.loads(content.get("xqueue_body", "{}"))
+         # Optional: peek at what student sent
+         student_response = body.get("student_response")
+         log.info("Grading submission_id=%s (dummy OK). student_response=%r",
+                  json.loads(content["xqueue_header"]).get("submission_id"), student_response)
+      except Exception:
+         pass
+
+      # This dict becomes the JSON sent as 'xqueue_body' to /xqueue/put_result/
+      return {
+         "correct": True,
+         "score": 1.0,
+         "msg": "<div class='result-output result-correct'><h4>Graded OK</h4>"
+                  "<pre>Minimal watcher: accepted.</pre></div>"
+      }
+
+   def main():
+      # Adjust to your values
+      QUEUE_NAME = "openedx"                      
+      XQUEUE_URL = "http://local.openedx.io:8000" 
+      XQUEUE_AUTH = ("abdulrehman", "rehman123")  
+
+      client = XQueueClient(
+         queue_name=QUEUE_NAME,
+         xqueue_server=XQUEUE_URL,
+         xqueue_auth=XQUEUE_AUTH,
+         http_basic_auth=None,
+         requests_timeout=5,
+         poll_interval=1,
+         login_poll_interval=5,
+         follow_client_redirects=False,
+      )
+
+      # register our trivial handler
+      client.add_handler(always_ok_handler)
+
+      # run forever (Ctrl+C to stop)
+      client.run()
+
+   if __name__ == "__main__":
+      main()
+
+.. seealso::
+ 
+ :ref:`Enable XQueue` (how-to)
+
+ :ref:`XQueue Reference` (reference)
+
+ :ref:`About External Grader Problems` (concept)
+
+ :ref:`Add an External Grader Problem` (how-to)
+
+
+**Maintenance chart**
+
++--------------+-------------------------------+----------------+--------------------------------+
+| Review Date  | Working Group Reviewer        |   Release      |Test situation                  |
++--------------+-------------------------------+----------------+--------------------------------+
+| 2025-03-25   |  Usama S                      |  Verawood      |  Pass                          |
++--------------+-------------------------------+----------------+--------------------------------+
\ No newline at end of file
diff --git a/source/site_ops/references/xqueue_external_grader.rst b/source/site_ops/references/xqueue_external_grader.rst
new file mode 100644
index 000000000..c87b92b11
--- /dev/null
+++ b/source/site_ops/references/xqueue_external_grader.rst
@@ -0,0 +1,179 @@
+.. _XQueue Reference:
+
+XQueue Reference
+############################
+
+.. tags:: site operator, how-to
+
+An external grader problem requires :ref:`Enable XQueue` before it can be defined and published in Studio.
+
+This reference guide details external grader requirements and technical specifications of XQueue submissions.
+
+.. contents:: 
+  :local:
+  :depth: 1
+
+Once properly set up, an :ref:`OLX definition <OLX Definition>` for the external grader can be defined in Studio.
+
+.. _External Grader Requirements:
+
+External Grader Requirements
+============================
+
+When you build your external grader, keep the following requirements in mind.
+
+* To communicate with XQueue, the grader must accept and return JSON objects.
+  For more information, see :ref:`XQueue JSON Objects`.
+
+* The external grader must actively retrieve, or pull, submissions from the
+  XQueue through a RESTful interface at regular intervals.
+
+* The grader must be scalable. Many learners might submit responses at one
+  time, such as shortly before an exam is due. The grader must be able to
+  process many submissions in a limited time, without failure or unexpected
+  delays.
+
+* The grader must not constantly send queries unless the grader detects that
+  the ``queuelen`` value is growing. If XQueue receives too many requests from
+  a grader, the XQueue system administrator may apply throttling to the grader.
+
+* The grader must implement security features.
+
+  You are responsible for the server that runs the code that learners submit.
+  Your system must protect against learners who might submit malicious code and
+  ensure that the external grader runs only code that is relevant to the course
+  problems. Your specific security implementation depends on the programming
+  language that you are using and your deployment architecture. You must ensure
+  that malicious code will not damage your server.
+
+
+* You must have a plan to immediately notify the team that operates your
+  grader, as well as your Open edX system administrator, if the grader fails.
+  You must also have a process to quickly identify the cause of the failure,
+  whether the problem is with your grader or XQueue.
+
+  If you know the grader will be unavailable at a certain time for maintenance,
+  you might consider contacting course teams so they can :ref:`add a course update <Add a Course Update>`.
+
+.. _XQueue JSON Objects:
+
+XQueue JSON Objects
+===================
+
+Both the learner submission that XQueue sends to the grader, and the response
+that the grader sends to XQueue, are JSON objects.
+
+.. note::
+  XQueue does not send the learner ID to the external grader. Your grader
+  cannot access IDs or associate learner IDs with submissions.
+
+.. _XQueue Learner Submissions:
+
+Learner Submissions
+*******************
+
+The grader must receive a JSON object as a learner submission. The JSON object
+has the following keys.
+
+* ``xqueue_header``: A dictionary that the grader uses to identify the
+  submission when the grader returns the submission to XQueue. Do not edit this
+  dictionary. Return this dictionary to XQueue in the same ``xqueue_header``
+  part of the JSON object.
+
+* ``xqueue_files``: A dictionary of key/value pairs that contains a list of
+  files that the learner submitted. In this dictionary, each key is a file
+  name, and each value is the location of the file.
+
+* ``xqueue_body``: A dictionary that contains the actual submission as JSON.
+
+  * ``student_info``: A dictionary that contains the following information
+    about the student in relation to this submission.
+
+    * ``anonymous_student_id``: A string that contains an anonymized identifier
+      of the student.
+
+    * ``submission_time``: A string that contains a timestamp with the time of
+      submission in ``YYYYMMDDHHMMSS`` format.
+
+    * ``random_seed``: If a randomization script is attached to the problem,
+      ``random_seed`` is an integer that contains the seed that initializes the
+      randomization script.
+
+  * ``student_response``: A string that contains the learner’s code submission.
+    A learner can submit code by entering a string in the LMS or by attaching a
+    file. XQueue stores files that learners upload in ``xqueue_files``.
+
+  * ``grader_payload``: An optional string that you can specify when you create
+    the problem. For more information, see :ref:`Add an External Grader Problem`.
+
+An example JSON object for a learner submission follows.
+
+::
+
+  {
+    "xqueue_header": {
+      "submission_id": 72,
+      "submission_key": "ffcd933556c926a307c45e0af5131995"
+    }
+    "xqueue_files": {
+      "helloworld.c": "http://download.location.com/helloworld.c"
+    }
+    "xqueue_body":
+    "{
+      "student_info": {
+        "anonymous_student_id": "106ecd878f4148a5cabb6bbb0979b730",
+        "submission_time": "20160324104521",
+        "random_seed": 334
+      },
+      "student_response": "def double(x):\n return 2*x\n",
+      "grader_payload": "problem_2"
+     }"
+  }
+
+
+.. _XQueue External Grader Responses:
+
+External Grader Responses
+*************************
+
+After the grader runs tests and records the results for a submission, the
+grader must return information by posting a JSON response. The JSON string
+contains a value that indicates the following information.
+
+* Whether the submission was correct.
+* The score for the problem.
+* Any message that the tests create.
+
+In the following example external grader response, the learner's submission was
+correct, the score was 1, and the tests created a brief message.
+
+::
+
+  {
+  “xqueue_header”: {
+    Identical to what was received from the xqueue
+  },
+  “xqueue_body”: {
+      "correct": true,
+      "score": 1,
+      "msg": "<p>The code passed all tests.</p>"
+   }
+  }
+
+
+.. seealso::
+ 
+ :ref:`Enable XQueue`
+
+ :ref:`About External Grader Problems` (concept)
+
+ :ref:`Add an External Grader Problem` (how-to)
+
+
+**Maintenance chart**
+
++--------------+-------------------------------+----------------+--------------------------------+
+| Review Date  | Working Group Reviewer        |   Release      |Test situation                  |
++--------------+-------------------------------+----------------+--------------------------------+
+| 2025-03-25   |  Usama S                      |  Verawood      |  Pass                          |
++--------------+-------------------------------+----------------+--------------------------------+
\ No newline at end of file