From 81ac3c1d562d6fa2fd92e9572ba09715aa34dc57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Thu, 13 Feb 2025 15:53:38 -0500 Subject: [PATCH 1/4] docs: [FC-0074] index, references and concepts style review --- docs/concepts/openedx-filters.rst | 54 +++++++++-------- docs/index.rst | 12 ++-- docs/reference/architecture-subdomains.rst | 12 +++- docs/reference/django-plugins-and-filters.rst | 27 +++++---- .../reference/documenting-filters-classes.rst | 18 ++++-- docs/reference/filters-configuration.rst | 16 +++-- docs/reference/filters-tooling.rst | 12 +++- docs/reference/filters.rst | 14 ++++- docs/reference/real-life-use-cases.rst | 59 ++++++++++++------- 9 files changed, 148 insertions(+), 76 deletions(-) diff --git a/docs/concepts/openedx-filters.rst b/docs/concepts/openedx-filters.rst index 8a09c11c..36031c03 100644 --- a/docs/concepts/openedx-filters.rst +++ b/docs/concepts/openedx-filters.rst @@ -1,20 +1,20 @@ Open edX Filters -================ +################# Overview --------- +********* As mentioned in the :doc:`docs.openedx.org:developers/concepts/hooks_extension_framework` docs, Open edX filters provide a mechanism for modifying the platform's behavior by altering runtime data or halting execution based on specific conditions. Filters allow developers to implement application flow control based on their business logic or requirements without directly modifying the application code. Throughout this document, we will refer to Open edX Filters as filters interchangeably. -What are Open edX Filters? --------------------------- +What Are Open edX Filters? +***************************** An Open edX Filter is a pipeline mechanism that executes a series of functions when configured. Each function receives input arguments, which are data used by the process in execution, and returns the same arguments, possibly modified. Given this design, filters can modify the application flow according to the specified configuration, altering or adding new behaviors during execution time. -How do Open edX Filters work? ------------------------------ +How Do Open edX Filters Work? +****************************** Open edX Filters are implemented using an accumulative pipeline mechanism, which executes a series of functions in a specific order. Each function in the pipeline receives the output of the previous function as input, allowing developers to build complex processing logic by chaining multiple functions together. The pipeline ensures that the order of execution is maintained and that the result of a previous function is available to the current one in the form of a pipeline. @@ -30,47 +30,47 @@ In this diagram, we illustrate the workflow of triggering an Open edX Filter: :align: center Components -~~~~~~~~~~ +============ -#. Application (caller): The component that calls the filter during its execution, triggering the pipeline to process the input data. Developers may have added this call to a part of the application to include different behaviors. E.g., a user enrolls in a course, triggering the `CourseEnrollmentStarted filter`_. -#. OpenEdxPublicFilter: The class that implements all methods used to manage the execution of the filter. -#. PipelineStep1...N: The pipeline steps that are executed in sequence, each processing the input data and returning potentially modified data. These steps are defined by the developer to introduce additional behaviors. E.g., a pipeline step that checks user eligibility for enrollment. +* **Application (caller):** The component that calls the filter during its execution, triggering the pipeline to process the input data. Developers may have added this call to a part of the application to include different behaviors. E.g., a user enrolls in a course, triggering the `CourseEnrollmentStarted filter`_. +* **OpenEdxPublicFilter:** This class implements all methods used to manage the execution of the filter. +* **PipelineStep1...N:** The pipeline steps that are executed in sequence, each processing the input data and returning potentially modified data. The developer defines these steps to introduce additional behaviors. E.g., a pipeline step that checks user eligibility for enrollment. Workflow -~~~~~~~~ +=========== #. An application component (caller) invokes the filter during its execution by calling the ``run_filter`` method implemented by its :term:`filter definition`. -#. The caller passes the input data to the filter through the ``run_filter`` method, this data are in-memory platform objects that the filter will process. +#. The caller passes the input data to the filter through the ``run_filter`` method. This data is an in-memory platform object that the filter will process. #. The ``run_filter`` method of the filter calls the ``OpenEdxPublicFilter.run_pipeline`` method under the hood, which manages the execution of the filter's pipeline. #. This method retrieves the configuration from ``OPEN_EDX_FILTERS_CONFIG``, which defines a list of N functions :math:`f_1, f_2, \ldots, f_{n}` that will be executed. -#. Then it executes each function in the pipeline sequentially, starting with :math:`f_1`, which processes the input arguments ``kwargs`` and applies the developer's operations, returning potentially modified arguments ``kwargs_1``. +#. Then, it executes each function in the pipeline sequentially, starting with :math:`f_1`, which processes the input arguments ``kwargs`` and applies the developer's operations, returning potentially modified arguments ``kwargs_1``. -#. The next function (if there are more than one) :math:`f_2` receives the potentially modified arguments ``kwargs_1`` and applies further operations, returning another modified set of arguments ``kwargs_2``. This process continues through the list of functions. +#. The next function (if there is more than one) :math:`f_2` receives the potentially modified arguments ``kwargs_1`` and applies further operations, returning another modified set of arguments ``kwargs_2``. This process continues through the list of functions. #. Each subsequent function receives the output from the previous function and returns its modified output until all functions have been executed. -#. At any point in the pipeline, a developer can halt execution by raising an exception, based on conditions defined in the processing logic, to stop the application flow. Let's assume that :math:`f_{2}` raises an exception instead of returning the modified arguments ``kwargs_2``. In this case, the pipeline stops, and the ``OpenEdxPublicFilter.run_pipeline`` method raises the exception to the caller as the final output. From there the caller can handle the exception as needed. +#. At any point in the pipeline, a developer can halt execution by raising an exception based on conditions defined in the processing logic to stop the application flow. Let's assume that :math:`f_{2}` raises an exception instead of returning the modified arguments ``kwargs_2``. In this case, the pipeline stops, and the ``OpenEdxPublicFilter.run_pipeline`` method raises the exception to the caller as the final output. From there, the caller can handle the exception as needed. #. If no exceptions are raised, the pipeline continues executing the functions until the final function :math:`f_{n}` has been executed. -#. The final modified arguments ``kwargs_n`` are returned to the caller, which may use them for the remaining part of its execution. +#. The final modified arguments ``kwargs_n`` are returned to the caller and may be used for the remaining part of its execution. -Each function in the pipeline has the ability to modify the input data, add new data, or halt execution based on specific conditions, such as raising exceptions if certain criteria is not met. This pipeline structure ensures that complex business logic can be applied during runtime without directly altering the application code. +Each function in the pipeline has the ability to modify the input data, add new data, or halt execution based on specific conditions, such as raising exceptions if certain criteria are not met. This pipeline structure ensures that complex business logic can be applied during runtime without directly altering the application code. Real-Life Example -~~~~~~~~~~~~~~~~~ +******************* Here's an example of the `CourseEnrollmentStarted filter`_ in action: #. A user enrolls in a course, triggering the `CourseEnrollmentStarted filter`_ by calling the ``run_filter`` method with the enrollment details. This filter processes information about the user, course, and enrollment details. -#. The ``run_pipeline`` method executes a series of functions configured in ``OPEN_EDX_FILTERS_CONFIG``, e.g. checking user eligibility for enrollment or updating the enrollment status in a third-party system. +#. The ``run_pipeline`` method executes a series of functions configured in ``OPEN_EDX_FILTERS_CONFIG``, e.g., checking user eligibility for enrollment or updating the enrollment status in a third-party system. -#. Each function can modify the input data or halt the process based on business logic, e.g. denying enrollment if the user is ineligible. +#. Each function can modify the input data or halt the process based on business logic, e.g., denying enrollment if the user is ineligible. #. The final output of the pipeline, such as the updated enrollment details, is returned to the caller, or an exception is raised if the user is not eligible. @@ -78,10 +78,10 @@ Here's an example of the `CourseEnrollmentStarted filter`_ in action: By running filters in key places of the Open edX platform, developers can extend the platform's functionality in a flexible and maintainable way. -How are Open edX Filters used? ------------------------------- +How Are Open edX Filters Used? +******************************* -Developers can implement functions in an `Open edX Django plugin`_, configure them for a particular filter in the ``OPEN_EDX_FILTERS_CONFIG`` setting, and modify the application flow when a the filter in question is invoked by the process in execution. These functions can the application's behavior by altering data, adding new data, or stopping execution by raising exceptions. For example, a filter can stop a student's enrollment if certain conditions, such as business rules, are not met. +Developers can implement functions in an `Open edX Django plugin`_, configure them for a particular filter in the ``OPEN_EDX_FILTERS_CONFIG`` setting, and modify the application flow when the filter in question is invoked by the process in execution. These functions can change the application's behavior by altering data, adding new data, or stopping execution by raising exceptions. For example, a filter can stop a student's enrollment if certain conditions, such as business rules, are not met. For more information on how to use Open edX Filters, refer to the :doc:`how-tos section <../how-tos/index>`. @@ -91,3 +91,11 @@ For more information on how to use Open edX Filters, refer to the :doc:`how-tos .. _Python Social Auth: https://python-social-auth.readthedocs.io/en/latest/pipeline.html .. _OpenEdxPublicFilter: https://github.com/openedx/openedx-filters/blob/main/openedx_filters/tooling.py#L14-L15 .. _Open edX Django plugin: https://edx.readthedocs.io/projects/edx-django-utils/en/latest/plugins/readme.html + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-13 | Maria Grimaldi | Sumac |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/index.rst b/docs/index.rst index 77047319..a2d2cba1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,17 +3,19 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Open edX Filters's documentation! -============================================ +Welcome to Open edX Filters's Documentation! +############################################# -Open edX Filters is a type of hook in the Hooks Extension Framework that allows extending the Open edX platform in a more stable and maintainable way. If you're new to this approach for extending Open edX, start by reading the :doc:`docs.openedx.org:developers/concepts/hooks_extension_framework` documentation. This documentation provides an overview of the framework's concepts and structure useful to support your adoption of Open edX Filters. +Open edX Filters is a type of hook in the Hooks Extension Framework that allows extending the Open edX platform in a more stable and maintainable way. If you're new to this approach for extending Open edX, start by reading the :doc:`docs.openedx.org:developers/concepts/hooks_extension_framework` documentation. + +This documentation provides an overview of the framework's concepts and structure to support your adoption of Open edX Filters. .. toctree:: :maxdepth: 2 :caption: Contents: concepts/index - decisions/index + reference/index how-tos/index quickstarts/index - reference/index + decisions/index \ No newline at end of file diff --git a/docs/reference/architecture-subdomains.rst b/docs/reference/architecture-subdomains.rst index 1cbbc7d6..70fc335d 100644 --- a/docs/reference/architecture-subdomains.rst +++ b/docs/reference/architecture-subdomains.rst @@ -1,10 +1,10 @@ Architecture Subdomains -======================= +######################## Currently, these are the `architecture subdomains`_ used by the Open edX Events library: +-------------------+----------------------------------------------------------------------------------------------------+ -| Subdomain name | Description | +| Subdomain Name | Description | +===================+====================================================================================================+ | Content Authoring | Allows educators to create, modify, package, annotate (tag), and share learning content. | +-------------------+----------------------------------------------------------------------------------------------------+ @@ -31,3 +31,11 @@ Here we list useful information about Open edX architecture subdomains and their .. _`Message Content Data Guidelines`: https://docs.openedx.org/projects/openedx-proposals/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html?highlight=subdomain#message-content-data-guidelines .. _`Notes on events design and subdomains`: https://github.com/openedx/openedx-events/issues/72#issuecomment-1179291340 .. _architecture subdomains: https://microservices.io/patterns/decomposition/decompose-by-subdomain.html + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-13 | Maria Grimaldi | Sumac |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/docs/reference/django-plugins-and-filters.rst b/docs/reference/django-plugins-and-filters.rst index 27390b6c..4a615017 100644 --- a/docs/reference/django-plugins-and-filters.rst +++ b/docs/reference/django-plugins-and-filters.rst @@ -1,22 +1,21 @@ Django Plugins and Filters ########################## -Django plugins is one of the most valuable extension mechanisms for the Open edX platform. In this section, we will +Django plugins are one of the most valuable extension mechanisms for the Open edX platform. In this section, we will guide you through the process of using filters inside your own plugin. -Use filters inside your plugin +Use Filters Inside Your Plugin ****************************** -Imagine you have your own registration plugin and you want to add a filter to it. The first thing you need to do is -adding ``openedx-filters`` to your requirements file. Then, you can import the registration filter and use it inside -your registration flow as it's used in the LMS registration flow. You can even add your own filters to your registration, -after implementing their definitions in your plugin. +Imagine you have your own registration plugin, and you want to add a filter to it. The first thing you need to do is +add ``openedx-filters`` to your requirements file. Then, you can import the registration filter and use it inside +your registration flow as it is used in the LMS registration flow. After implementing their definitions in your plugin, you can even add your filters to your registration. -Configure filters +Configure Filters ***************** -Filters are configured in the ``OPEN_EDX_FILTERS_CONFIG`` dictionary which can be specified in your plugin's settings +Filters are configured in the ``OPEN_EDX_FILTERS_CONFIG`` dictionary, which can be specified in your plugin's settings file. The dictionary has the following structure: .. code-block:: python @@ -34,8 +33,16 @@ file. The dictionary has the following structure: } -Create pipeline steps +Create Pipeline Steps ********************* -In your own plugin, you can create your own :term:`pipeline steps` by inheriting from ``PipelineStep`` and implementing the +In your plugin, you can create your own :term:`pipeline steps` by inheriting from ``PipelineStep`` and implementing the ``run_filter`` method. You can find examples of :term:`pipeline steps` in the ``openedx-filters-samples`` repository. See :doc:`/quickstarts/index` for more details. + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-13 | Maria Grimaldi | Sumac |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/documenting-filters-classes.rst b/docs/reference/documenting-filters-classes.rst index ced836e2..3c24f2ca 100644 --- a/docs/reference/documenting-filters-classes.rst +++ b/docs/reference/documenting-filters-classes.rst @@ -1,17 +1,17 @@ Documenting Open edX Filters Classes -==================================== +###################################### -When creating a new filter, you should document the purpose of the filter in the docstring of the filter class. This will help other developers understand the purpose of the filter and how to use it. +When creating a new filter, you should document the filter's purpose in the filter class's docstring. This will help other developers understand the purpose of the filter and how to use it. The docstring should comply with the following guidelines: - The docstring should be a triple-quoted string. - The docstring should be placed at the beginning of the class definition. -- The docstring should include a brief description of what's supposed to do. +- The docstring should include a brief description of what it is supposed to do. - The docstring should describe the purpose of the filter. - The docstring should include the filter type ``filter_type``, which is the unique identifier for the filter. -- The docstring should include the trigger information, which includes the repository, path, and function or method that triggers the filter. If for some reason the filter is triggered by multiple functions or methods, you should list them all. If it's not triggered by any function or method, you should use NA (Not Applicable). -- The docstring should include any other relevant information about the filter (e.g., it works only for legacy views not MFEs). +- The docstring should include the trigger information, which includes the repository, path, and function or method that triggers the filter. If, for some reason, the filter is triggered by multiple functions or methods, you should list them all. If it is not triggered by any function or method, you should use NA (Not Applicable). +- The docstring should include any other relevant information about the filter (e.g., it works only for legacy views, not MFEs). Consider the following example: @@ -36,3 +36,11 @@ Consider the following example: Additional Information: This filter doesn't work alongside the account MFE, only with the legacy account settings page. """ + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-13 | Maria Grimaldi | Sumac |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/filters-configuration.rst b/docs/reference/filters-configuration.rst index e214acdc..68d85faa 100644 --- a/docs/reference/filters-configuration.rst +++ b/docs/reference/filters-configuration.rst @@ -21,9 +21,9 @@ Where: - ``FILTER_TYPE`` is the :term:`filter type`. - ``fail_silently`` is a boolean flag indicating whether the pipeline should continue executing the next steps when a runtime exception is raised by a pipeline step. - - If ``True``, when a pipeline step raises a runtime exception (e.g., ``ImportError`` or ``AttributeError``) which are not intentionally raised by the developer during the filter's execution; the exception won't be propagated and the execution will resume, i.e the next steps will be executed. - - If ``False``, the exception will be propagated and the execution will stop returning control to the caller. -- ``pipeline`` is list of paths for each pipeline step. Each path is a string with the following format: ``module.path.PipelineStepClassName``. The module path is the path to the module where the pipeline step class was implemented and the class name is the name of the class that implements the ``run_filter`` method to be executed when the filter is triggered. + - If ``True``, when a pipeline step raises a runtime exception (e.g., ``ImportError`` or ``AttributeError``) that the developer does not intentionally raise during the filter’s execution, the exception will not be propagated, and the execution will resume, i.e., the next steps will be executed. + - If ``False``, the exception will be propagated, and the execution will stop returning control to the caller. +- ``pipeline`` is a list of paths for each pipeline step. Each path is a string with the following format: ``module.path.PipelineStepClassName``. The module path is the path to the module where the pipeline step class was implemented and the class name is the name of the class that implements the ``run_filter`` method to be executed when the filter is triggered. With this configuration: @@ -46,4 +46,12 @@ Triggering the filter will behave as follows: - The pipeline tooling will catch the ``AttributeError`` exception raised by the second step and continue executing the next steps. - The pipeline tooling will execute the third step successfully and then return the result. -For more details on the configuration see :doc:`../decisions/0002-hooks-filter-config-location`. +For more details on the configuration, see :doc:`../decisions/0002-hooks-filter-config-location`. + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-13 | Maria Grimaldi | Sumac |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/filters-tooling.rst b/docs/reference/filters-tooling.rst index 5838cce4..5a593766 100644 --- a/docs/reference/filters-tooling.rst +++ b/docs/reference/filters-tooling.rst @@ -1,7 +1,7 @@ Open edX Filters Tooling -======================== +########################## -Here we document the tooling available for working with Open edX filters as a developer. +These are the tooling available for working with Open edX filters as a developer. .. autoclass:: openedx_filters.tooling.OpenEdxPublicFilter :members: @@ -10,3 +10,11 @@ Here we document the tooling available for working with Open edX filters as a de .. autoclass:: openedx_filters.filters.PipelineStep :members: + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-13 | Maria Grimaldi | Sumac |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/filters.rst b/docs/reference/filters.rst index c59e115e..6c0443bb 100644 --- a/docs/reference/filters.rst +++ b/docs/reference/filters.rst @@ -1,5 +1,5 @@ Filters -======= +####### This is the list of Open edX Filters found in this repository. @@ -7,13 +7,21 @@ This is the list of Open edX Filters found in this repository. Filters can be created in other projects and plugins as well, but these default filters are guaranteed to exist. Learning Subdomain ------------------- +******************** .. automodule:: openedx_filters.learning.filters :members: Course Authoring Subdomain --------------------------- +*************************** .. automodule:: openedx_filters.course_authoring.filters :members: + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-13 | Maria Grimaldi | Sumac |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/real-life-use-cases.rst b/docs/reference/real-life-use-cases.rst index 681962f2..b1985739 100644 --- a/docs/reference/real-life-use-cases.rst +++ b/docs/reference/real-life-use-cases.rst @@ -1,50 +1,56 @@ Real-Life Use Cases for Open edX Filters -======================================== +########################################## Overview --------- +********** -As mentioned in the Hooks Extension Framework, Open edX Filters filters can be used when implementing features meant to modify the application's behavior, navigation, or user interaction. - -.. TODO: add cross-reference to Hooks Extension Framework after PR is merged docs.openedx.org/pull/599 +As mentioned in the :doc:`docs.openedx.org:developers/concepts/hooks_extension_framework`, Open edX Filters filters can be used when implementing features meant to modify the application's behavior, navigation, or user interaction. To illustrate the different solutions that can be implemented with this approach, we have compiled a list of implementations built using Open edX Filters to address various challenges. The goal of this list is to serve as a reference for extension developers to implement their own solutions based on the community's experience. Use Cases ---------- +*********** The following list of real-life use cases showcases the different ways Open edX Filters can be used to facilitate the modification of the Open edX platform behavior without modifying the codebase, only through configurations and feature implementation in plugins. Reusable LTI Configuration -************************** +=========================== When a course creator adds an LTI tool, a filter is executed to fetch reusable and pluggable LTI configurations from external plugins and display them to course creators as configuration options in Studio. This use case simplifies the setup of LTI tools by allowing reusable options to be used instead of manually setting them for each tool. -More details on `Reusable LTI Configuration`_. +More details on: + +* `Reusable LTI Configuration`_. Verification of Skills by Users -******************************* +================================= When a user enters a unit, a filter is executed to inject verification forms where users can vote on the skills they have learned. This use case helps gather feedback from users about their learning experience in the course, helping to ensure the course objectives match what learners experience. -More details on `Verification of Skills by Users`_. +More details on: + +* `Verification of Skills by Users`_. + +IDV Integration with New Vendors +================================== -IDV Integration with new Vendors -******************************** +A filter is executed to return the URL for the configured Identity Verification (IDV) vendor. When student verify their identity from their account settings, they are redirected to the IDV vendor's configured to complete the verification process. This use case can be used to integrate new IDV vendors with the Open edX platform. -A filter is executed to return the URL for the Identity Verification (IDV) vendor configured. When a student verifies their identity from their account settings, they are redirected to the IDV vendor's configured to complete the verification process. This use case can be used to integrate new IDV vendors with the Open edX platform. +More details on: -More details on `IDV Integration with new Vendors`_. +* `IDV Integration with new Vendors`_. Show Consent Warning to Users -***************************** +=============================== When a student loads an Open Response Assessment (ORA) problem, a filter is executed to display a consent warning to the student. This use case can be used to inform students about the data collection and processing that will occur when they submit their responses. This is especially useful when the data is being processed by third-party services. -More details on `Show Consent Warning to Users`_. +More details on: + +* `Show Consent Warning to Users`_. Adding Custom Tabs to the Instructor Dashboard -********************************************** +================================================= When an instructor enters the instructor dashboard, a filter is executed to modify the section tabs. This allows adding new features implemented in plugins to the instructor dashboard, such as custom reports, analytics, or other tools that help instructors manage their courses. @@ -55,7 +61,7 @@ More details on: * `Forum Digest Instructor Configurations`_. Prevent Enrollment From Unauthorized Users -****************************************** +============================================ When a student enrolls in a course, before the enrollment is completed, a filter is executed to check if the student is authorized to enroll in that course. If the student doesn't meet the conditions for enrollment, they will not be able to enroll. For instance, when the student is not part of a partner institution or doesn't have the required prerequisites. This use case can also be extended to cover login, registration, and other actions. @@ -67,16 +73,16 @@ More details on: * `Prevent Login of Users with Specific Email Domains`_. Webfilters Integration -********************** +======================== -Webfilters, as mentioned in `openedx-webhooks`_ is a type of webhook that allows you to make HTTP requests to external services and modify the application behavior depending on the response. This use case can be used to validate data with external services, such as verifying the user's subscription with a third-party service before allowing them to enroll in a course. This is a more generalized implementation of the previous use case. +Webfilters, as mentioned in `openedx-webhooks`_, are a type of webhook that allows you to make HTTP requests to external services and modify the application behavior depending on the response. This use case can be used to validate data with external services, such as verifying the user's subscription with a third-party service before allowing them to enroll in a course. This is a more generalized implementation of the previous use case. More details on `Open edX Webhooks - Webfilters`_. Schedules Filtering -******************* +===================== -When a automatic email message is scheduled to be sent to students, a filter is executed to modify the schedule. This functionality allows you to define specific criteria to determine which students will receive the email. For example, filters can check whether students have opted to receive newsletters, assess their progress in the course, evaluate their activity, or consider other relevant conditions. +When an automatic email message is scheduled to be sent to students, a filter is executed to modify the schedule. This functionality allows you to define specific criteria to determine which students will receive the email. For example, filters can check whether students have opted to receive newsletters, assess their progress in the course, evaluate their activity, or consider other relevant conditions. More details on `Schedule Filtering`_. @@ -114,3 +120,12 @@ Here are some additional use cases that can be implemented using Open edX Filter .. _Render Alternative Course About: https://github.com/lektorium-tutor/lektorium_main/blob/master/lektorium_main/tilda/pipeline.py#L15-L94 .. _Hide Course About from Users Without Memberships: https://github.com/academic-innovation/mogc-partnerships/blob/main/mogc_partnerships/pipeline.py#L53-L66 .. _Schedule Filtering: https://github.com/fccn/nau-openedx-extensions/pull/56 + + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-13 | Maria Grimaldi | Sumac |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ From d94e6ebfa312d6e228f63b43eb8f3a63432300ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Thu, 13 Feb 2025 16:02:58 -0500 Subject: [PATCH 2/4] docs: update commit --- docs/index.rst | 5 ++--- docs/reference/architecture-subdomains.rst | 2 +- docs/reference/real-life-use-cases.rst | 8 ++++---- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index a2d2cba1..c84a3ce0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,8 +6,7 @@ Welcome to Open edX Filters's Documentation! ############################################# -Open edX Filters is a type of hook in the Hooks Extension Framework that allows extending the Open edX platform in a more stable and maintainable way. If you're new to this approach for extending Open edX, start by reading the :doc:`docs.openedx.org:developers/concepts/hooks_extension_framework` documentation. - +Open edX Filters is a type of hook in the Hooks Extension Framework that allows extending the Open edX platform in a more stable and maintainable way. If you're new to this approach for extending Open edX, start by reading the :doc:`docs.openedx.org:developers/concepts/hooks_extension_framework` documentation. This documentation provides an overview of the framework's concepts and structure to support your adoption of Open edX Filters. .. toctree:: @@ -18,4 +17,4 @@ This documentation provides an overview of the framework's concepts and structur reference/index how-tos/index quickstarts/index - decisions/index \ No newline at end of file + decisions/index diff --git a/docs/reference/architecture-subdomains.rst b/docs/reference/architecture-subdomains.rst index 70fc335d..99ee614d 100644 --- a/docs/reference/architecture-subdomains.rst +++ b/docs/reference/architecture-subdomains.rst @@ -38,4 +38,4 @@ Here we list useful information about Open edX architecture subdomains and their | Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-13 | Maria Grimaldi | Sumac |Pass. | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/real-life-use-cases.rst b/docs/reference/real-life-use-cases.rst index b1985739..e725d6cf 100644 --- a/docs/reference/real-life-use-cases.rst +++ b/docs/reference/real-life-use-cases.rst @@ -18,7 +18,7 @@ Reusable LTI Configuration When a course creator adds an LTI tool, a filter is executed to fetch reusable and pluggable LTI configurations from external plugins and display them to course creators as configuration options in Studio. This use case simplifies the setup of LTI tools by allowing reusable options to be used instead of manually setting them for each tool. -More details on: +More details on: * `Reusable LTI Configuration`_. @@ -27,7 +27,7 @@ Verification of Skills by Users When a user enters a unit, a filter is executed to inject verification forms where users can vote on the skills they have learned. This use case helps gather feedback from users about their learning experience in the course, helping to ensure the course objectives match what learners experience. -More details on: +More details on: * `Verification of Skills by Users`_. @@ -36,7 +36,7 @@ IDV Integration with New Vendors A filter is executed to return the URL for the configured Identity Verification (IDV) vendor. When student verify their identity from their account settings, they are redirected to the IDV vendor's configured to complete the verification process. This use case can be used to integrate new IDV vendors with the Open edX platform. -More details on: +More details on: * `IDV Integration with new Vendors`_. @@ -45,7 +45,7 @@ Show Consent Warning to Users When a student loads an Open Response Assessment (ORA) problem, a filter is executed to display a consent warning to the student. This use case can be used to inform students about the data collection and processing that will occur when they submit their responses. This is especially useful when the data is being processed by third-party services. -More details on: +More details on: * `Show Consent Warning to Users`_. From d087d511bd599e85bacbb5fdbca87f2faf0647ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Sun, 16 Feb 2025 23:02:40 -0500 Subject: [PATCH 3/4] docs: update django-plugins-and-filters --- docs/reference/django-plugins-and-filters.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/django-plugins-and-filters.rst b/docs/reference/django-plugins-and-filters.rst index 4a615017..21d48e3b 100644 --- a/docs/reference/django-plugins-and-filters.rst +++ b/docs/reference/django-plugins-and-filters.rst @@ -32,12 +32,13 @@ file. The dictionary has the following structure: }, } +To learm more about this, visit :doc:`/reference/filters-configuration`. Create Pipeline Steps ********************* In your plugin, you can create your own :term:`pipeline steps` by inheriting from ``PipelineStep`` and implementing the -``run_filter`` method. You can find examples of :term:`pipeline steps` in the ``openedx-filters-samples`` repository. See :doc:`/quickstarts/index` for more details. +``run_filter`` method. You can find examples of :term:`pipeline steps` in the ``openedx-filters-samples`` repository. See :doc:`/quickstarts/index` for more details. To learn more about this process, visit :doc:`/how-tos/create-a-pipeline-step`. **Maintenance chart** From 3ca52f46f99b184d2af5668808d44934587c67bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Mon, 17 Feb 2025 12:28:18 -0500 Subject: [PATCH 4/4] docs: Update docs/concepts/openedx-filters.rst Co-authored-by: Maria Grimaldi --- docs/concepts/openedx-filters.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/openedx-filters.rst b/docs/concepts/openedx-filters.rst index 36031c03..7f8d93b5 100644 --- a/docs/concepts/openedx-filters.rst +++ b/docs/concepts/openedx-filters.rst @@ -41,7 +41,7 @@ Workflow #. An application component (caller) invokes the filter during its execution by calling the ``run_filter`` method implemented by its :term:`filter definition`. -#. The caller passes the input data to the filter through the ``run_filter`` method. This data is an in-memory platform object that the filter will process. +#. The caller passes the input data to the filter through the ``run_filter`` method. These data are in-memory platform objects that the filter will process. #. The ``run_filter`` method of the filter calls the ``OpenEdxPublicFilter.run_pipeline`` method under the hood, which manages the execution of the filter's pipeline.