Skip to content

Commit

Permalink
docs: Update openedx-events.rst
Browse files Browse the repository at this point in the history
PR to Update openedx-events.rst and fix an error
  • Loading branch information
Apgomeznext committed Feb 4, 2025
1 parent b029dc1 commit ed623b6
Showing 1 changed file with 13 additions and 9 deletions.
22 changes: 13 additions & 9 deletions docs/concepts/openedx-events.rst
Original file line number Diff line number Diff line change
@@ -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
*********************
Expand All @@ -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.

Expand All @@ -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.
Expand All @@ -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?
*****************************

Expand Down

0 comments on commit ed623b6

Please sign in to comment.