docs: [FC-0074] add docs about creating and consuming events #439

mariajgrimaldi · 2024-12-19T16:58:06Z

Description

Update how-to documents to create and consume a new event considering design suggestions introduced in #438 and old docs as well.

Here are the main documents to review:

How to Create a New Event with Long-Term Support: https://github.com/openedx/openedx-events/pull/439/files#diff-4ddc667d74faa397c775466201343c217838a6b92c089cff0fdd015d3d7918c9
Consume an Event: https://github.com/openedx/openedx-events/pull/439/files#diff-bbbb0da0a033c988afb7eefca64da1f676a6b7c5d343904e77c865fd5f22cacf

The other changes are improvements to the current docs:

Change continuous to imperative verb forms in titles
Add assumptions for each how-to
Complete reference for architecture subdomains

Supporting information

Addresses #360 #362

Testing instructions

You can review the docs here: https://docsopenedxorg--439.org.readthedocs.build/projects/openedx-events/en/439/.
It'd also be incredibly useful to follow the guide to verify the steps.

Deadline

None

Other information

Depends on feedback on #438

Checklists

Check off if complete or not applicable:

Merge Checklist:

Post Merge:

Create a tag
Create a release on GitHub
Check new version is pushed to PyPI after tag-triggered build is
finished.
Delete working branch (if not needed anymore)
Upgrade the package in the Open edX platform requirements (if applicable)

openedx-webhooks · 2024-12-19T16:58:11Z

Thanks for the pull request, @mariajgrimaldi!

What's next?

Please work through the following steps to get your changes ready for engineering review:

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Let us know that your PR is ready for review:

Who will review my changes?

This repository is currently maintained by @openedx/hooks-extension-framework. Tag them in a comment and let them know that your changes are ready for review.

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

sarina · 2025-01-06T15:36:30Z

docs/reference/architecture-subdomains.rst

+-------------------+----------------------------------------------------------------------------------------------------+
+| Learning          | Allows learners to consume content and perform actions in a learning activity on the platform.     |
+-------------------+----------------------------------------------------------------------------------------------------+
+| Analytics         | Provides insights into learner behavior and course performance.                                    |


I think I commented this on a previous PR, but I'd avoid use of the term "insights" here so it's not confused with the Insights deprecated service.

Thanks for raising this. I used "visibility" instead.

MaferMazu

I only have a few suggestions. The rest looks good.

Thanks for this PR @mariajgrimaldi

MaferMazu · 2025-01-07T23:33:03Z

docs/how-tos/consume-an-event.rst

+
+- You have a development environment set up using `Tutor`_.
+- You have a basic understanding of Python and Django.
+- You have created a new Open edX event. If not, you can follow the :doc:`../how-tos/create-a-new-event` guide to create a new event.


We may want to edit this part because we don't need a new event to consume events.

Thanks for noticing! 7980afc

MaferMazu · 2025-01-07T23:41:21Z

docs/how-tos/consume-an-event.rst

+- In the test suite, you can use the ``send_event`` method to trigger the event and pass the necessary data to the event receiver. In this case, we are passing the user, course and enrollment data to the event receiver as the triggering logic would do.
+- After triggering the event, you can assert that the event receiver executed the custom logic as expected. In this case, we are checking that the request was sent to the webhook with the correct data.
+
+You can review this example to understand how you can test the event receiver and ensure that the custom logic is executed when the event is triggered in the openedx-events-2-zapier plugin.


Suggested change

You can review this example to understand how you can test the event receiver and ensure that the custom logic is executed when the event is triggered in the openedx-events-2-zapier plugin.

You can review this example to understand how you can test the event receiver and ensure that the custom logic is executed when the event is triggered in the openedx-events-2-zapier_ plugin.

Fixed, thank you! bdccd4c

sarina

Looks good to me, made a couple comments, good to merge when you're satisfied.

sarina · 2025-01-09T00:46:37Z

docs/how-tos/consume-an-event.rst

+        pass
+
+- The Django dispatcher will call the ``send_enrollment_data_to_webhook`` function when the ``COURSE_ENROLLMENT_CREATED`` event is triggered by using the ``receiver`` decorator. In this case, that would be every time a user enrolls in a course.
+- Consider using asynchronous tasks to handle the event processing to avoid blocking the main thread and improve performance. Also, make sure to handle exceptions and errors gracefully to avoid silent failures and improve debugging. You should also consider not creating a tight coupling between receivers and other services, if doing so is necessary consider using the event bus to broadcast the event.


Suggested change

- Consider using asynchronous tasks to handle the event processing to avoid blocking the main thread and improve performance. Also, make sure to handle exceptions and errors gracefully to avoid silent failures and improve debugging. You should also consider not creating a tight coupling between receivers and other services, if doing so is necessary consider using the event bus to broadcast the event.

- Consider using asynchronous tasks to handle the event processing to avoid blocking the main thread and improve performance. Also, make sure to handle exceptions and errors gracefully to avoid silent failures and improve debugging. It is recommended to not create a tight coupling between receivers and other services. If doing so is necessary consider using the event bus to broadcast the event.

Small language tweak for easier reading

sarina · 2025-01-09T00:49:47Z

docs/how-tos/consume-an-event.rst

+            enrollment=enrollment_data
+        )
+
+        # Assert that the request was sent to the webhook with the correct data


Are you missing an assert statement here?

sarina · 2025-01-09T00:50:42Z

docs/how-tos/consume-an-event.rst

+
+These event receivers are usually implemented independently of the service in an `Open edX Django plugins`_ and are registered in the ``handlers.py`` (according to `OEP-49`_) file of the plugin. You can review the ``handlers.py`` file of the `openedx-events-2-zapier`_ plugin to understand how the event receivers are implemented and connected to the events.
+
+.. TODO: change receivers.py in openedx-events-2-zapier to handlers.py


