From a3b0728a4ebe783b1fbbb3b1d650825663f3825b Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 11 Nov 2024 09:59:15 -0400 Subject: [PATCH] docs: apply suggestions from code review --- docs/reference/real-life-use-cases.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/reference/real-life-use-cases.rst b/docs/reference/real-life-use-cases.rst index 072afbf8..53554a06 100644 --- a/docs/reference/real-life-use-cases.rst +++ b/docs/reference/real-life-use-cases.rst @@ -4,25 +4,23 @@ Real-Life Use Cases for Open edX Events Overview -------- -As mentioned in the Hooks Extension Framework, 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. +As mentioned in the Hooks Extension Framework overview, 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 framework, we have compiled a list of implementations built using Open edX Events to address various challenges. +To illustrate the different solutions that can be implemented with this framework, 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. Communication, coordination or synchronization between IDAs ------------------------------------------------------------ -Communication between IDAs in the Open edX ecosystem is currently managed through an event-based architecture implemented via Event Bus. - -The Event Bus functionality for asynchronous communication between services is built on top of sending Open edX Events (Open edX-specific Django signals) within a service. The Event Bus extends these signals, allowing them to be broadcast and handled across multiple services. For more details on the Event Bus, please see `How to Start Using the Event Bus`_. +The suggested strategy for communicating IDAs efficiently in the Open edX ecosystem is through an event-based architecture implemented via the 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. The Event Bus extends these signals, allowing them to be broadcast and handled across multiple services. For more details on the Event Bus, please see `How to Start Using the Event Bus`_. 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 allows edx-exams to emit events, triggering responses like grade overrides without creating dependencies between the two. +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. This approach implements a modular and scalable system by enabling edx-exams to function independently from edx-platform while still interacting through asynchronous communication. @@ -38,21 +36,21 @@ 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 consumed by the Credentials service. Based on the event type, the credentials can automatically award or revoke learner credentials. This integration simplifies credential management by enabling real-time updates from the LMS, ensuring appropiate generation of learner credentials without requiring manual synchronization. +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, to the event bus. The Credentials service then receives these events, adds extra information, and forwards them to external credential providers such as Credly, Accredible, or OBv3. These providers create and display digital credentials for learners based on the completion data. +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, Accredible, or OBv3. 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 signal listens for each tracking event and sends it directly 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. +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. More details on: `Real-Time Event Tracking`_. @@ -73,8 +71,10 @@ Keep Search Indexes Up-To-Date Each time content is updated or created, an event is emitted that triggers Meilisearch to index 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 -****************************** +******************************* Open edX 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. @@ -83,7 +83,7 @@ More details on: `External Certificate Generation`_. Automatic Group Association ************************** -Open edX Events are sent after a user enrolls into a course, these 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 manually add a student into a cohort but it's automatically done reducing logistic efforts and a seamless integration with language-based restricted content. +Enrollment-related 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 a seamless integration with language-based restricted content. More details on: `Automatic Group Association`_. @@ -97,14 +97,14 @@ More details on: `Linking In-Context Discussions to Units`_. Forum Emails Notifier with Digest Frequency ******************************************* -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 and customize digest frequency for instructors. +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 with Digest Frequency`_. Webhooks Integration ******************** -A Webhook is a mechanism that triggers an HTTP POST request to a configurable URL when certain events happen in the 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. +`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. More details on: