From a0f3a86f4daf1c9cd90acd88812ef3f5640c6ed5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Mon, 3 Feb 2025 16:30:52 -0500 Subject: [PATCH 01/14] docs: [FC-0074] - Style corrections for references and concepts This PR modifies some elements of the references and concepts' documents for the events repository, like the titles' RST codes and minor grammar corrections. --- docs/concepts/event-bus.rst | 32 +++++++++---------- docs/concepts/openedx-events.rst | 24 +++++++------- docs/index.rst | 13 +++++--- docs/reference/event-bus-configurations.rst | 2 +- docs/reference/events-data.rst | 12 +++---- docs/reference/events-tooling.rst | 2 +- docs/reference/events.rst | 2 +- .../in-line-code-annotations-for-an-event.rst | 2 +- docs/reference/oeps.rst | 8 ++--- 9 files changed, 50 insertions(+), 47 deletions(-) diff --git a/docs/concepts/event-bus.rst b/docs/concepts/event-bus.rst index 93b22d81..75138f13 100644 --- a/docs/concepts/event-bus.rst +++ b/docs/concepts/event-bus.rst @@ -22,24 +22,24 @@ The :term:`Event Bus` can help us achieve loose coupling between services, repla * **Eliminate Blocking, Synchronous Requests**: reduce site outages when services become overloaded with requests by replacing synchronous calls with asynchronous communication. * **Eliminate Expensive, Delayed, Batch Synchronization**: replace expensive batch processing with near real-time data updates. -* **Reduce the need for Plugins**: reduce the computational load for plugins that don't need to run in the same process by allowing cross-service communication of lifecycle events. +* **Reduce the Need for Plugins**: reduce the computational load for plugins that don't need to run in the same process by allowing cross-service communication of lifecycle events. How Does the Open edX Event Bus Work? ------------------------------------- The Open edX platform uses the ``OpenEdxPublicSignals`` (Open edX-specific Django Signals) to send events within a service. The event bus extends these signals, allowing them to be broadcasted and handled across multiple services. That's how Open edX Events are used for internal and external communication. For more details on how these Open edX-specific Django Signals are used by the event bus, refer to the :doc:`../decisions/0004-external-event-bus-and-django-signal-events` Architectural Decision Record (ADR). -Open edX Events provides an abstract implementation of the `publish/subscribe messaging pattern`_ (pub/sub) which is the chosen pattern for the event bus implementation as explained in :doc:`openedx-proposals:architectural-decisions/oep-0052-arch-event-bus-architecture`. It implements two abstract classes, `EventProducer`_ and `EventConsumer`_ which allow concrete implementations of the event bus based on different message brokers, such as Pulsar. +Open edX Events provides an abstract implementation of the `publish/subscribe messaging pattern`_ (pub/sub), which is the chosen pattern for the event bus implementation, as explained in :doc:`openedx-proposals:architectural-decisions/oep-0052-arch-event-bus-architecture`. It implements two abstract classes, `EventProducer`_ and `EventConsumer`_, which allow concrete implementations of the event bus based on different message brokers, such as Pulsar. -This abstraction allows for developers to implement their own concrete implementations of the event bus in their own plugins. There are currently two implementations of the event bus, Redis (`event-bus-redis`_) and Kafka (`event-bus-kafka`_). Redis streams is a data structure that acts like an append-only log, and Kafka is a distributed event streaming application. Both implementations handle event production and consumption with technology specific methods. +This abstraction allows for developers to implement their own concrete implementations of the event bus in their own plugins. There are currently two implementations of the event bus, Redis (`event-bus-redis`_) and Kafka (`event-bus-kafka`_). Redis streams is a data structure that acts like an append-only log, and Kafka is a distributed event streaming application. Both implementations handle event production and consumption using technology-specific methods.. Architectural Diagram ********************* -These diagrams show what happens when an event is sent to the event bus. The event sending workflow follows the same steps as explained in :ref:`events-architecture`, with a key difference: when configured, the event bus recognizes events and publish them to the message broker for consumption by other services. +These diagrams show what happens when an event is sent to the event bus. The event-sending workflow follows the same steps as explained in the :ref:`events-architecture`, with a key difference: when configured, the event bus recognizes events and publishes them to the message broker for consumption by other services. Components -~~~~~~~~~~ +============= * **Service A (Producer)**: The service that emits the event. Developers may have emitted this event in a key section of the application logic, signaling that a specific action has occurred. * **Service B (Consumer)**: The service that listens for the event and executes custom logic in response. @@ -47,10 +47,10 @@ Components * **Event Producer**: The class in the :term:`Producer` service that sends events to the event bus. The producer serializes the event data and enriches it with relevant metadata for the consumer. * **Event Consumer**: The class in the :term:`Consumer` service that receives events from the event bus. The consumer deserializes the :term:`message ` and re-emits it as an event with the data that was transmitted. * **Message Broker**: The :term:`message broker ` is responsible for storing and delivering messages between the producer and consumer. -* **Event Bus Plugin**: The concrete implementation of the event bus (EventProducer and EventConsumer) based on a specific :term:`message broker `, such as Pulsar. The plugin handles event production and consumption with technology-specific methods. +* **Event Bus Plugin**: The concrete implementation of the event bus (EventProducer and EventConsumer) based on a specific :term:`message broker `, such as Pulsar. The plugin handles event production and consumption using technology-specific methods. Workflow -~~~~~~~~ +========== .. image:: ../_images/event-bus-workflow-service-a.png :alt: Open edX Event Bus Workflow (Service A) @@ -60,8 +60,8 @@ Workflow 1. When the event is sent, a registered event receiver `general_signal_handler`_ is called to send the event to the event bus. This receiver is registered by the Django Signal mechanism when the ``openedx-events`` app is installed, and it listens for all Open edX Events. 2. The receiver checks the ``EVENT_BUS_PRODUCER_CONFIG`` to look for the ``event_type`` of the event that was sent. -3. If the event type is found and it's enabled for publishing in the configuration, the receiver obtains the configured producer class (``EventProducer``) from the concrete event bus implementation. For example, the producer class for Redis or Kafka implemented in their respective plugins. -4. The ``EventProducer`` serializes the event data and enriches it with relevant metadata, and then transforms it into a message that can be transmitted. +3. If the event type is found and it's enabled for publishing in the configuration, the receiver obtains the configured producer class (``EventProducer``) from the concrete event bus implementation. For example, the producer class for Redis or Kafka is implemented in their respective plugins. +4. The ``EventProducer`` serializes the event data, enriches it with relevant metadata, and then transforms it into a message that can be transmitted. 5. The producer uses its technology-specific ``send`` method to publish a message to the configured broker (e.g., Redis or Kafka). .. image:: ../_images/event-bus-workflow-service-b.png @@ -74,12 +74,12 @@ Workflow 2. When a new message is found, the ``EventConsumer`` deserializes the message and re-emits it as an event with the data that was transmitted. 3. The event sending and processing workflow repeats in Service B. -This approach of producing events via settings with the generic handler was chosen to allow for flexibility in the event bus implementation. It allows developers to choose the event bus implementation that best fits their needs, and to easily switch between implementations if necessary. See more details in the :doc:`../decisions/0012-producing-to-event-bus-via-settings` Architectural Decision Record (ADR). +This approach of producing events via settings with the generic handler was chosen to allow for flexibility in the event bus implementation. It allows developers to choose the event bus implementation that best fits their needs, and easily switch between implementations if necessary. See more details in the :doc:`../decisions/0012-producing-to-event-bus-via-settings` Architectural Decision Record (ADR). Event Bus vs Asynchronous Tasks ------------------------------- -Asynchronous tasks are used for long-running, resource-intensive operations that should not block the main thread of a service. The event bus is used for broadcasting messages to multiple services, allowing them to react to changes or actions in the system. Both can be used for asynchronous communication, but they serve different purposes and have different workflows. +Asynchronous tasks are used for long-running, resource-intensive operations that should not block the main thread of a service. The event bus broadcasts messages to multiple services, allowing them to react to changes or actions in the system. Both can be used for asynchronous communication, but they serve different purposes and have different workflows. In this diagram, you can see the difference between the two when it comes to asynchronous communication: @@ -87,7 +87,7 @@ In this diagram, you can see the difference between the two when it comes to asy :alt: Open edX Event Bus vs Asynchronous Tasks :align: center -In the upper part of the diagram, we have Service A and Service B. Service A is the producer of the event, and a :term:`Worker` of Service B is the consumer. This is the event bus workflow which allows asynchronous non-blocking communication between services: +In the upper part of the diagram, we have Service A and Service B. Service A is the producer of the event, and a :term:`Worker` of Service B is the consumer. This is the event bus workflow, which allows asynchronous, non-blocking communication between services: - Service A sends the event as a message to the event bus and continues its execution, as we previously explained. - Service B polls the message broker for new messages and converts them into ``OpenEdxPublicSignal``. @@ -103,23 +103,23 @@ In the lower part of the diagram, we have the asynchronous tasks workflow: If we were to introduce a Service C in this scenario, it would need to wait for the worker of Service A to finish processing the response from Service B and receive a response before it could continue. -This is an example of an asynchronous approach (from the producer point of view) to send messages to another services but with a blocking nature. +This is an example of an asynchronous approach (from the producer's point of view) to send messages to other services but with a blocking nature. Use the Open edX Event bus instead of asynchronous tasks when: - You want to send a message but don't need a response. For example, notifying other services of an event that occurred. -- You need to send a high volume of messages to a single or multiple services. For example, notifying when users visit a unit in a course or watch a video. +- You need to send a high volume of messages to a single or multiple services. For example, notifying when the users visit a unit in a course or watch a video. - You want to decouple services and avoid direct dependencies. - You want to send events out of the Open edX ecosystem. For example, external databases or services that can consume events to update their own state. -When you need to send a message to a particular service and wait their response for further processing, use asynchronous tasks. +Use asynchronous tasks when you need to send a message to a particular service and wait for their response for further processing. How is the Open edX Event Bus Used? ----------------------------------- The event bus is used to broadcast Open edX Events to multiple services, allowing them to react to changes or actions in the system. -We encourage you to review the :doc:`../reference/real-life-use-cases` page for examples of how the event bus is used in the Open edX ecosystem by the community. Also, see the :doc:`../how-tos/use-the-event-bus-to-broadcast-and-consume-events` guide to get start sending events to the event bus. +We encourage you to review the :doc:`../reference/real-life-use-cases` page for examples of how the community uses the event bus in the Open edX ecosystem. Also, see the :doc:`../how-tos/use-the-event-bus-to-broadcast-and-consume-events` guide to start sending events to the event bus. .. _general_signal_handler: https://github.com/openedx/openedx-events/blob/main/openedx_events/apps.py#L16-L44 .. _EventProducer: https://github.com/openedx/openedx-events/blob/main/openedx_events/event_bus/__init__.py#L71-L91 diff --git a/docs/concepts/openedx-events.rst b/docs/concepts/openedx-events.rst index b4a9bdb4..c92b8b2e 100644 --- a/docs/concepts/openedx-events.rst +++ b/docs/concepts/openedx-events.rst @@ -2,7 +2,7 @@ Open edX Events =============== Overview --------- +********* Open edX Events provide a mechanism for extending the platform by enabling developers to listen to Open edX-specific Django signals emitted by various services and respond accordingly. This allows for customized reactions to actions or changes within the platform without modifying the Open edX platform codebase, with the main goal of minimizing maintenance efforts for the Open edX project and plugin maintainers. @@ -11,14 +11,14 @@ What are Open edX Events? Open edX Events are signals emitted by a service (e.g., LMS, CMS, or others) within the Open edX ecosystem to notify that an action has occurred. For example, a user may have registered, logged in, or created a course. -These events are built on top of Django signals, inheriting their behavior while also incorporating metadata and actions specific to the Open edX ecosystem, making them uniquely suited for Open edX. Since they are essentially Django signals tailored to Open edX's specific needs, we can refer to `Django Signals Documentation`_ for a more detailed understanding of Open edX Events: +These events are built on top of Django signals, inheriting their behavior while also incorporating metadata and actions specific to the Open edX ecosystem, making them uniquely suited for Open edX. Since they are essentially Django signals tailored to Open edX's specific needs, we can refer to `Django Signals Documentation`_ for a more detailed understanding of Open edX Events. - Django includes a "signal dispatcher" which helps decoupled applications get notified when actions occur elsewhere in the framework. In a nutshell, signals allow certain senders to notify a set of receivers that some action has taken place. They're especially useful when many pieces of code may be interested in the same events. +.. note:: Django includes a "signal dispatcher" which helps decoupled applications be notified when actions occur elsewhere in the framework. In a nutshell, signals allow certain senders to notify a set of receivers that some action has taken place. They're especially useful when many pieces of code may be interested in the same events. Events are primarily used as a communication method between internal services by leveraging Django Signals and external services using the :doc:`../concepts/event-bus`, making them the standard communication mechanism within the Open edX ecosystem. How do Open edX Events work? ----------------------------- +**************************** Open edX Events are implemented by a class called `OpenEdxPublicSignal`_, which inherits from `Django's Signals class` and adds behaviors specific to the Open edX ecosystem. Thanks to this design, ``OpenEdxPublicSignal`` leverages the functionality of Django signals, allowing developers to apply their existing knowledge of the Django framework. You can review the :doc:`Open edX Events Tooling <../reference/events-tooling>` documentation for more information on the tooling available for working with Open edX events. @@ -34,19 +34,19 @@ In this diagram, we illustrate the workflow of emitting and processing an Open e :align: center Components -~~~~~~~~~~ +=========== -#. Application (caller): The application component that emits the event. Developers may have emitted this event in a key section of the application logic, signaling that a specific action has occurred. E.g., a user has enrolled in a course, `triggering the COURSE_ENROLLMENT_CREATED event`_. -#. OpenEdxPublicSignal: The class that implements all methods used to manage sending the event. As mentioned previously, this class inherits from Django's Signals class and adds Open edX-specific metadata and behaviors. -#. Django Signals: The Django framework's built-in signal mechanism. -#. Receiver1...ReceiverN: The components that listen to the event and execute custom logic in response. This receivers are implemented as Django signal receivers. +* **Application (caller):** The application component that emits the event. Developers may have emitted this event in a key section of the application logic, signaling that a specific action has occurred. E.g., a user has enrolled in a course, `triggering the COURSE_ENROLLMENT_CREATED event`_. +* **OpenEdxPublicSignal:** The class that implements all methods used to manage sending the event. As mentioned previously, this class inherits from Django's Signals class and adds Open edX-specific metadata and behaviors. +* **Django Signals:** The Django framework's built-in signal mechanism. +* **Receiver1...ReceiverN:** The components that listen to the event and execute custom logic in response. These receivers are implemented as Django signal receivers. Workflow ~~~~~~~~ #. An application (caller) emits an event by calling the `send_event`_ method implemented by `OpenEdxPublicSignal`_ which the event inherits from. -#. The caller passes the :term:`event payload` to the `send_event`_ method. The event payload is the data associated with the event that is passed to the receivers when it's triggered, and uses data attribute classes (e.g. ``CourseEnrollmentData``, ``UserData``, etc.) to carry data about the event. +#. The caller passes the :term:`event payload` to the `send_event`_ method. The event payload is the data associated with the event that is passed to the receivers when it's triggered. It uses data attribute classes (e.g. ``CourseEnrollmentData``, ``UserData``, etc.) to carry data about the event. #. The `send_event`_ method generates Open edX-specific metadata for the event on the fly, like the event version or the timestamp when the event was sent. The event receivers can access this metadata during their processing. @@ -70,8 +70,8 @@ Here is an example of an event that saves a user's notification preferences when The `Django Signals Documentation`_ provides a more detailed explanation of how Django signals work. -How are Open edX Events used? ------------------------------ +How Are Open edX Events Used? +***************************** As mentioned previously, developers can listen to Open edX Events by registering signal receivers from their Open edX Django plugins that respond to the emitted events or by using the :doc:`../concepts/event-bus` to send events to external services. diff --git a/docs/index.rst b/docs/index.rst index 61d5d6f1..da68f610 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,17 +3,20 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Open edX Events' documentation! -============================================ -Open edX Events is 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 Events. +Welcome to Open edX Events' Documentation! +########################################### + +Open edX Events is a type of hook in the :doc:`Hooks Extension Framework` that allows extending the Open edX platform in a more stable and maintainable way. If you are 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, which are useful to support your adoption of Open edX Events. + +This repository contains all the references, concepts, how-tos, quickstarts and Architectural Decision Records (ADRs) related to the Open edX Events necessary to implement this hook in your instance. .. toctree:: :maxdepth: 2 :caption: Contents: concepts/index - decisions/index + reference/index how-tos/index quickstarts/index - reference/index + decisions/index diff --git a/docs/reference/event-bus-configurations.rst b/docs/reference/event-bus-configurations.rst index c5313f3c..b7432151 100644 --- a/docs/reference/event-bus-configurations.rst +++ b/docs/reference/event-bus-configurations.rst @@ -1,5 +1,5 @@ Event Bus Configuration -======================= +######################## Here are the available configurations for the event bus that are used to setup the event bus in the Open edX platform. diff --git a/docs/reference/events-data.rst b/docs/reference/events-data.rst index da8e5088..29a581a9 100644 --- a/docs/reference/events-data.rst +++ b/docs/reference/events-data.rst @@ -1,30 +1,30 @@ Open edX Events Data Attributes -=============================== +################################ -Here are the data classes and attributes available for use when creating new Open edX Events. Review the classes and attributes to understand the data available for use in your event before creating a new data classes. +Here are the data classes and attributes available for use when creating new Open edX Events. Review the classes and attributes to understand the data available in your event before creating new data classes. .. note:: If you are creating a new data class in a subdomain that is not listed here, please add the new data class to the appropriate new subdomain section. Learning Subdomain ------------------- +******************** .. automodule:: openedx_events.learning.data :members: Content Authoring Subdomain ---------------------------- +**************************** .. automodule:: openedx_events.content_authoring.data :members: Analytics Subdomain -------------------- +********************** .. automodule:: openedx_events.analytics.data :members: Enterprise Subdomain --------------------- +*********************** .. automodule:: openedx_events.enterprise.data :members: diff --git a/docs/reference/events-tooling.rst b/docs/reference/events-tooling.rst index 67da4396..901d7861 100644 --- a/docs/reference/events-tooling.rst +++ b/docs/reference/events-tooling.rst @@ -1,5 +1,5 @@ Open edX Events Tooling -======================= +######################## Here we document the tooling available for working with Open edX events as a developer. diff --git a/docs/reference/events.rst b/docs/reference/events.rst index 20b19005..2ad8843a 100644 --- a/docs/reference/events.rst +++ b/docs/reference/events.rst @@ -1,5 +1,5 @@ Events -====== +####### This is the list of Open edX events found in this repository. diff --git a/docs/reference/in-line-code-annotations-for-an-event.rst b/docs/reference/in-line-code-annotations-for-an-event.rst index 858ec32d..08caf86c 100644 --- a/docs/reference/in-line-code-annotations-for-an-event.rst +++ b/docs/reference/in-line-code-annotations-for-an-event.rst @@ -1,5 +1,5 @@ In-line Code Annotations for An Open edX Event -============================================== +################################################ When creating a new Open edX Event, you must document the event definition using in-line code annotations. These annotations provide a structured way to document the event's metadata, making it easier for developers to understand the event's purpose and how it should be used. diff --git a/docs/reference/oeps.rst b/docs/reference/oeps.rst index 519b5833..b12b54fd 100644 --- a/docs/reference/oeps.rst +++ b/docs/reference/oeps.rst @@ -1,12 +1,12 @@ Open edX Proposals -================== +################### -Here we list the Open edX proposals used throughout the project, that will help +Here we list the Open edX proposals used throughout the project that will help you understand the major decisions made during the library's design. -- The `Hooks extension framework (OEP-50)`_ which specifies its motivation, implementation details, rationale, performance considerations, general use cases and more. The goal of the OEP-50 is give the extensions' developer a glance on the framework implementation and design. +- The `Hooks extension framework (OEP-50)`_ specifies its motivation, implementation details, rationale, performance considerations, general use cases, and more. The goal of the OEP-50 is to give the extensions' developer a glance at the framework implementation and design. -- The `Asynchronous Server Event Message Format (OEP-41)`_, which specifies the header information format sent by the events. For a detailed description on the impact of the OEP-41, please refer to the Events Payload ADR. +- The `Asynchronous Server Event Message Format (OEP-41)`_ specifies the header information format sent by the events. For a detailed description at the impact of the OEP-41, please refer to the Events Payload ADR. .. _Hooks extension framework (OEP-50): https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0050-hooks-extension-framework.html .. _Asynchronous Server Event Message Format (OEP-41): https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html From 1640c7e095e978f884b315522e00d35935fc1948 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Mon, 3 Feb 2025 16:42:35 -0500 Subject: [PATCH 02/14] docs: update event-bus.rst This PR update event-bus.rst --- docs/concepts/event-bus.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/concepts/event-bus.rst b/docs/concepts/event-bus.rst index 75138f13..3edb59cf 100644 --- a/docs/concepts/event-bus.rst +++ b/docs/concepts/event-bus.rst @@ -1,13 +1,13 @@ Open edX Event Bus -================== +#################### Overview --------- +********** The suggested strategy for cross-service communication in the Open edX ecosystem is through an event-based architecture implemented via the :term:`Event Bus`. This functionality used for asynchronous communication between services is built on top of sending Open edX Events (Open edX-specific Django signals) within a service. What is the Open edX Event Bus? -------------------------------- +******************************** The :term:`Event Bus` implements an event-driven architecture that enables asynchronous communication between services using the `publish/subscribe messaging pattern`_ (pub/sub). In the Open edX ecosystem, the event bus is used to broadcast Open edX Events to multiple services, allowing them to react to changes or actions in the system. The event bus is a key component of the Open edX architecture, enabling services to communicate without direct dependencies on each other. @@ -16,7 +16,7 @@ The :term:`Event Bus` implements an event-driven architecture that enables async :align: center Why use the Open edX Event Bus? -------------------------------- +********************************** The :term:`Event Bus` can help us achieve loose coupling between services, replacing blocking requests between services and large sync jobs, leading to a faster, more reliable, and more extensible system. See event messaging architectural goals highlighted in :doc:`openedx-proposals:architectural-decisions/oep-0041-arch-async-server-event-messaging` to read more about its benefits. Here's a brief summary of some key points: @@ -25,7 +25,7 @@ The :term:`Event Bus` can help us achieve loose coupling between services, repla * **Reduce the Need for Plugins**: reduce the computational load for plugins that don't need to run in the same process by allowing cross-service communication of lifecycle events. How Does the Open edX Event Bus Work? -------------------------------------- +*************************************** The Open edX platform uses the ``OpenEdxPublicSignals`` (Open edX-specific Django Signals) to send events within a service. The event bus extends these signals, allowing them to be broadcasted and handled across multiple services. That's how Open edX Events are used for internal and external communication. For more details on how these Open edX-specific Django Signals are used by the event bus, refer to the :doc:`../decisions/0004-external-event-bus-and-django-signal-events` Architectural Decision Record (ADR). @@ -36,10 +36,10 @@ This abstraction allows for developers to implement their own concrete implement Architectural Diagram ********************* -These diagrams show what happens when an event is sent to the event bus. The event-sending workflow follows the same steps as explained in the :ref:`events-architecture`, with a key difference: when configured, the event bus recognizes events and publishes them to the message broker for consumption by other services. +These diagrams show what happens when an event is sent to the event bus. The event-sending workflow follows the same steps as explained in the :ref:`events architecture`, with a key difference: when configured, the event bus recognizes events and publishes them to the message broker for consumption by other services. Components -============= +========== * **Service A (Producer)**: The service that emits the event. Developers may have emitted this event in a key section of the application logic, signaling that a specific action has occurred. * **Service B (Consumer)**: The service that listens for the event and executes custom logic in response. @@ -50,13 +50,14 @@ Components * **Event Bus Plugin**: The concrete implementation of the event bus (EventProducer and EventConsumer) based on a specific :term:`message broker `, such as Pulsar. The plugin handles event production and consumption using technology-specific methods. Workflow -========== +========= .. image:: ../_images/event-bus-workflow-service-a.png :alt: Open edX Event Bus Workflow (Service A) :align: center -**From Service A (Producer)** +From Service A (Producer) +------------------------------ 1. When the event is sent, a registered event receiver `general_signal_handler`_ is called to send the event to the event bus. This receiver is registered by the Django Signal mechanism when the ``openedx-events`` app is installed, and it listens for all Open edX Events. 2. The receiver checks the ``EVENT_BUS_PRODUCER_CONFIG`` to look for the ``event_type`` of the event that was sent. @@ -68,7 +69,8 @@ Workflow :alt: Open edX Event Bus Workflow (Service B) :align: center -**From Service B (Consumer)** +From Service B (Consumer) +------------------------- 1. A :term:`Worker` process in Service B runs indefinitely, checking the broker for new messages. 2. When a new message is found, the ``EventConsumer`` deserializes the message and re-emits it as an event with the data that was transmitted. @@ -77,7 +79,7 @@ Workflow This approach of producing events via settings with the generic handler was chosen to allow for flexibility in the event bus implementation. It allows developers to choose the event bus implementation that best fits their needs, and easily switch between implementations if necessary. See more details in the :doc:`../decisions/0012-producing-to-event-bus-via-settings` Architectural Decision Record (ADR). Event Bus vs Asynchronous Tasks -------------------------------- +******************************** Asynchronous tasks are used for long-running, resource-intensive operations that should not block the main thread of a service. The event bus broadcasts messages to multiple services, allowing them to react to changes or actions in the system. Both can be used for asynchronous communication, but they serve different purposes and have different workflows. @@ -115,7 +117,7 @@ Use the Open edX Event bus instead of asynchronous tasks when: Use asynchronous tasks when you need to send a message to a particular service and wait for their response for further processing. How is the Open edX Event Bus Used? ------------------------------------ +************************************ The event bus is used to broadcast Open edX Events to multiple services, allowing them to react to changes or actions in the system. From b029dc1db10af9e1daabc9a5e83f8120da4a0d72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Mon, 3 Feb 2025 16:43:58 -0500 Subject: [PATCH 03/14] docs: Update index.rst This PR update index.rst --- docs/index.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index da68f610..4c39b4e9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,11 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. - Welcome to Open edX Events' Documentation! -########################################### +############################################ -Open edX Events is a type of hook in the :doc:`Hooks Extension Framework` that allows extending the Open edX platform in a more stable and maintainable way. If you are 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, which are useful to support your adoption of Open edX Events. +Open edX Events 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 are 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, which are useful to support your adoption of Open edX Events. This repository contains all the references, concepts, how-tos, quickstarts and Architectural Decision Records (ADRs) related to the Open edX Events necessary to implement this hook in your instance. From ed623b634195ad650fcfca040319ac941df53d50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Tue, 4 Feb 2025 13:59:41 -0500 Subject: [PATCH 04/14] docs: Update openedx-events.rst PR to Update openedx-events.rst and fix an error --- docs/concepts/openedx-events.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/concepts/openedx-events.rst b/docs/concepts/openedx-events.rst index c92b8b2e..2db284d0 100644 --- a/docs/concepts/openedx-events.rst +++ b/docs/concepts/openedx-events.rst @@ -1,28 +1,29 @@ Open edX Events -=============== +################# Overview -********* +********** + Open edX Events provide a mechanism for extending the platform by enabling developers to listen to Open edX-specific Django signals emitted by various services and respond accordingly. This allows for customized reactions to actions or changes within the platform without modifying the Open edX platform codebase, with the main goal of minimizing maintenance efforts for the Open edX project and plugin maintainers. -What are Open edX Events? -------------------------- +What Are Open edX Events? +************************** Open edX Events are signals emitted by a service (e.g., LMS, CMS, or others) within the Open edX ecosystem to notify that an action has occurred. For example, a user may have registered, logged in, or created a course. These events are built on top of Django signals, inheriting their behavior while also incorporating metadata and actions specific to the Open edX ecosystem, making them uniquely suited for Open edX. Since they are essentially Django signals tailored to Open edX's specific needs, we can refer to `Django Signals Documentation`_ for a more detailed understanding of Open edX Events. -.. note:: Django includes a "signal dispatcher" which helps decoupled applications be notified when actions occur elsewhere in the framework. In a nutshell, signals allow certain senders to notify a set of receivers that some action has taken place. They're especially useful when many pieces of code may be interested in the same events. +.. note:: Django includes a "signal dispatcher", which helps decoupled applications be notified when actions occur elsewhere in the framework. In a nutshell, signals allow certain senders to notify a set of receivers that some action has taken place. They're especially useful when many pieces of code may be interested in the same events. Events are primarily used as a communication method between internal services by leveraging Django Signals and external services using the :doc:`../concepts/event-bus`, making them the standard communication mechanism within the Open edX ecosystem. -How do Open edX Events work? +How Do Open edX Events Work? **************************** Open edX Events are implemented by a class called `OpenEdxPublicSignal`_, which inherits from `Django's Signals class` and adds behaviors specific to the Open edX ecosystem. Thanks to this design, ``OpenEdxPublicSignal`` leverages the functionality of Django signals, allowing developers to apply their existing knowledge of the Django framework. You can review the :doc:`Open edX Events Tooling <../reference/events-tooling>` documentation for more information on the tooling available for working with Open edX events. -.. _events-architecture: +.. _events architecture: Architectural Diagram ********************* @@ -34,15 +35,16 @@ In this diagram, we illustrate the workflow of emitting and processing an Open e :align: center Components -=========== +========== * **Application (caller):** The application component that emits the event. Developers may have emitted this event in a key section of the application logic, signaling that a specific action has occurred. E.g., a user has enrolled in a course, `triggering the COURSE_ENROLLMENT_CREATED event`_. * **OpenEdxPublicSignal:** The class that implements all methods used to manage sending the event. As mentioned previously, this class inherits from Django's Signals class and adds Open edX-specific metadata and behaviors. * **Django Signals:** The Django framework's built-in signal mechanism. + * **Receiver1...ReceiverN:** The components that listen to the event and execute custom logic in response. These receivers are implemented as Django signal receivers. Workflow -~~~~~~~~ +========= #. An application (caller) emits an event by calling the `send_event`_ method implemented by `OpenEdxPublicSignal`_ which the event inherits from. @@ -58,6 +60,7 @@ Workflow #. After all receivers for the event have been executed, the process continues with the application logic. + Here is an example of an event that saves a user's notification preferences when they enroll in a course: #. A user enrolls in a course, `triggering the COURSE_ENROLLMENT_CREATED event`_. This event includes information about the user, course, and enrollment details. @@ -70,6 +73,7 @@ Here is an example of an event that saves a user's notification preferences when The `Django Signals Documentation`_ provides a more detailed explanation of how Django signals work. + How Are Open edX Events Used? ***************************** From 3aa690de299915db4a10bb5c5ca45dc9c98effd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Wed, 5 Feb 2025 19:29:36 -0500 Subject: [PATCH 05/14] docs: maintenance chart adding --- docs/concepts/event-bus.rst | 13 +++++ docs/concepts/openedx-events.rst | 14 ++++++ docs/reference/architecture-subdomains.rst | 15 +++++- docs/reference/event-bus-configurations.rst | 13 +++++ docs/reference/events-data.rst | 13 +++++ docs/reference/events-tooling.rst | 14 ++++++ docs/reference/events.rst | 13 +++++ .../in-line-code-annotations-for-an-event.rst | 15 +++++- docs/reference/oeps.rst | 13 +++++ docs/reference/real-life-use-cases.rst | 47 ++++++++++++------- 10 files changed, 151 insertions(+), 19 deletions(-) diff --git a/docs/concepts/event-bus.rst b/docs/concepts/event-bus.rst index 3edb59cf..35f673e7 100644 --- a/docs/concepts/event-bus.rst +++ b/docs/concepts/event-bus.rst @@ -123,6 +123,19 @@ The event bus is used to broadcast Open edX Events to multiple services, allowin We encourage you to review the :doc:`../reference/real-life-use-cases` page for examples of how the community uses the event bus in the Open edX ecosystem. Also, see the :doc:`../how-tos/use-the-event-bus-to-broadcast-and-consume-events` guide to start sending events to the event bus. +**Maintenance chart** + +.. list-table:: +:header-rows: 1 +* - Review Date + - Working Group Reviewer + - Release + - Test Situation +* - 2025-02-05 + - BTR WG - Maria Grimaldi + - Redwood + - Pass + .. _general_signal_handler: https://github.com/openedx/openedx-events/blob/main/openedx_events/apps.py#L16-L44 .. _EventProducer: https://github.com/openedx/openedx-events/blob/main/openedx_events/event_bus/__init__.py#L71-L91 .. _EventConsumer: https://github.com/openedx/openedx-events/blob/main/openedx_events/event_bus/__init__.py#L128-L139 diff --git a/docs/concepts/openedx-events.rst b/docs/concepts/openedx-events.rst index 2db284d0..45fff384 100644 --- a/docs/concepts/openedx-events.rst +++ b/docs/concepts/openedx-events.rst @@ -81,6 +81,20 @@ As mentioned previously, developers can listen to Open edX Events by registering For more information on using Open edX Events, refer to the :doc:`../how-tos/create-a-new-event` how-to guide. We also encourage you to explore the :doc:`../reference/real-life-use-cases` section for real-life examples of how Open edX Events are used by the community. +**Maintenance chart** + +.. list-table:: +:header-rows: 1 +* - Review Date + - Working Group Reviewer + - Release + - Test Situation +* - 2025-02-05 + - BTR WG - Maria Grimaldi + - Redwood + - Pass + + .. _Django Signals Documentation: https://docs.djangoproject.com/en/4.2/topics/signals/ .. _triggering the COURSE_ENROLLMENT_CREATED event: https://github.com/openedx/edx-platform/blob/master/common/djangoapps/student/models/course_enrollment.py#L777-L795 .. _course_enrollment_post_save receiver: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/notifications/handlers.py#L38-L53 diff --git a/docs/reference/architecture-subdomains.rst b/docs/reference/architecture-subdomains.rst index dff2befe..a6ecabab 100644 --- a/docs/reference/architecture-subdomains.rst +++ b/docs/reference/architecture-subdomains.rst @@ -1,5 +1,5 @@ Architecture Subdomains -======================= +########################## Currently, these are the `architecture subdomains`_ used by the Open edX Events library: @@ -23,6 +23,19 @@ Here we list useful information about Open edX architecture subdomains and their - `Subdomains from OEP-41`_ - `Message Content Data Guidelines`_ +**Maintenance chart** + +.. list-table:: +:header-rows: 1 +* - Review Date + - Working Group Reviewer + - Release + - Test Situation +* - 2025-02-05 + - BTR WG - Maria Grimaldi + - Redwood + - Pass + .. _Events Naming and Versioning: https://github.com/openedx/openedx-events/blob/main/docs/decisions/0002-events-naming-and-versioning.rst#L1 .. _edX Domain Driven Design documentation: https://openedx.atlassian.net/wiki/spaces/AC/pages/213910332/Domain-Driven+Design .. _`Subdomains from OEP-41`: https://docs.openedx.org/projects/openedx-proposals/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html#subdomain-from-domain-driven-design diff --git a/docs/reference/event-bus-configurations.rst b/docs/reference/event-bus-configurations.rst index b7432151..89ffce35 100644 --- a/docs/reference/event-bus-configurations.rst +++ b/docs/reference/event-bus-configurations.rst @@ -5,3 +5,16 @@ Here are the available configurations for the event bus that are used to setup t .. settings:: :folder_path: openedx_events/event_bus + +**Maintenance chart** + +.. list-table:: +:header-rows: 1 +* - Review Date + - Working Group Reviewer + - Release + - Test Situation +* - 2025-02-05 + - BTR WG - Maria Grimaldi + - Redwood + - Pass diff --git a/docs/reference/events-data.rst b/docs/reference/events-data.rst index 29a581a9..7a742034 100644 --- a/docs/reference/events-data.rst +++ b/docs/reference/events-data.rst @@ -28,3 +28,16 @@ Enterprise Subdomain .. automodule:: openedx_events.enterprise.data :members: + +**Maintenance chart** + +.. list-table:: +:header-rows: 1 +* - Review Date + - Working Group Reviewer + - Release + - Test Situation +* - 2025-02-05 + - BTR WG - Maria Grimaldi + - Redwood + - Pass \ No newline at end of file diff --git a/docs/reference/events-tooling.rst b/docs/reference/events-tooling.rst index 901d7861..6ed7187b 100644 --- a/docs/reference/events-tooling.rst +++ b/docs/reference/events-tooling.rst @@ -5,3 +5,17 @@ Here we document the tooling available for working with Open edX events as a dev .. autoclass:: openedx_events.tooling.OpenEdxPublicSignal :members: + + +**Maintenance chart** + +.. list-table:: +:header-rows: 1 +* - Review Date + - Working Group Reviewer + - Release + - Test Situation +* - 2025-02-05 + - BTR WG - Maria Grimaldi + - Redwood + - Pass \ No newline at end of file diff --git a/docs/reference/events.rst b/docs/reference/events.rst index 2ad8843a..7eb01dd6 100644 --- a/docs/reference/events.rst +++ b/docs/reference/events.rst @@ -7,3 +7,16 @@ This is the list of Open edX events found in this repository. Events can be created in other projects and plugins as well, but these default events are guaranteed to exist. .. openedxevents:: + +**Maintenance chart** + +.. list-table:: +:header-rows: 1 +* - Review Date + - Working Group Reviewer + - Release + - Test Situation +* - 2025-02-05 + - BTR WG - Maria Grimaldi + - Redwood + - Pass diff --git a/docs/reference/in-line-code-annotations-for-an-event.rst b/docs/reference/in-line-code-annotations-for-an-event.rst index 08caf86c..75ed61d8 100644 --- a/docs/reference/in-line-code-annotations-for-an-event.rst +++ b/docs/reference/in-line-code-annotations-for-an-event.rst @@ -1,4 +1,4 @@ -In-line Code Annotations for An Open edX Event +In-line Code Annotations for an Open edX Event ################################################ When creating a new Open edX Event, you must document the event definition using in-line code annotations. These annotations provide a structured way to document the event's metadata, making it easier for developers to understand the event's purpose and how it should be used. @@ -32,3 +32,16 @@ Consider the following example: "enrollment": CourseEnrollmentData, } ) + +**Maintenance chart** + +.. list-table:: +:header-rows: 1 +* - Review Date + - Working Group Reviewer + - Release + - Test Situation +* - 2025-02-05 + - BTR WG - Maria Grimaldi + - Redwood + - Pass \ No newline at end of file diff --git a/docs/reference/oeps.rst b/docs/reference/oeps.rst index b12b54fd..420f7567 100644 --- a/docs/reference/oeps.rst +++ b/docs/reference/oeps.rst @@ -8,5 +8,18 @@ you understand the major decisions made during the library's design. - The `Asynchronous Server Event Message Format (OEP-41)`_ specifies the header information format sent by the events. For a detailed description at the impact of the OEP-41, please refer to the Events Payload ADR. +**Maintenance chart** + +.. list-table:: +:header-rows: 1 +* - Review Date + - Working Group Reviewer + - Release + - Test Situation +* - 2025-02-05 + - BTR WG - Maria Grimaldi + - Redwood + - Pass + .. _Hooks extension framework (OEP-50): https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0050-hooks-extension-framework.html .. _Asynchronous Server Event Message Format (OEP-41): https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html diff --git a/docs/reference/real-life-use-cases.rst b/docs/reference/real-life-use-cases.rst index 2b778381..2e3495a8 100644 --- a/docs/reference/real-life-use-cases.rst +++ b/docs/reference/real-life-use-cases.rst @@ -1,27 +1,27 @@ Real-Life Use Cases for Open edX Events -======================================= +######################################## Overview --------- +********** As mentioned in the :doc:`docs.openedx.org:developers/concepts/hooks_extension_framework` docs, Open edX Events can be used to integrate application components with each other or with external services, allowing them to communicate, synchronize, and perform additional actions when specific triggers occur. To illustrate the different solutions that can be implemented with this approach, we have compiled a list of use cases built using Open edX Events to address various challenges. The goal of this list is to serve as a reference for extension developers to implement their own solutions in their own plugins or IDAs based on the community's experience. Use Cases ---------- +********** The following list of real-life use cases showcases the different ways Open edX Events can be used to facilitate communication between IDAs and application components, allowing them to interact, synchronize, and perform additional actions when specific triggers occur. Cross-services communication -**************************** +============================= As mentioned in :doc:`../concepts/event-bus`, the suggested strategy for cross-service communication in the Open edX ecosystem is through an event-based architecture implemented via the :doc:`../concepts/event-bus`. This functionality used for asynchronous communication between services is built on top of sending Open edX Events (Open edX-specific Django signals) within a service. For more details on the Event Bus, please see :doc:`../how-tos/use-the-event-bus-to-broadcast-and-consume-events`. Here are some examples of how the Event Bus can be used to facilitate communication between IDAs: Exam Downstream Effects -~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ The `edx-exams`_ service adopts an event-driven architecture, using the event bus to allow communication with edx-platform to downstream effects. Unlike the legacy exams system (`edx-proctoring`_), which relied on direct function calls to edx-platform services, the event bus sends exam-specific events received by the LMS, triggering responses like grade overrides without creating dependencies between the two. @@ -30,28 +30,28 @@ This approach implements a modular and scalable system by enabling `edx-exams`_ More details on: `ADR Implementation of Event Driven Architecture for Exam Downstream Effects`_. Course Metadata Synchronization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------- An event is emitted each time a course is published by the CMS, which is sent to the event bus and received by the `Course Discovery`_ service. This process allows `Course Discovery`_ to automatically update course metadata, ensuring that any changes in the CMS are reflected. By communicating through the event bus, this setup decreases the need for manual data syncs, keeping course metadata consistently up-to-date across services. More details on: `Use Event Bus to Replace Refresh Course Metadata`_. Credentials Management -~~~~~~~~~~~~~~~~~~~~~~ +------------------------- When the LMS emits certificate-related events, they are sent to the event bus and received by the `Credentials`_ service. `Credentials`_ can automatically award or revoke learner credentials based on the event type. This integration simplifies credential management by enabling real-time updates from the LMS, ensuring the appropriate generation of learner credentials without requiring manual synchronization. More details on: `Credentials - Event Bus`_. Credly Integration -~~~~~~~~~~~~~~~~~~ +-------------------- The LMS sends events about learner progress, like course and section completions, through the event bus. The `Credentials`_ service then receives these events, adds extra information, and forwards them to external credential providers such as `Credly`_. These providers create and display digital credentials for learners based on the completion data. More details on: `Credly Integration`_. Real-Time Event Tracking -~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------- To make event tracking faster and more efficient, tracking logs are optionally sent through the event bus instead of the traditional method, which relied on asynchronous tasks to process logs. A receiver listens for each tracking event and sends it to the event bus, allowing real-time updates. This new approach improves performance by reducing delays, as logs now reach the `Aspects`_ stack in a near real-time manner. @@ -63,42 +63,42 @@ Communication between Application Components Open edX Events can also be used to facilitate communication between different application components running in the same process, allowing them to interact and synchronize their actions. Here are some examples of how Open edX Events can be used to coordinate between application components: Automatic Content Tagging -~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- When new content is created or existing content is edited, these events trigger updates to automatically apply relevant tags based on system-defined categories. This ensures that content is consistently tagged, reducing the need for manual tagging and keeping content classification up-to-date. More details on: `Automatic Content Tagging`_. Keep Search Indexes Up-To-Date -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------- Each time content is updated or created, an event is emitted that triggers the indexing of the new content, automatically updating the search index with the latest content metadata. This ensure that all content changes are accurately reflected in search results. More details on: `Update Search Indexes`_ External Certificate Generation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------- Events are sent after the certificate generation for a user when they complete a course, these events trigger the generation of corresponding certificates in an external system if the proper conditions are met, allowing for seamless integrations with external certification services. More details on: `External Certificate Generation`_. Automatic Group Association -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- Enrollment events trigger the association of the user into a pre-defined cohort based on the user's preference language. This way, instructors don't need to add a student into a cohort manually, but it's automatically done, reducing logistic efforts and creating more seamless integrations with language-based restricted content. More details on: `Automatic Group Association`_. Forum Emails Notifier -~~~~~~~~~~~~~~~~~~~~~ +----------------------- When new threads, responses or comments are created in the discussion forum, events are sent with relevant information about what occurred, triggering email notifications with relevant information about the update based on the user's preferences. This allows users stay up-to-date with discussions threads. More details on: `Forum Emails Notifier`_. Webhooks Integration -~~~~~~~~~~~~~~~~~~~~ +---------------------- `Webhooks`_ trigger an HTTP POST request to a configurable URL when certain events happen in the Open edX platform, including information relevant to the event. When these events are sent, then the data is sent to services like Zapier or any other configured, allowing the sharing of data between different external services. @@ -109,14 +109,14 @@ More details on: * `Open edX Events To Zapier`_. Send ORA Submissions to Third-Party Plagiarism Services -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------------------------- Each time a student submits an Open Response Assessment (ORA), an event is emitted triggering a request to external services to review the student response for plagiarism. This allows a seamless integration of tools to help instructors while grading. More details on: `Send ORA Submissions to Third-Party Plagiarism Services`_. Other Use Cases -*************** +================ Here are some additional use cases that can be implemented using Open edX Events: @@ -130,6 +130,19 @@ Here are some additional use cases that can be implemented using Open edX Events .. note:: If you have implemented a solution using Open edX Events and would like to share it with the community, please submit a pull request to add it to this list! +**Maintenance chart** + +.. list-table:: +:header-rows: 1 +* - Review Date + - Working Group Reviewer + - Release + - Test Situation +* - 2025-02-05 + - BTR WG - Maria Grimaldi + - Redwood + - Pass + .. _edx-exams: https://github.com/edx/edx-exams .. _edx-proctoring: https://github.com/openedx/edx-proctoring .. _ADR Implementation of Event Driven Architecture for Exam Downstream Effects: https://github.com/edx/edx-exams/blob/main/docs/decisions/0004-downstream-effect-events.rst From e330de4a8a01458492f10525fb18242844c9fad5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Wed, 5 Feb 2025 19:38:03 -0500 Subject: [PATCH 06/14] docs: update maintenance chart --- docs/concepts/event-bus.rst | 21 +++++++------------ docs/concepts/openedx-events.rst | 21 +++++++------------ docs/reference/architecture-subdomains.rst | 20 +++++++----------- docs/reference/event-bus-configurations.rst | 15 +++++-------- docs/reference/events-data.rst | 15 +++++-------- docs/reference/events-tooling.rst | 15 +++++-------- docs/reference/events.rst | 15 +++++-------- .../in-line-code-annotations-for-an-event.rst | 15 +++++-------- docs/reference/oeps.rst | 21 +++++++------------ docs/reference/real-life-use-cases.rst | 21 +++++++------------ 10 files changed, 65 insertions(+), 114 deletions(-) diff --git a/docs/concepts/event-bus.rst b/docs/concepts/event-bus.rst index 35f673e7..f820323b 100644 --- a/docs/concepts/event-bus.rst +++ b/docs/concepts/event-bus.rst @@ -123,22 +123,17 @@ The event bus is used to broadcast Open edX Events to multiple services, allowin We encourage you to review the :doc:`../reference/real-life-use-cases` page for examples of how the community uses the event bus in the Open edX ecosystem. Also, see the :doc:`../how-tos/use-the-event-bus-to-broadcast-and-consume-events` guide to start sending events to the event bus. -**Maintenance chart** - -.. list-table:: -:header-rows: 1 -* - Review Date - - Working Group Reviewer - - Release - - Test Situation -* - 2025-02-05 - - BTR WG - Maria Grimaldi - - Redwood - - Pass - .. _general_signal_handler: https://github.com/openedx/openedx-events/blob/main/openedx_events/apps.py#L16-L44 .. _EventProducer: https://github.com/openedx/openedx-events/blob/main/openedx_events/event_bus/__init__.py#L71-L91 .. _EventConsumer: https://github.com/openedx/openedx-events/blob/main/openedx_events/event_bus/__init__.py#L128-L139 .. _publish/subscribe messaging pattern: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern .. _event-bus-redis: https://github.com/openedx/event-bus-redis/ .. _event-bus-kafka: https://github.com/openedx/event-bus-kafka/ + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/docs/concepts/openedx-events.rst b/docs/concepts/openedx-events.rst index 45fff384..e257e7e5 100644 --- a/docs/concepts/openedx-events.rst +++ b/docs/concepts/openedx-events.rst @@ -81,19 +81,6 @@ As mentioned previously, developers can listen to Open edX Events by registering For more information on using Open edX Events, refer to the :doc:`../how-tos/create-a-new-event` how-to guide. We also encourage you to explore the :doc:`../reference/real-life-use-cases` section for real-life examples of how Open edX Events are used by the community. -**Maintenance chart** - -.. list-table:: -:header-rows: 1 -* - Review Date - - Working Group Reviewer - - Release - - Test Situation -* - 2025-02-05 - - BTR WG - Maria Grimaldi - - Redwood - - Pass - .. _Django Signals Documentation: https://docs.djangoproject.com/en/4.2/topics/signals/ .. _triggering the COURSE_ENROLLMENT_CREATED event: https://github.com/openedx/edx-platform/blob/master/common/djangoapps/student/models/course_enrollment.py#L777-L795 @@ -105,3 +92,11 @@ For more information on using Open edX Events, refer to the :doc:`../how-tos/cre .. _Django's Signals class: https://docs.djangoproject.com/en/4.2/topics/signals/#defining-and-sending-signals .. _send_event: https://github.com/openedx/openedx-events/blob/main/openedx_events/tooling.py#L185 .. _send or send_robust: https://docs.djangoproject.com/en/4.2/topics/signals/#sending-signals + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/docs/reference/architecture-subdomains.rst b/docs/reference/architecture-subdomains.rst index a6ecabab..5cc2325b 100644 --- a/docs/reference/architecture-subdomains.rst +++ b/docs/reference/architecture-subdomains.rst @@ -23,18 +23,6 @@ Here we list useful information about Open edX architecture subdomains and their - `Subdomains from OEP-41`_ - `Message Content Data Guidelines`_ -**Maintenance chart** - -.. list-table:: -:header-rows: 1 -* - Review Date - - Working Group Reviewer - - Release - - Test Situation -* - 2025-02-05 - - BTR WG - Maria Grimaldi - - Redwood - - Pass .. _Events Naming and Versioning: https://github.com/openedx/openedx-events/blob/main/docs/decisions/0002-events-naming-and-versioning.rst#L1 .. _edX Domain Driven Design documentation: https://openedx.atlassian.net/wiki/spaces/AC/pages/213910332/Domain-Driven+Design @@ -42,3 +30,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 | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/docs/reference/event-bus-configurations.rst b/docs/reference/event-bus-configurations.rst index 89ffce35..7024c8e9 100644 --- a/docs/reference/event-bus-configurations.rst +++ b/docs/reference/event-bus-configurations.rst @@ -8,13 +8,8 @@ Here are the available configurations for the event bus that are used to setup t **Maintenance chart** -.. list-table:: -:header-rows: 1 -* - Review Date - - Working Group Reviewer - - Release - - Test Situation -* - 2025-02-05 - - BTR WG - Maria Grimaldi - - Redwood - - Pass ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/docs/reference/events-data.rst b/docs/reference/events-data.rst index 7a742034..a647a679 100644 --- a/docs/reference/events-data.rst +++ b/docs/reference/events-data.rst @@ -31,13 +31,8 @@ Enterprise Subdomain **Maintenance chart** -.. list-table:: -:header-rows: 1 -* - Review Date - - Working Group Reviewer - - Release - - Test Situation -* - 2025-02-05 - - BTR WG - Maria Grimaldi - - Redwood - - Pass \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/docs/reference/events-tooling.rst b/docs/reference/events-tooling.rst index 6ed7187b..6afda80d 100644 --- a/docs/reference/events-tooling.rst +++ b/docs/reference/events-tooling.rst @@ -9,13 +9,8 @@ Here we document the tooling available for working with Open edX events as a dev **Maintenance chart** -.. list-table:: -:header-rows: 1 -* - Review Date - - Working Group Reviewer - - Release - - Test Situation -* - 2025-02-05 - - BTR WG - Maria Grimaldi - - Redwood - - Pass \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/docs/reference/events.rst b/docs/reference/events.rst index 7eb01dd6..aa60b37f 100644 --- a/docs/reference/events.rst +++ b/docs/reference/events.rst @@ -10,13 +10,8 @@ This is the list of Open edX events found in this repository. **Maintenance chart** -.. list-table:: -:header-rows: 1 -* - Review Date - - Working Group Reviewer - - Release - - Test Situation -* - 2025-02-05 - - BTR WG - Maria Grimaldi - - Redwood - - Pass ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/docs/reference/in-line-code-annotations-for-an-event.rst b/docs/reference/in-line-code-annotations-for-an-event.rst index 75ed61d8..b4650d52 100644 --- a/docs/reference/in-line-code-annotations-for-an-event.rst +++ b/docs/reference/in-line-code-annotations-for-an-event.rst @@ -35,13 +35,8 @@ Consider the following example: **Maintenance chart** -.. list-table:: -:header-rows: 1 -* - Review Date - - Working Group Reviewer - - Release - - Test Situation -* - 2025-02-05 - - BTR WG - Maria Grimaldi - - Redwood - - Pass \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/docs/reference/oeps.rst b/docs/reference/oeps.rst index 420f7567..858ae0a8 100644 --- a/docs/reference/oeps.rst +++ b/docs/reference/oeps.rst @@ -8,18 +8,13 @@ you understand the major decisions made during the library's design. - The `Asynchronous Server Event Message Format (OEP-41)`_ specifies the header information format sent by the events. For a detailed description at the impact of the OEP-41, please refer to the Events Payload ADR. -**Maintenance chart** - -.. list-table:: -:header-rows: 1 -* - Review Date - - Working Group Reviewer - - Release - - Test Situation -* - 2025-02-05 - - BTR WG - Maria Grimaldi - - Redwood - - Pass - .. _Hooks extension framework (OEP-50): https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0050-hooks-extension-framework.html .. _Asynchronous Server Event Message Format (OEP-41): https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |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 2e3495a8..e8075cb2 100644 --- a/docs/reference/real-life-use-cases.rst +++ b/docs/reference/real-life-use-cases.rst @@ -130,19 +130,6 @@ Here are some additional use cases that can be implemented using Open edX Events .. note:: If you have implemented a solution using Open edX Events and would like to share it with the community, please submit a pull request to add it to this list! -**Maintenance chart** - -.. list-table:: -:header-rows: 1 -* - Review Date - - Working Group Reviewer - - Release - - Test Situation -* - 2025-02-05 - - BTR WG - Maria Grimaldi - - Redwood - - Pass - .. _edx-exams: https://github.com/edx/edx-exams .. _edx-proctoring: https://github.com/openedx/edx-proctoring .. _ADR Implementation of Event Driven Architecture for Exam Downstream Effects: https://github.com/edx/edx-exams/blob/main/docs/decisions/0004-downstream-effect-events.rst @@ -170,3 +157,11 @@ Here are some additional use cases that can be implemented using Open edX Events .. _Link User to Invite: https://github.com/academic-innovation/mogc-partnerships/blob/main/mogc_partnerships/receivers.py#L9 .. _Enterprise Unenrollment Sync: https://github.com/openedx/edx-enterprise/pull/1754 .. _IDV Integration with new Vendors: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/4307386369/Proposal+Add+Extensibility+Mechanisms+to+IDV+to+Enable+Integration+of+New+IDV+Vendor+Persona#Event-Hooks + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release |Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | ++--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file From 06af3aff4c1d93cdbfa3cbc18d70e763192a28a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Wed, 5 Feb 2025 19:52:08 -0500 Subject: [PATCH 07/14] docs: update real-life-use-cases --- docs/reference/real-life-use-cases.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/real-life-use-cases.rst b/docs/reference/real-life-use-cases.rst index e8075cb2..6abb9709 100644 --- a/docs/reference/real-life-use-cases.rst +++ b/docs/reference/real-life-use-cases.rst @@ -58,7 +58,7 @@ To make event tracking faster and more efficient, tracking logs are optionally s More details on: `Real-Time Event Tracking`_. Communication between Application Components -******************************************** +============================================== Open edX Events can also be used to facilitate communication between different application components running in the same process, allowing them to interact and synchronize their actions. Here are some examples of how Open edX Events can be used to coordinate between application components: From 2b3769dbb3c071ba4f1e04b85849493d2e751fd3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Wed, 5 Feb 2025 19:55:30 -0500 Subject: [PATCH 08/14] docs: fix commit errors --- docs/concepts/event-bus.rst | 2 +- docs/concepts/openedx-events.rst | 2 +- docs/reference/architecture-subdomains.rst | 2 +- docs/reference/event-bus-configurations.rst | 2 +- docs/reference/events-data.rst | 2 +- docs/reference/events-tooling.rst | 4 ++-- docs/reference/events.rst | 2 +- docs/reference/in-line-code-annotations-for-an-event.rst | 2 +- docs/reference/oeps.rst | 2 +- docs/reference/real-life-use-cases.rst | 2 +- 10 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/concepts/event-bus.rst b/docs/concepts/event-bus.rst index f820323b..e295b8a6 100644 --- a/docs/concepts/event-bus.rst +++ b/docs/concepts/event-bus.rst @@ -136,4 +136,4 @@ We encourage you to review the :doc:`../reference/real-life-use-cases` page for | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/concepts/openedx-events.rst b/docs/concepts/openedx-events.rst index e257e7e5..5a8baeb0 100644 --- a/docs/concepts/openedx-events.rst +++ b/docs/concepts/openedx-events.rst @@ -99,4 +99,4 @@ For more information on using Open edX Events, refer to the :doc:`../how-tos/cre | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/architecture-subdomains.rst b/docs/reference/architecture-subdomains.rst index 5cc2325b..91782b43 100644 --- a/docs/reference/architecture-subdomains.rst +++ b/docs/reference/architecture-subdomains.rst @@ -37,4 +37,4 @@ Here we list useful information about Open edX architecture subdomains and their | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/event-bus-configurations.rst b/docs/reference/event-bus-configurations.rst index 7024c8e9..08b2510f 100644 --- a/docs/reference/event-bus-configurations.rst +++ b/docs/reference/event-bus-configurations.rst @@ -12,4 +12,4 @@ Here are the available configurations for the event bus that are used to setup t | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/events-data.rst b/docs/reference/events-data.rst index a647a679..66cc7e9b 100644 --- a/docs/reference/events-data.rst +++ b/docs/reference/events-data.rst @@ -35,4 +35,4 @@ Enterprise Subdomain | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/events-tooling.rst b/docs/reference/events-tooling.rst index 6afda80d..5a3d4d16 100644 --- a/docs/reference/events-tooling.rst +++ b/docs/reference/events-tooling.rst @@ -6,11 +6,11 @@ Here we document the tooling available for working with Open edX events as a dev .. autoclass:: openedx_events.tooling.OpenEdxPublicSignal :members: - + **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/events.rst b/docs/reference/events.rst index aa60b37f..9781ff13 100644 --- a/docs/reference/events.rst +++ b/docs/reference/events.rst @@ -14,4 +14,4 @@ This is the list of Open edX events found in this repository. | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/in-line-code-annotations-for-an-event.rst b/docs/reference/in-line-code-annotations-for-an-event.rst index b4650d52..1f199ac5 100644 --- a/docs/reference/in-line-code-annotations-for-an-event.rst +++ b/docs/reference/in-line-code-annotations-for-an-event.rst @@ -39,4 +39,4 @@ Consider the following example: | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/oeps.rst b/docs/reference/oeps.rst index 858ae0a8..ec1842c6 100644 --- a/docs/reference/oeps.rst +++ b/docs/reference/oeps.rst @@ -17,4 +17,4 @@ you understand the major decisions made during the library's design. | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-05 | BTR WG - Maria Grimaldi |Redwood |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 6abb9709..90ff8600 100644 --- a/docs/reference/real-life-use-cases.rst +++ b/docs/reference/real-life-use-cases.rst @@ -164,4 +164,4 @@ Here are some additional use cases that can be implemented using Open edX Events | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ |2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file ++--------------+-------------------------------+----------------+--------------------------------+ From eddcf4523ba64d9a6f29ce0fa59bc1e30db04913 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Mon, 10 Feb 2025 17:39:09 -0500 Subject: [PATCH 09/14] docs: update docs/reference/oeps.rst Co-Authored-By: Sarina Canelake --- docs/concepts/event-bus.rst | 2 +- docs/concepts/openedx-events.rst | 2 +- docs/reference/architecture-subdomains.rst | 2 +- docs/reference/event-bus-configurations.rst | 3 ++- docs/reference/events-data.rst | 3 ++- docs/reference/events-tooling.rst | 3 ++- docs/reference/events.rst | 3 ++- docs/reference/in-line-code-annotations-for-an-event.rst | 3 ++- docs/reference/oeps.rst | 5 +++-- docs/reference/real-life-use-cases.rst | 3 ++- 10 files changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/concepts/event-bus.rst b/docs/concepts/event-bus.rst index e295b8a6..b3a27a30 100644 --- a/docs/concepts/event-bus.rst +++ b/docs/concepts/event-bus.rst @@ -135,5 +135,5 @@ We encourage you to review the :doc:`../reference/real-life-use-cases` page for +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | +|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/concepts/openedx-events.rst b/docs/concepts/openedx-events.rst index 5a8baeb0..66ab6b33 100644 --- a/docs/concepts/openedx-events.rst +++ b/docs/concepts/openedx-events.rst @@ -98,5 +98,5 @@ For more information on using Open edX Events, refer to the :doc:`../how-tos/cre +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | +|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/architecture-subdomains.rst b/docs/reference/architecture-subdomains.rst index 91782b43..151a656f 100644 --- a/docs/reference/architecture-subdomains.rst +++ b/docs/reference/architecture-subdomains.rst @@ -36,5 +36,5 @@ Here we list useful information about Open edX architecture subdomains and their +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | +|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/event-bus-configurations.rst b/docs/reference/event-bus-configurations.rst index 08b2510f..abd1135e 100644 --- a/docs/reference/event-bus-configurations.rst +++ b/docs/reference/event-bus-configurations.rst @@ -11,5 +11,6 @@ Here are the available configurations for the event bus that are used to setup t +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | +|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ + diff --git a/docs/reference/events-data.rst b/docs/reference/events-data.rst index 66cc7e9b..6875bfe2 100644 --- a/docs/reference/events-data.rst +++ b/docs/reference/events-data.rst @@ -34,5 +34,6 @@ Enterprise Subdomain +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | +|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ + diff --git a/docs/reference/events-tooling.rst b/docs/reference/events-tooling.rst index 5a3d4d16..04ccec20 100644 --- a/docs/reference/events-tooling.rst +++ b/docs/reference/events-tooling.rst @@ -12,5 +12,6 @@ Here we document the tooling available for working with Open edX events as a dev +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | +|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ + diff --git a/docs/reference/events.rst b/docs/reference/events.rst index 9781ff13..4db4e59c 100644 --- a/docs/reference/events.rst +++ b/docs/reference/events.rst @@ -13,5 +13,6 @@ This is the list of Open edX events found in this repository. +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | +|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ + diff --git a/docs/reference/in-line-code-annotations-for-an-event.rst b/docs/reference/in-line-code-annotations-for-an-event.rst index 1f199ac5..a278521f 100644 --- a/docs/reference/in-line-code-annotations-for-an-event.rst +++ b/docs/reference/in-line-code-annotations-for-an-event.rst @@ -38,5 +38,6 @@ Consider the following example: +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | +|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ + diff --git a/docs/reference/oeps.rst b/docs/reference/oeps.rst index ec1842c6..498ed50d 100644 --- a/docs/reference/oeps.rst +++ b/docs/reference/oeps.rst @@ -6,7 +6,7 @@ you understand the major decisions made during the library's design. - The `Hooks extension framework (OEP-50)`_ specifies its motivation, implementation details, rationale, performance considerations, general use cases, and more. The goal of the OEP-50 is to give the extensions' developer a glance at the framework implementation and design. -- The `Asynchronous Server Event Message Format (OEP-41)`_ specifies the header information format sent by the events. For a detailed description at the impact of the OEP-41, please refer to the Events Payload ADR. +- The `Asynchronous Server Event Message Format (OEP-41)`_ specifies the header information format sent by the events. For a detailed description of the impact of the OEP-41, please refer to the Events Payload ADR. .. _Hooks extension framework (OEP-50): https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0050-hooks-extension-framework.html .. _Asynchronous Server Event Message Format (OEP-41): https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html @@ -16,5 +16,6 @@ you understand the major decisions made during the library's design. +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | +|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ + diff --git a/docs/reference/real-life-use-cases.rst b/docs/reference/real-life-use-cases.rst index 90ff8600..defed130 100644 --- a/docs/reference/real-life-use-cases.rst +++ b/docs/reference/real-life-use-cases.rst @@ -163,5 +163,6 @@ Here are some additional use cases that can be implemented using Open edX Events +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi |Redwood |Pass. | +|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ + From c1a710fd8c51a1445272b551fb99a34fc831cbb5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Mon, 10 Feb 2025 17:38:54 -0500 Subject: [PATCH 10/14] docs: update docs/concepts/openedx-events.rst Co-Authored-By: Sarina Canelake --- docs/concepts/openedx-events.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/openedx-events.rst b/docs/concepts/openedx-events.rst index 66ab6b33..9efb841a 100644 --- a/docs/concepts/openedx-events.rst +++ b/docs/concepts/openedx-events.rst @@ -14,7 +14,7 @@ Open edX Events are signals emitted by a service (e.g., LMS, CMS, or others) wit These events are built on top of Django signals, inheriting their behavior while also incorporating metadata and actions specific to the Open edX ecosystem, making them uniquely suited for Open edX. Since they are essentially Django signals tailored to Open edX's specific needs, we can refer to `Django Signals Documentation`_ for a more detailed understanding of Open edX Events. -.. note:: Django includes a "signal dispatcher", which helps decoupled applications be notified when actions occur elsewhere in the framework. In a nutshell, signals allow certain senders to notify a set of receivers that some action has taken place. They're especially useful when many pieces of code may be interested in the same events. +.. note:: Django includes a "signal dispatcher", which helps decoupled applications get notified when actions occur elsewhere in the framework. In a nutshell, signals allow certain senders to notify a set of receivers that some action has taken place. They're especially useful when many pieces of code may be interested in the same events. Events are primarily used as a communication method between internal services by leveraging Django Signals and external services using the :doc:`../concepts/event-bus`, making them the standard communication mechanism within the Open edX ecosystem. From b3b51392abc00991a48004f94a8c8f82431a7241 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Mon, 10 Feb 2025 17:38:37 -0500 Subject: [PATCH 11/14] docs: update docs/concepts/event-bus.rst Co-Authored-By: Sarina Canelake --- docs/concepts/event-bus.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/event-bus.rst b/docs/concepts/event-bus.rst index b3a27a30..f2f5b1cb 100644 --- a/docs/concepts/event-bus.rst +++ b/docs/concepts/event-bus.rst @@ -22,7 +22,7 @@ The :term:`Event Bus` can help us achieve loose coupling between services, repla * **Eliminate Blocking, Synchronous Requests**: reduce site outages when services become overloaded with requests by replacing synchronous calls with asynchronous communication. * **Eliminate Expensive, Delayed, Batch Synchronization**: replace expensive batch processing with near real-time data updates. -* **Reduce the Need for Plugins**: reduce the computational load for plugins that don't need to run in the same process by allowing cross-service communication of lifecycle events. +* **Reduce the need for Plugins**: reduce the computational load for plugins that don't need to run in the same process by allowing cross-service communication of lifecycle events. How Does the Open edX Event Bus Work? *************************************** From 748d7ae9ff0d50fb031d0b837b2fcd4fd2a194f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Wed, 12 Feb 2025 20:21:12 -0500 Subject: [PATCH 12/14] docs: update docs/concepts/event-bus.rst Co-Authored-By: Maria Grimaldi --- docs/concepts/event-bus.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/event-bus.rst b/docs/concepts/event-bus.rst index f2f5b1cb..ccbfca50 100644 --- a/docs/concepts/event-bus.rst +++ b/docs/concepts/event-bus.rst @@ -31,7 +31,7 @@ The Open edX platform uses the ``OpenEdxPublicSignals`` (Open edX-specific Djang Open edX Events provides an abstract implementation of the `publish/subscribe messaging pattern`_ (pub/sub), which is the chosen pattern for the event bus implementation, as explained in :doc:`openedx-proposals:architectural-decisions/oep-0052-arch-event-bus-architecture`. It implements two abstract classes, `EventProducer`_ and `EventConsumer`_, which allow concrete implementations of the event bus based on different message brokers, such as Pulsar. -This abstraction allows for developers to implement their own concrete implementations of the event bus in their own plugins. There are currently two implementations of the event bus, Redis (`event-bus-redis`_) and Kafka (`event-bus-kafka`_). Redis streams is a data structure that acts like an append-only log, and Kafka is a distributed event streaming application. Both implementations handle event production and consumption using technology-specific methods.. +This abstraction allows for developers to implement their own concrete implementations of the event bus in their own plugins. There are currently two implementations of the event bus, Redis (`event-bus-redis`_) and Kafka (`event-bus-kafka`_). Redis streams is a data structure that acts like an append-only log, and Kafka is a distributed event streaming application. Both implementations handle event production and consumption using technology-specific methods. Architectural Diagram ********************* From f0f52a8807a58a6cbbcb044b0898db6697cc88e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ana=20Paula=20G=C3=B3mez?= <131492787+Apgomeznext@users.noreply.github.com> Date: Wed, 12 Feb 2025 20:34:33 -0500 Subject: [PATCH 13/14] docs: maintenance chart fix Co-Authored-By: Maria Grimaldi --- docs/concepts/event-bus.rst | 4 ++-- docs/concepts/openedx-events.rst | 4 ++-- docs/reference/architecture-subdomains.rst | 4 ++-- docs/reference/event-bus-configurations.rst | 5 ++--- docs/reference/events-data.rst | 4 ++-- docs/reference/events-tooling.rst | 4 ++-- docs/reference/events.rst | 4 ++-- docs/reference/in-line-code-annotations-for-an-event.rst | 4 ++-- docs/reference/oeps.rst | 4 ++-- docs/reference/real-life-use-cases.rst | 4 ++-- 10 files changed, 20 insertions(+), 21 deletions(-) diff --git a/docs/concepts/event-bus.rst b/docs/concepts/event-bus.rst index ccbfca50..ee34646f 100644 --- a/docs/concepts/event-bus.rst +++ b/docs/concepts/event-bus.rst @@ -133,7 +133,7 @@ We encourage you to review the :doc:`../reference/real-life-use-cases` page for **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | +| Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +|2025-02-05 | Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/concepts/openedx-events.rst b/docs/concepts/openedx-events.rst index 9efb841a..928b8146 100644 --- a/docs/concepts/openedx-events.rst +++ b/docs/concepts/openedx-events.rst @@ -96,7 +96,7 @@ For more information on using Open edX Events, refer to the :doc:`../how-tos/cre **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | +| Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +|2025-02-05 | Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/architecture-subdomains.rst b/docs/reference/architecture-subdomains.rst index 151a656f..38a1087c 100644 --- a/docs/reference/architecture-subdomains.rst +++ b/docs/reference/architecture-subdomains.rst @@ -34,7 +34,7 @@ Here we list useful information about Open edX architecture subdomains and their **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | +| Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +|2025-02-05 | Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/event-bus-configurations.rst b/docs/reference/event-bus-configurations.rst index abd1135e..53e2019a 100644 --- a/docs/reference/event-bus-configurations.rst +++ b/docs/reference/event-bus-configurations.rst @@ -9,8 +9,7 @@ Here are the available configurations for the event bus that are used to setup t **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | +| Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +|2025-02-05 | Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ - diff --git a/docs/reference/events-data.rst b/docs/reference/events-data.rst index 6875bfe2..c7d952da 100644 --- a/docs/reference/events-data.rst +++ b/docs/reference/events-data.rst @@ -32,8 +32,8 @@ Enterprise Subdomain **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | +| Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +|2025-02-05 | Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/events-tooling.rst b/docs/reference/events-tooling.rst index 04ccec20..a07ed2d7 100644 --- a/docs/reference/events-tooling.rst +++ b/docs/reference/events-tooling.rst @@ -10,8 +10,8 @@ Here we document the tooling available for working with Open edX events as a dev **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | +| Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +|2025-02-05 | Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/events.rst b/docs/reference/events.rst index 4db4e59c..f3fe9729 100644 --- a/docs/reference/events.rst +++ b/docs/reference/events.rst @@ -11,8 +11,8 @@ This is the list of Open edX events found in this repository. **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | +| Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +|2025-02-05 | Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/in-line-code-annotations-for-an-event.rst b/docs/reference/in-line-code-annotations-for-an-event.rst index a278521f..7c79bb3f 100644 --- a/docs/reference/in-line-code-annotations-for-an-event.rst +++ b/docs/reference/in-line-code-annotations-for-an-event.rst @@ -36,8 +36,8 @@ Consider the following example: **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | +| Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +|2025-02-05 | Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/oeps.rst b/docs/reference/oeps.rst index 498ed50d..242c6508 100644 --- a/docs/reference/oeps.rst +++ b/docs/reference/oeps.rst @@ -14,8 +14,8 @@ you understand the major decisions made during the library's design. **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | +| Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +|2025-02-05 | Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/docs/reference/real-life-use-cases.rst b/docs/reference/real-life-use-cases.rst index defed130..e20a3302 100644 --- a/docs/reference/real-life-use-cases.rst +++ b/docs/reference/real-life-use-cases.rst @@ -161,8 +161,8 @@ Here are some additional use cases that can be implemented using Open edX Events **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | +| Review Date | Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -|2025-02-05 | BTR WG - Maria Grimaldi | Sumac |Pass. | +|2025-02-05 | Maria Grimaldi | Sumac |Pass. | +--------------+-------------------------------+----------------+--------------------------------+ From 0fd855194a4fd1bba782693a4244b1e7e803ae91 Mon Sep 17 00:00:00 2001 From: Sarina Canelake Date: Thu, 13 Feb 2025 10:56:07 -0500 Subject: [PATCH 14/14] docs: Use "Open edX" as an adjective --- docs/concepts/openedx-events.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/openedx-events.rst b/docs/concepts/openedx-events.rst index 928b8146..9be5583d 100644 --- a/docs/concepts/openedx-events.rst +++ b/docs/concepts/openedx-events.rst @@ -12,7 +12,7 @@ What Are Open edX Events? Open edX Events are signals emitted by a service (e.g., LMS, CMS, or others) within the Open edX ecosystem to notify that an action has occurred. For example, a user may have registered, logged in, or created a course. -These events are built on top of Django signals, inheriting their behavior while also incorporating metadata and actions specific to the Open edX ecosystem, making them uniquely suited for Open edX. Since they are essentially Django signals tailored to Open edX's specific needs, we can refer to `Django Signals Documentation`_ for a more detailed understanding of Open edX Events. +These events are built on top of Django signals, inheriting their behavior while also incorporating metadata and actions specific to the Open edX ecosystem, making them uniquely suited for the Open edX use cases. Since they are essentially Django signals tailored to the Open edX platform's specific needs, we can refer to `Django Signals Documentation`_ for a more detailed understanding of Open edX Events. .. note:: Django includes a "signal dispatcher", which helps decoupled applications get notified when actions occur elsewhere in the framework. In a nutshell, signals allow certain senders to notify a set of receivers that some action has taken place. They're especially useful when many pieces of code may be interested in the same events.