From 57cf4c888d243b9d9283486546415f1634242d60 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Fri, 11 Oct 2024 15:18:25 +0200 Subject: [PATCH 1/5] docs: add glossary for openedx-events ecosystem --- docs/reference/glossary.rst | 47 +++++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 2 files changed, 48 insertions(+) create mode 100644 docs/reference/glossary.rst diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst new file mode 100644 index 00000000..e3887f4c --- /dev/null +++ b/docs/reference/glossary.rst @@ -0,0 +1,47 @@ +Open edX Events Glossary +########################## + +This glossary provides definitions for some of the terms to ease the adoption +of the Open edX Events library. + +Event Receiver +-------------- + +An event receiver, handler or listener is a function that listens for a specific +event and executes custom logic in response to the event being triggered. Since +Events are Django-signals, then receivers are registered with the signal +dispatcher and are called when the event is emitted. In Django, event receivers +are known as signal handlers. Both terms are used interchangeably. + +Event Trigger +------------- + +An event trigger is the action that causes an event to be emitted. When a +trigger action occurs, the associated event is emitted, and any registered event +receivers are called to handle the event. + +Event Payload +------------- + +The event payload is the data associated with an event that is passed to event +receivers when it's triggered. The payload of an event are data attribute classes (e.g. `CourseEnrollmentData`, `UserData`, etc.) +that carry data about the event such as the event name, timestamp, and any additional +metadata and information about the actual event. For more information, see the +`ADR: Events Payload`_. + +Event Type +---------- + +The event type is a unique identifier for an event that distinguishes it from +other events. For example, `org.openedx.content_authoring.xblock.published.v1`. The event type is used to +identify the event, its purpose, and version. In the event-bus context, the event +type is used to connect events to the appropriate topics in the ``EVENT_BUS_PRODUCER_CONFIG``. + +Event Definition +---------------- + +An event definition is the instantiation of the `OpenEdxPublicSignal` class that +defines the structure and metadata of an event. The event definition includes +information such as the event name, description, payload, and version. Event +definitions are used to create events which are later imported into the +application and used to trigger events using the `send_event` method. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 685938eb..61d3984d 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -6,5 +6,6 @@ References :caption: Contents: events + glossary oeps architecture-subdomains From 43571e1ae05344fa195e10627cd8de0699b1f98c Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 4 Nov 2024 14:37:34 +0100 Subject: [PATCH 2/5] refactor: use glossary format for glossary --- docs/reference/glossary.rst | 50 +++++++++---------------------------- 1 file changed, 12 insertions(+), 38 deletions(-) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index e3887f4c..5bdc5bd2 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -1,47 +1,21 @@ Open edX Events Glossary ########################## -This glossary provides definitions for some of the terms to ease the adoption -of the Open edX Events library. +An event has multiple components that are used to define, trigger, and handle the event. This glossary provides definitions for some of the terms to ease the adoption of the Open edX Events library. -Event Receiver --------------- +.. glossary:: -An event receiver, handler or listener is a function that listens for a specific -event and executes custom logic in response to the event being triggered. Since -Events are Django-signals, then receivers are registered with the signal -dispatcher and are called when the event is emitted. In Django, event receivers -are known as signal handlers. Both terms are used interchangeably. + Event Receiver + An event receiver, handler or listener is a function that listens for a specific event and executes custom logic in response to the event being triggered. Since Events are Django-signals, then receivers are registered with the signal dispatcher and are called when the event is emitted. In Django, event receivers are known as signal handlers. Both terms are used interchangeably. -Event Trigger -------------- + Event Trigger + An event trigger is the action that causes an event to be emitted. When a trigger action occurs, the associated event is emitted, and any registered event receivers are called to handle the event. -An event trigger is the action that causes an event to be emitted. When a -trigger action occurs, the associated event is emitted, and any registered event -receivers are called to handle the event. + Event Payload + The event payload is the data associated with an event that is passed to event receivers when it's triggered. The payload of an event are data attribute classes (e.g. ``CourseEnrollmentData``, ``UserData``, etc.) that carry data about the event such as the event name, timestamp, and any additional metadata and information about the actual event. For more information, see the `ADR: Events Payload`_. -Event Payload -------------- + Event Type + The event type is a unique identifier for an event that distinguishes it from other events. For example, ``org.openedx.content_authoring.xblock.published.v1``. The event type is used to identify the event, its purpose, and version. In the event-bus context, the event type is used to connect events to the appropriate topics in the ``EVENT_BUS_PRODUCER_CONFIG``. -The event payload is the data associated with an event that is passed to event -receivers when it's triggered. The payload of an event are data attribute classes (e.g. `CourseEnrollmentData`, `UserData`, etc.) -that carry data about the event such as the event name, timestamp, and any additional -metadata and information about the actual event. For more information, see the -`ADR: Events Payload`_. - -Event Type ----------- - -The event type is a unique identifier for an event that distinguishes it from -other events. For example, `org.openedx.content_authoring.xblock.published.v1`. The event type is used to -identify the event, its purpose, and version. In the event-bus context, the event -type is used to connect events to the appropriate topics in the ``EVENT_BUS_PRODUCER_CONFIG``. - -Event Definition ----------------- - -An event definition is the instantiation of the `OpenEdxPublicSignal` class that -defines the structure and metadata of an event. The event definition includes -information such as the event name, description, payload, and version. Event -definitions are used to create events which are later imported into the -application and used to trigger events using the `send_event` method. + Event Definition + An event definition (or simply, event) is the instantiation of the ``OpenEdxPublicSignal`` class that defines the structure and metadata of an event. This definition includes information such as the event name, description, payload, and version. Event definitions are used to create events which are later imported into the services and are triggered by using the ``send_event`` method. From 8d637ad256e9d8b5c7434642b7cf4372d5558199 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 4 Nov 2024 14:42:12 +0100 Subject: [PATCH 3/5] fix: add missing reference for event payload ADR --- docs/reference/glossary.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 5bdc5bd2..8a368e96 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -12,10 +12,12 @@ An event has multiple components that are used to define, trigger, and handle th An event trigger is the action that causes an event to be emitted. When a trigger action occurs, the associated event is emitted, and any registered event receivers are called to handle the event. Event Payload - The event payload is the data associated with an event that is passed to event receivers when it's triggered. The payload of an event are data attribute classes (e.g. ``CourseEnrollmentData``, ``UserData``, etc.) that carry data about the event such as the event name, timestamp, and any additional metadata and information about the actual event. For more information, see the `ADR: Events Payload`_. + The event payload is the data associated with an event that is passed to event receivers when it's triggered. The payload of an event are data attribute classes (e.g. ``CourseEnrollmentData``, ``UserData``, etc.) that carry data about the event such as the event name, timestamp, and any additional metadata and information about the actual event. For more information, see the `Events Payload ADR`_. Event Type The event type is a unique identifier for an event that distinguishes it from other events. For example, ``org.openedx.content_authoring.xblock.published.v1``. The event type is used to identify the event, its purpose, and version. In the event-bus context, the event type is used to connect events to the appropriate topics in the ``EVENT_BUS_PRODUCER_CONFIG``. Event Definition An event definition (or simply, event) is the instantiation of the ``OpenEdxPublicSignal`` class that defines the structure and metadata of an event. This definition includes information such as the event name, description, payload, and version. Event definitions are used to create events which are later imported into the services and are triggered by using the ``send_event`` method. + +.. _Events Payload ADR: :doc: `/decisions/0003-events-payload` From 76514671abab5e15023b406cc9edf0e63e953a53 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 4 Nov 2024 14:51:51 +0100 Subject: [PATCH 4/5] refactor: reference glossary terms throughout documents --- docs/how-tos/creating-new-events.rst | 8 ++++---- docs/how-tos/using-events.rst | 4 ++-- docs/quickstarts/use-events-to-call-webhook.rst | 10 +++++----- docs/reference/glossary.rst | 2 +- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/how-tos/creating-new-events.rst b/docs/how-tos/creating-new-events.rst index 2920a424..63872873 100644 --- a/docs/how-tos/creating-new-events.rst +++ b/docs/how-tos/creating-new-events.rst @@ -19,7 +19,7 @@ if you have time, you could accompany your proposal with the implementation of t 2. Place your event in an architecture subdomain ------------------------------------------------- -As specified in the Architectural Decisions Record (ADR) events naming and versioning, the event definition needs an Open edX Architecture +As specified in the Architectural Decisions Record (ADR) events naming and versioning, the :term:`event definition ` needs an Open edX Architecture Subdomain for: - The name of the event: ``{Reverse DNS}.{Architecture Subdomain}.{Subject}.{Action}.{Major Version}`` @@ -43,7 +43,7 @@ Refer to `edX DDD Bounded Contexts 3. Create the data attributes for the event (OEP-49) ---------------------------------------------------- -Events send `data attributes `_ when triggered. Therefore, when designing your new event definition you must +Events send `data attributes `_ when triggered. Therefore, when designing your new :term:`event definition ` you must decide if an existent data class works for your use case or you must create a new one. If the answer is the latter, then try to answer: - Which attributes of the object are the most relevant? @@ -103,10 +103,10 @@ Consider the user data representation as an example: 4. Create the event definition ------------------------------ -Open edX Events are instances of the class OpenEdxPublicSignal, this instance represents the event definition that +Open edX Events are instances of the class OpenEdxPublicSignal, this instance represents the :term:`event definition ` that specifies: -- The event type which should follow the conventions in the Naming Conventions ADR. +- The :term:`event type ` which should follow the conventions in the Naming Conventions ADR. - The events' payload, here you must use the class you decided on before. The definition created in this step must comply with: diff --git a/docs/how-tos/using-events.rst b/docs/how-tos/using-events.rst index a7acc628..dcdf569e 100644 --- a/docs/how-tos/using-events.rst +++ b/docs/how-tos/using-events.rst @@ -16,7 +16,7 @@ an event and you want to react to it in your plugin. For this you need to: 1. Include openedx-events in your dependencies. -2. Connect your receiver functions to the signals being sent. +2. Connect your :term:`receiver ` functions to the signals being sent. Connecting signals can be done using regular django syntax: @@ -59,7 +59,7 @@ plugin system. Sending events ^^^^^^^^^^^^^^ -Sending events requires you to import both the event definition as well as the +Sending events requires you to import both the :term:`event definition ` as well as the attr data classes that encapsulate the event data. .. code-block:: python diff --git a/docs/quickstarts/use-events-to-call-webhook.rst b/docs/quickstarts/use-events-to-call-webhook.rst index 3d8b4d86..6bfa2c63 100644 --- a/docs/quickstarts/use-events-to-call-webhook.rst +++ b/docs/quickstarts/use-events-to-call-webhook.rst @@ -32,9 +32,9 @@ Configuration The package we just installed is a `Django plugin`_, which adds additional configurations to our working environment thanks to the extension mechanisms put in place. Now, -signal receivers are listening to the registration and enrollment events sent within the LMS service. +:term:`event receivers ` are listening to the registration and enrollment events sent within the LMS service. -The following is the implementation for the signal receiver listening for the event ``STUDENT_REGISTRATION_COMPLETED``: +The following is the implementation for the `event receivers ` listening for the event ``STUDENT_REGISTRATION_COMPLETED``: .. code-block:: python @@ -97,7 +97,7 @@ The following is the implementation for the signal receiver listening for the ev flatten_dict(zapier_payload), ) -Those receivers work out of the box after the plugin installation. Now, we must +Those `event receivers ` work out of the box after the plugin installation. Now, we must set the plugin settings which indicate where to send the events data. For this, go to ``env/apps/openedx/settings/development.py`` and add your Zapier configuration: @@ -109,7 +109,7 @@ go to ``env/apps/openedx/settings/development.py`` and add your Zapier configura Getting data from Zapier ------------------------ -Now that you have configured both receivers, you'll need to trigger the events +Now that you have configured both `event receivers `, you'll need to trigger the events so you receive the events data in Zapier. Try it out! .. _openedx-events-2-zapier: https://github.com/eduNEXT/openedx-events-2-zapier @@ -117,5 +117,5 @@ so you receive the events data in Zapier. Try it out! .. _Django plugin: https://github.com/openedx/edx-django-utils/blob/master/edx_django_utils/plugins/README.rst .. warning:: - The receiver function implemented in this tutorial was intended to be lightweight, just to serve as an example for events' receivers. However, in production + The `event receiver ` function implemented in this tutorial was intended to be lightweight, just to serve as an example for events' receivers. However, in production settings, we encourage the use of asynchronous tasks to avoid creating bottlenecks. diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 8a368e96..b2242f0c 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -18,6 +18,6 @@ An event has multiple components that are used to define, trigger, and handle th The event type is a unique identifier for an event that distinguishes it from other events. For example, ``org.openedx.content_authoring.xblock.published.v1``. The event type is used to identify the event, its purpose, and version. In the event-bus context, the event type is used to connect events to the appropriate topics in the ``EVENT_BUS_PRODUCER_CONFIG``. Event Definition - An event definition (or simply, event) is the instantiation of the ``OpenEdxPublicSignal`` class that defines the structure and metadata of an event. This definition includes information such as the event name, description, payload, and version. Event definitions are used to create events which are later imported into the services and are triggered by using the ``send_event`` method. + An event is a signal that is emitted when a specific action occurs in the platform. The event definition is the instantiation of the ``OpenEdxPublicSignal`` class that defines the structure and metadata of an event. This definition includes information such as the event name, description, payload, and version. Event definitions are used to create events which are later imported into the services and are triggered by using the ``send_event`` method. .. _Events Payload ADR: :doc: `/decisions/0003-events-payload` From b85e1016a1c24e82cc82c7ad948e02b629bbe7ad Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 4 Nov 2024 23:57:16 +0100 Subject: [PATCH 5/5] refactor: address PR reviews --- .../use-events-to-call-webhook.rst | 2 +- docs/reference/glossary.rst | 24 ++++++++++++++++--- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/quickstarts/use-events-to-call-webhook.rst b/docs/quickstarts/use-events-to-call-webhook.rst index 6bfa2c63..4ab45336 100644 --- a/docs/quickstarts/use-events-to-call-webhook.rst +++ b/docs/quickstarts/use-events-to-call-webhook.rst @@ -117,5 +117,5 @@ so you receive the events data in Zapier. Try it out! .. _Django plugin: https://github.com/openedx/edx-django-utils/blob/master/edx_django_utils/plugins/README.rst .. warning:: - The `event receiver ` function implemented in this tutorial was intended to be lightweight, just to serve as an example for events' receivers. However, in production + The `event receiver ` function implemented in this tutorial was intended to be lightweight, just to serve as an example for event receivers. However, in production settings, we encourage the use of asynchronous tasks to avoid creating bottlenecks. diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index b2242f0c..b8c78b53 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -6,18 +6,36 @@ An event has multiple components that are used to define, trigger, and handle th .. glossary:: Event Receiver - An event receiver, handler or listener is a function that listens for a specific event and executes custom logic in response to the event being triggered. Since Events are Django-signals, then receivers are registered with the signal dispatcher and are called when the event is emitted. In Django, event receivers are known as signal handlers. Both terms are used interchangeably. + An event receiver, handler, or listener is a function that listens for a specific event and executes custom logic in response to the event being triggered. Since Events are Django-signals, then receivers are registered with the signal dispatcher and are called when the event is emitted. In Django, event receivers are known as signal handlers. Both terms are used interchangeably. Event Trigger - An event trigger is the action that causes an event to be emitted. When a trigger action occurs, the associated event is emitted, and any registered event receivers are called to handle the event. + An event trigger is the action that causes an event to be emitted. When a trigger action occurs, the associated event is emitted, and any registered event receivers are called to handle the event. For example, when a user enrolls in a course, the ``COURSE_ENROLLMENT_CREATED`` event is triggered. In this case, the event trigger is the user enrolling in the course. Event Payload The event payload is the data associated with an event that is passed to event receivers when it's triggered. The payload of an event are data attribute classes (e.g. ``CourseEnrollmentData``, ``UserData``, etc.) that carry data about the event such as the event name, timestamp, and any additional metadata and information about the actual event. For more information, see the `Events Payload ADR`_. Event Type - The event type is a unique identifier for an event that distinguishes it from other events. For example, ``org.openedx.content_authoring.xblock.published.v1``. The event type is used to identify the event, its purpose, and version. In the event-bus context, the event type is used to connect events to the appropriate topics in the ``EVENT_BUS_PRODUCER_CONFIG``. + The event type is a unique identifier for an event that distinguishes it from other events. For example, ``org.openedx.content_authoring.xblock.published.v1``. The event type is used to identify the event, its purpose, and version. In the event bus context, the event type is used to connect events to the appropriate topics in the ``EVENT_BUS_PRODUCER_CONFIG``. Event Definition An event is a signal that is emitted when a specific action occurs in the platform. The event definition is the instantiation of the ``OpenEdxPublicSignal`` class that defines the structure and metadata of an event. This definition includes information such as the event name, description, payload, and version. Event definitions are used to create events which are later imported into the services and are triggered by using the ``send_event`` method. + Event Bus + To be added soon. + + Event Bus Producer + To be added soon. + + Event Bus Consumer + To be added soon. + + Event Bus Topic + To be added soon. + + Event Bus Producer Config + To be added soon. + + Event Bus Settings + To be added soon. + .. _Events Payload ADR: :doc: `/decisions/0003-events-payload`