should this be done before the PR merges?

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Dec 19, 2024

mariajgrimaldi added 2 commits December 19, 2024 17:58

docs: refactor names for consistency in how-tos

187f16e

docs: add docs about creating and consuming events

29c4c3a

mariajgrimaldi force-pushed the MJG/how-to-create-events branch from 13cbe55 to 29c4c3a Compare December 19, 2024 16:58

mariajgrimaldi added 2 commits December 20, 2024 10:39

docs: add assumptions for how-tos

f3e0d8e

docs: add more considerations to keep in mind

874f4f3

mariajgrimaldi marked this pull request as ready for review December 20, 2024 10:18

mariajgrimaldi requested a review from a team as a code owner December 20, 2024 10:18

mariajgrimaldi changed the title ~~Mjg/how to create events~~ docs: [FC-0074] add docs about creating and consuming events Dec 20, 2024

mariajgrimaldi added the FC Relates to an Axim Funded Contribution project label Dec 20, 2024

mariajgrimaldi added 2 commits December 20, 2024 12:45

docs: add consequences for ADR

8f3da1c

docs: add note about consumption

5809e22

mariajgrimaldi mentioned this pull request Dec 20, 2024

docs: [FC-0074] add ADR with event design suggestions #438

Open

15 tasks

mariajgrimaldi added 13 commits December 20, 2024 14:50

docs: add note about considering support over time for the service

9029d47

docs: move identify triggering logic to previous step

c8ec268

docs: use implement instead of write

297069f

docs: add note about data stability over time

28845d0

docs: split tests needed for the new event

f8d1497

docs: add note about triggering only when facts happen

e30b79f

docs: add independent step for consuming the event

d63020c

docs: add note about adding tests to the triggering logic

dad6fcc

docs: add an example of testing integration

b5d1cab

docs: add more details about example code

7e66121

fix: add plural for contribution process

287908a

docs: clarify identify triggering logic

8206324

docs: clarify where to place an event

6ad6bcf

mariajgrimaldi force-pushed the MJG/how-to-create-events branch from e092d3e to 6ad6bcf Compare December 25, 2024 15:35

mariajgrimaldi added 2 commits December 25, 2024 17:34

docs: add note about inspecting event content to implement custom logic

ae80dce

docs: use example from openedx-events-2-zapier plugin

992e7a2

mariajgrimaldi force-pushed the MJG/how-to-create-events branch from 9b5a636 to 992e7a2 Compare December 25, 2024 17:06

mariajgrimaldi added 8 commits December 25, 2024 18:54

docs: match description for new use case

4f259e6

docs: add notes about reviewing the event content for the use case

e540e29

docs: add note about django plugins

84c4639

docs: add note about OEP-49 handler patterns

13e3d5f

docs: add note about identify event to consume

d124da8

refactor: fix typing error

f3f8141

docs: add notes about implementing receivers

caba18f

docs: add suggestion about avoiding suffixes in data field names

5c22b93

mariajgrimaldi requested a review from sarina December 26, 2024 13:10

sarina reviewed Jan 6, 2025

View reviewed changes

refactor: address PR review

37e3ae4

mariajgrimaldi requested a review from sarina January 7, 2025 15:57

MaferMazu reviewed Jan 7, 2025

View reviewed changes

mariajgrimaldi added 2 commits January 8, 2025 15:22

docs: drop unnecessary assumption

7980afc

docs: add reference to openedx-events-2-zapier

bdccd4c

sarina approved these changes Jan 9, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: [FC-0074] add docs about creating and consuming events #439

docs: [FC-0074] add docs about creating and consuming events #439

mariajgrimaldi commented Dec 19, 2024 •

edited

Loading

openedx-webhooks commented Dec 19, 2024 •

edited

Loading

sarina Jan 6, 2025

mariajgrimaldi Jan 7, 2025

MaferMazu left a comment

MaferMazu Jan 7, 2025

mariajgrimaldi Jan 8, 2025

MaferMazu Jan 7, 2025

mariajgrimaldi Jan 8, 2025

sarina left a comment

sarina Jan 9, 2025

sarina Jan 9, 2025

sarina Jan 9, 2025

	You can review this example to understand how you can test the event receiver and ensure that the custom logic is executed when the event is triggered in the openedx-events-2-zapier plugin.
	You can review this example to understand how you can test the event receiver and ensure that the custom logic is executed when the event is triggered in the openedx-events-2-zapier_ plugin.


		These event receivers are usually implemented independently of the service in an `Open edX Django plugins`_ and are registered in the ``handlers.py`` (according to `OEP-49`_) file of the plugin. You can review the ``handlers.py`` file of the `openedx-events-2-zapier`_ plugin to understand how the event receivers are implemented and connected to the events.

		.. TODO: change receivers.py in openedx-events-2-zapier to handlers.py

docs: [FC-0074] add docs about creating and consuming events #439

Are you sure you want to change the base?

docs: [FC-0074] add docs about creating and consuming events #439

Conversation

mariajgrimaldi commented Dec 19, 2024 • edited Loading

Description

Supporting information

Testing instructions

Deadline

Other information

Checklists

openedx-webhooks commented Dec 19, 2024 • edited Loading

What's next?

🔘 Get product approval

🔘 Provide context

🔘 Get a green build

🔘 Let us know that your PR is ready for review:

Who will review my changes?

Where can I find more information?

When can I expect my changes to be merged?

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MaferMazu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sarina left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mariajgrimaldi commented Dec 19, 2024 •

edited

Loading

openedx-webhooks commented Dec 19, 2024 •

edited

Loading