diff --git a/src/ol_openedx_canvas_integration/README.rst b/src/ol_openedx_canvas_integration/README.rst index de29baa6..83bbec7a 100644 --- a/src/ol_openedx_canvas_integration/README.rst +++ b/src/ol_openedx_canvas_integration/README.rst @@ -1,11 +1,11 @@ -ol_openedx_canvas_integration +Canvas Integration Plugin ============================= -A django app plugin to add ``Canvas Integration`` support in edx-platform. +A django app plugin to add Canvas integration to Open edX. **NOTE:** -Since the edx-platform’s ``Instructor Dashboard`` does not support the plugin based tabs so we had to make some changes in the edx-platform itself to add ``Canvas`` tab through the plugin. +We had to make some changes to edx-platform itself in order to add the "Canvas" tab to the instructor dashboard. The ``edx-platform`` branch/tag you're using must include below commit for ``ol-openedx-canvas-integration`` plugin to work properly: @@ -15,55 +15,58 @@ The ``edx-platform`` branch/tag you're using must include below commit for ``ol- Installation ------------ -You can install it into any Open edX instance by using any of the following two methods: +You can install this plugin into any Open edX instance by using any of the following methods: -- To get the latest stable release from PyPI + +**Option 1: Install from PyPI** .. code-block:: + # If running devstack in docker, first open a shell in LMS (make lms-shell) pip install ol-openedx-canvas-integration -- To create & install a build locally - -.. code-block:: +**Option 2: Build the package locally and install it** - # Open Terminal +Follow these steps in a terminal on your machine: - 1. Navigate to "open-edx-plugins" directory - 2. Run ./pants build # Do this if you haven’t run it already - 3. Run ./pants package :: # This will create a "dist" directory inside "open-edx-plugins" directory with ".whl" & ".tar.gz" format packages for all the "ol_openedx_*" plugins in "open-edx-plugins/src") - 4. Install the "ol-openedx-canvas-integration" using any of ".whl" or ".tar.gz" files generated in the above step +1. Navigate to ``open-edx-plugins`` directory +2. If you haven't done so already, run ``./pants build`` +3. Run ``./pants package ::``. This will create a "dist" directory inside "open-edx-plugins" directory with ".whl" & ".tar.gz" format packages for all the "ol_openedx_*" plugins in "open-edx-plugins/src") +4. Move/copy any of the ".whl" or ".tar.gz" files for this plugin that were generated in the above step to the machine/container running Open edX (NOTE: If running devstack via Docker, you can use ``docker cp`` to copy these files into your LMS container) +5. Run a shell in the machine/container running Open edX, and install this plugin using pip -Dependencies +Configuration ------------ -Once you’ve installed the plugin you will need set some configuration values as mentioned below. +**1) edx-platform configuration** +Add the following configuration values to the config file in Open edX. For any release after Juniper, that config file is ``/edx/etc/lms.yml``. These should be added to the top level. **Ask a fellow developer or devops for these values.** .. code-block:: - 1) Set the value for "CANVAS_ACCESS_TOKEN" into your environment variable # This can be done through lms.yml or private.py - 2) Set the value for "CANVAS_BASE_URL" # This will be the URL of your Canvas instance - 3) Go to Studio "http://localhost:18010" -> Open a course and navigate to "Advanced Settings" -> Set value for `canvas_course_id` # This should be the id of a course that exists on Canvas - -How To Use ----------- -1. Install ``ol-openedx-canvas-integration`` plugin & set the configurations mentioned above + CANVAS_ACCESS_TOKEN: + CANVAS_BASE_URL: -2. In Studio(``http://localhost:18010``) create/navigate to a course and create some ``graded assignments/quizzes`` +**2) Add course settings value** -3. In LMS (``http://localhost:18000``), open the above course, navigate to ``Instructor`` tab & make sure that you see ``Canvas`` underneath +1) Open your course in Studio. +2) Navigate to "Advanced Settings". +3) Add a ``canvas_course_id`` value. This should be the id of a course that exists on Canvas. -4. Clicking the ``Canvas`` tab should present you with a multiple buttons ``List enrolments on Canvas``, ``Merge enrolment list using Canvas``, ``Overload enrolment list using Canvas``, ``Push all MITx grades to Canvas``, ``List Canvas assignments`` - 4.1) Clicking ``List enrolments on Canvas`` button should list all the enrollments for the course on Canvas +How To Use +---------- - 4.2) Clicking ``Merge enrolment list using Canvas`` should enroll all the users that are present on edX. For the users that doesn’t exist on edX it will create `CourseEnrollmentAllowed` object +1. In Studio, create/navigate to a course and create some graded assignments/quizzes. +2. In LMS, open the above course, navigate to the "Instructor" tab, and make sure that you see can see a "Canvas" tab. - 4.3) Clicking ``Overload enrolment list using Canvas`` will manage both enroll and unenroll - 4.4) Clicking ``Push all MITx grades to Canvas`` will create those assignments/quizes in Canvas that don’t exist there and then it will created/update the user grades for those assignments/quizes in the Canvas (Make sure that the assignment that you’re syncing grades for has a `Published` status on Canvas) +Some of the functionality available in this tab: - 4.5) Clicking ``List Canvas assignments`` will show a dropdown of all the assignments that are present on Canvas and upon clicking an assignment in dropdown a list of grades will be printed. +- ``List enrollments on Canvas`` - Show all enrollments for the course on Canvas. +- ``Merge enrollment list using Canvas`` - Enroll all the users that are present on edX. For the users that don't exist on edX, a ``CourseEnrollmentAllowed`` object will be created. +- ``Overload enrollment list using Canvas`` - Ensure that enrollment records in edX match the enrollments in Canvas (i.e.: create any enrollments that exist in Canvas but don't exist in edX, and delete enrollments that exist in edX but not in Canvas) +- ``Push all MITx grades to Canvas`` - Ensure that Canvas has the equivalent assignments/quizzes for the course, and create/update the user grades for those assignments/quizzes in Canvas (The assignments must have a `Published` status on Canvas) +- ``List Canvas assignments`` - Show a dropdown of all the assignments that are present on Canvas, and upon selecting an assignment, show a list of grades. \ No newline at end of file