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..4ab45336 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 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 new file mode 100644 index 00000000..b8c78b53 --- /dev/null +++ b/docs/reference/glossary.rst @@ -0,0 +1,41 @@ +Open edX Events Glossary +########################## + +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. + +.. 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. + + 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. 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``. + + 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` 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