Home
This plugin provides a flexible system for Moodle administrators to set up external actions (such as an HTTP request or an email), in response to specified Moodle events.
To schedule an external action in response to Moodle event, you create a workflow. Each workflow is set to run in response a specified trigger event type (e.g. "Course Created", "User Logged in", etc.).
The plugin then uses the Moodle Events API to listen for events of that type.
When one occurs, the plugin adds a copy of the workflow and the event to its queue, and runs the workflow on the next cron execution.
Workflows consist of a series of steps, which are executed in order.
There are three types of steps:
-
Lookups are steps which add data to the workflow task. For example, most events contain the userid of the user involved, but not their full data such as name, email, etc. The "user lookup" step reads the "userid" field of the event, looks up the user in the database, and adds the user's data to the workflow, for subsequent steps to make use of.
-
Filters are steps that can inspect the workflow's data and halt the further execution of the workflow task if some condition is not met. For example, you may only want to carry out the workflow's actions when a specific user logs in, so you could use a filter step to check for that user's username, and to halt the workflow for any other user.
-
Actions are steps that have some external effect, such as sending an email or making an HTTP POST request. These should typically be the last step in a workflow.
Steps communicate data to each other through datafields, which are a combination of the data from the initial event, and data added by lookup steps.
The currently available datafields are displayed in the step form under the description field for that step.
Fields are split up by the event or step that provides them. The fields available from the event associated with the workflow ar always listed first. Then the fields that each previous step provides are listed.
Datafields serve two purposes:
-
They provide a way for a workflow author to specify a particular piece of data to use in a step. For example, in the user lookup step, the workflow author must specify which field to get the user ID from. This might be "userid", "relateduserid", "other_teacherid", etc.
-
An action step's configuration may include
{placeholders}, to put the values of datafields into an outgoing message. For example, an HTTP POST action may need the target URL to vary like so:http://example.org/api?username={user_username}. Or an email action may want to include details like{user_fullname} logged into {course_shortname}..
Datafields come from these sources:
-
The event's "other" field, if it has one. These elements will have their name prefixed with "other", e.g. "other_courseshortname"
-
Data added by lookup steps. A lookup step will usually allow the workflow author to specify a prefix for the added data fields. For example, the user lookup step defaults to the prefix "user_", and will add fields such as "user_firstname", "user_lastname", "user_email", etc.
Note: (Because the events are serialized into a table and then restored at the next cron run, the workflow does not have access to non-serialized event data, such as record snapshots. However, this data can usually be added by a lookup step.)
The plugin allows for existing workflows to be exported as files. This allows existing workflows to be backed up and/or shared between Moodle installations. To export a worklfow click the download workflow icon for the workflow you wish to export from the workflow overview page.
Workflows can also be imported. On the workflow overview page, click the Import a workflow button, to import a workflow from a file.
Note: Imported workflows default to being disabled. They will need to be enabled before they will trigger on event actions. This is to allow review of imported workflows.
Several sample workflows ship with this plugin. These samples can be imported via the plugin workflow functionality. They give examples of how to configure workflows to perfrom various actions.
Note: Some of the sample workflows may need configuration changes to work with your particular Moodle setup.
The next section lists the available sample workflows.
The following sample workflows are available:
-
Course Completed
- This workflow sends an email to a student when they have successfully completed a course. The workflow will also send the completion details to an external system via HTTP Post.
-
Login Failure Logging
- This workflow sends details of failed login attempts to an external system via HTTP Post.
-
User enrolment
- This workflow will send an email to a user when they have been enrolled in a course. The email includes some basic information about the course.
If you wish to submit a sample workflow please raise a GitHub tracker issue here: https://github.com/catalyst/moodle-tool_trigger/issues
The Tool Trigger plugin, attempts to show the fields made available for each Moodle Event in the step form, when a step is added or updated. Unfortunately, there is no programatic way to know the fields each Event makes available.
This plugin loads the known fields for Moodle Events into the Moodle databse on install and upgrade. However, your Moodle installation may have Events that are not included in the known list that this plugin uses. In that case the available Event fields will not be displayed in the step form.
To allow the plugin to display datafields for unknown Events, learning mode has been added. Learning mode captures the fields that events produce when they are triggered. These learnt events will then be used to display datafields in the workflow step fields.
Learnt event fields can also be exported to a JSON file via a CLI script, so that they can then be contributed back to the project.
See below on how to configure learning mode.
This plugin relies on a scheduled task to process events. You must have cron running on your site - Moodle recommends that cron is run every minute - see: https://docs.moodle.org/en/Cron
If using Moodle 3.3 and higher you can trigger tasks manually, as an admin go to Site administration > Server > Scheduled tasks and you will see 2 tasks for the tool_trigger plugin.
- \tool_trigger\task\cleanup - this is responsible for deleting information about processed events (configurable by the admin - set to 24 hours by default.) - by default this task is set to run daily.
- \tool_trigger\task\process_workflows - this task is responsible for checking to see if any events are in the queue for processing. This is set to run every minute (as long as your overall cron process runs at least every minute).
For detailed instructions on how to setup up a workflow please see the following section:
Creating a new workflow