README.rst

EOX Hooks

This plugin extends and customizes the edx-platform by leveraging Open edX and Django events to trigger specific actions. Key features include:

• Post to Webhook URL: Sends data to a specified URL based on the eox-hooks settings.
• Get Extended Certificate Data: Adds comprehensive certificate information to the webhook request.
• Trigger Enrollments Creation: Initiates an asynchronous task to enroll users in a list of courses.
• Trigger Grades Assignment: Propagates grades to a specified course component.
• Create Enrollments for Program: Enroll users in a predefined list of courses constituting a Course Program.

Installation

1. Add this plugin in your Tutor config.yml with the OPENEDX_EXTRA_PIP_REQUIREMENTS setting.

   OPENEDX_EXTRA_PIP_REQUIREMENTS:
      - eox-hooks=={{version}}

2. Save the configuration with tutor config save.

3. Build the image and launch your platform with tutor local launch.

Usage

Before using eox-hooks, you need to set USE_EOX_HOOKS in True and configure EOX_HOOKS_DEFINITIONS in each tenant or site configuration that wants to use the plugin as follows:

USE_EOX_HOOKS: True
EOX_HOOKS_DEFINITIONS:
{
    "<trigger_event>":
    {
        "action": "<action_name>",
        "config":
        {
            "url": "https://webhook.site",
        },
        "fail_silently": False,
        "module": "<path_to_module>",
    },
}

Where:

• trigger_event: The name of the event the platform sends and eox-hooks listen, such as post_enrollment. For a detailed list, visit the trigger events examples file.
• action_name: Specify the name of the action to execute. For example: custom_action. To see the available actions in eox-hooks, visit the default hook actions file.
• config: Adds more information to the action.
• fail_silently: Defines what happens if an exception arises while executing the action. If False, then the exception is raised.
• path_to_module: Path to the module defining the action to execute. For example: eox_hooks.actions.

Example

EOX_HOOKS_DEFINITIONS:
{
    "post_register":
    {
        "action": "post_to_webhook_url",
        "config":
        {
            "fields": { "recipient_email": "user.pii.email" },
            "send_certificate_data": False,
            "url": "https://webhook.site",
        },
        "fail_silently": True,
        "module": "eox_hooks.actions",
    },
}

For more examples visit, the hooks settings example file.

Compatibility Notes

Open edX Release	Version
Juniper	<= 1.0
Koa	> 1.0
Lilac	> 1.0 < 2.0
Maple	>= 2.0 < 3.0
Nutmeg	>= 3.0
Olive	>= 4.0
Palm	>= 5.0
Quince	>= 6.0
Redwood	>= 6.3.0

The plugin is configured for the latest release (Quince). The following changes in the plugin settings should be applied to be used for previous releases. Those settings can be changed in eox_hooks/settings/common.py or, for example, in the instance configurations.

🚨 If the release you are looking for is not listed, please note:

• If the Open edX release is compatible with the current eox-hooks version (see Compatibility Notes), the default configuration is sufficient.
• If incompatible, you can refer to the README from the relevant version tag for configuration details (e.g., v5.1.0 README).

How to Contribute

Contributions are welcome! See our CONTRIBUTING file for more information – it also contains guidelines for how to maintain high code quality, which will make your contribution more likely to be accepted.

License

This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.