Skip to content

Latest commit

 

History

History
197 lines (138 loc) · 7.27 KB

events.rst

File metadata and controls

197 lines (138 loc) · 7.27 KB
Raw

Open edX Events

How to use

Using openedx-events in your code is very straight forward. We can consider the two possible cases, sending or receiving an event.

Receiving events

This is one of the most common use cases for plugins. The edx-platform will send 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.

Connecting signals can be done using regular django syntax:

from openedx_events.learning.signals import SESSION_LOGIN_COMPLETED

@receiver(SESSION_LOGIN_COMPLETED)
# your receiver function here

Or at the apps.py

"signals_config": {
    "lms.djangoapp": {
        "relative_path": "your_module_name",
        "receivers": [
            {
                "receiver_func_name": "your_receiver_function",
                "signal_path": "openedx_events.learning.signals.SESSION_LOGIN_COMPLETED",
            },
        ],
    }
},

In case you are listening to an event in the edx-platform repo, you can directly use the django syntax since the apps.py method will not be available without the plugin.

Sending events

Sending events requires you to import both the event definition as well as the attr data classes that encapsulate the event data.

from openedx_events.learning.data import UserData, UserPersonalData
from openedx_events.learning.signals import STUDENT_REGISTRATION_COMPLETED

STUDENT_REGISTRATION_COMPLETED.send_event(
    user=UserData(
        pii=UserPersonalData(
            username=user.username,
            email=user.email,
            name=user.profile.name,
        ),
        id=user.id,
        is_active=user.is_active,
    ),
)

You can do this both from the edx-platform code as well as from an openedx plugin.

Testing events

Testing your code in CI, specially for plugins is now possible without having to import the complete edx-platform as a dependency.

To test your functions you need to include the openedx-events library in your testing dependencies and make the signal connection in your test case.

from openedx_events.learning.signals import STUDENT_REGISTRATION_COMPLETED

def test_your_receiver(self):
    STUDENT_REGISTRATION_COMPLETED.connect(your_function)
    STUDENT_REGISTRATION_COMPLETED.send_event(
        user=UserData(
            pii=UserPersonalData(
                username='test_username',
                email='test_email@example.com',
                name='test_name',
            ),
            id=1,
            is_active=True,
        ),
    )

    # run your assertions

Changes in the openedx-events library that are not compatible with your code should break this kind of test in CI and let you know you need to upgrade your code.

Live example

For a complete and detailed example you can see the openedx-events-2-zapier plugin. This is a fully functional plugin that connects to STUDENT_REGISTRATION_COMPLETED and COURSE_ENROLLMENT_CREATED and sends the relevant information to zapier.com using a webhook.

Index of Events

This list contains the events currently being sent by edx-platform. The provided links target both the definition of the event in the openedx-events library as well as the trigger location in this same repository.

Learning Events

Name Type Date added
STUDENT_REGISTRATION_COMPLETED org.openedx.learning.student.registration.completed.v1 2022-06-14
SESSION_LOGIN_COMPLETED org.openedx.learning.auth.session.login.completed.v1 2022-06-14
COURSE_ENROLLMENT_CREATED org.openedx.learning.course.enrollment.created.v1 2022-06-14
COURSE_ENROLLMENT_CHANGED org.openedx.learning.course.enrollment.changed.v1 2022-06-14
COURSE_UNENROLLMENT_COMPLETED org.openedx.learning.course.unenrollment.completed.v1 2022-06-14
CERTIFICATE_CREATED org.openedx.learning.certificate.created.v1 2022-06-14
CERTIFICATE_CHANGED org.openedx.learning.certificate.changed.v1 2022-06-14
CERTIFICATE_REVOKED org.openedx.learning.certificate.revoked.v1 2022-06-14
COHORT_MEMBERSHIP_CHANGED org.openedx.learning.cohort_membership.changed.v1 2022-06-14
COURSE_DISCUSSIONS_CHANGED org.openedx.learning.discussions.configuration.changed.v1 2022-06-14

Content Authoring Events

Name Type Date added
COURSE_CATALOG_INFO_CHANGED org.openedx.content_authoring.course.catalog_info.changed.v1 2022-08-24