Dynamic rules
This feature is part of Moodle Workplace™, which is available through Moodle Partners only.Overview
Dynamic rules allow you to define and execute centralized and automated rules using an "if this then that" conditional approach to trigger actions when certain conditions are met. Each Workplace plug-in implements its own conditions and actions to be used in any dynamic rule. Other Workplace features use dynamic rules to automate some of their actions, like issuing badges or certificates or granting competencies.
A rule comprises a rule header and a rule body. The rule header contains information about the rule, while the rule body contains two parts: conditions and actions. The basic statement that is applied to every active user in the tenant that the dynamic rule belongs to is as follows:
IF <Conditions> = TRUE THEN execute <Actions>
Each <Conditions> clause comprises a single condition or multiple conditions, where all conditions are connected via AND operators; that is, all conditions must be met for <Conditions> to be true. <Actions> is a series of actions to be executed on all users that <Conditions> applies to. The same actions and conditions can be used multiple times in a rule. In the context of Workplace, both conditions and actions are always applied to users. Conditions are matched against all tenant users, whereas actions are applied to a subset of all users, namely those that satisfy the conditions.
Dynamic rules always belong to a tenant. It is not possible to share dynamic rules across tenants yet.
Creating Dynamic Rules
You can access the management of dynamic rules via Site administration > Dynamic rules or directly via the Dynamic rules icon in the Workplace launcher.
The process to create a new dynamic rule is as follows:
- Add a new rule using the +New rule button
- Specify the rules header
- Add one or more rules conditions
- Add one or more rules actions
- Enable rule
Rules Header
The rules header acts as a descriptive wrapper that is applied to all elements of the rule body and contains two options:
- Name: this doesn't have to be unique, but it is recommended to give each rule a unique and meaningful label.
- Rule action limits: this option defines the maximum number of times the actions should apply. As soon as users match the rule conditions, the actions will be applied. These actions will not apply again if users continue to match the conditions. However, if a user stops matching and then matches again, the actions may be applied again. This setting defines the maximum number of times actions should (re-)apply.
Once the Rule action limits setting has been enabled, there are two options to limit the number of times the matching process is performed:
- Can't be applied more than X times ever
- Can't be applied more than X times per Y minutes/hours/days/weeks/seconds
The Rule action limits feature allows you to control how often an action of a rule can be triggered:
- No rule action limits is the default and should be used when you cannot predict when conditions are met and when immediate actions are expected. An example is the successful completion of a course, which triggers the award of a competency or a badge.
- The ever matching mode is preferred when you know that a condition will only be met a certain number of times. An example is the one-off issuing of a certificate to all users who completed an already archived course after migrating historical data.
- The per matching mode is useful if a delay in executing the action part of the rule is acceptable. For instance, notifying the manager after a team member has attended a face-to-face seminar does not have to take place instantaneously and is usually sufficient once a day.
Rules Conditions
Conditions represent the IF part of a dynamic rule. On the Conditions tab, you will find a listing of predefined conditions for each entity that can be evaluated to trigger actions. Each condition has its editable properties; for example, using the drop-down menu lets you select a course that has to be completed, as well as the completion date and time parameters.
Only those conditions that the current user has the capability to add are listed. Some conditions may be listed but not available, which is the case if no entities associated with the condition exist in the system; for instance, the "Course completed" condition can only be added if there is at least one course the user (dynamic rule creator or editor) has rights to see users within. Once the conditions part has been appropriately configured, click on Save Changes. You can always return later and change the settings of your own rules using the Edit condition or Delete condition icons. If users have previously matched rule conditions, the conditions part becomes read-only. Actions can be edited at any point.
Modification or removal of conditions and actions from other users requires appropriate editing capabilities. For example, if one user adds the condition "User enrolled" and another user does not have access to this particular course, the condition will be read-only, indicated by the lock symbol. If a rule is invalid and processing is not possible, the broken condition or action can be modified or deleted without the required permissions.
At the bottom of the tab, you can check how many users would meet these conditions. By clicking on the View matching users link, you can view the complete user listing.
Most dynamic rule conditions are event-based, which means that when a particular requirement is matched (for example, “Course completed”), the event will trigger the rule. However, some conditions are not activated by events but run as a scheduled task. For example, if you want to perform an action upon users who did not complete a course, the condition "Course not completed" will instead scan the courses periodically (on cron run), looking for users that match this condition. If the system finds one or more users that match this condition, the rule will be triggered.
General conditions
This category contains conditions based on cohort membership, course completion and enrolment, and user-related criteria.
| Condition name | Setting(s) | Scheduled | Prerequisites |
| User is member of cohort |
|
No | Cohort has to exist
Permission to view cohort |
| User is not member of cohort |
|
Yes | Cohort has to exist
Permission to view cohort |
| User has achieved competency |
|
No | Competency has to exist
Permission to view competencies |
| Course completed |
|
No | Course has to exist
Permission to see at least one user |
| Course not completed |
This condition is applied to users regardless of their enrollment on the course. |
Yes | Course has to exist
Permission to see at least one user |
| Time since user was created |
|
Yes | Capability to view user details |
| User enrolled |
|
No | At least one course has to exist Permission to view participants in course |
| User last login |
|
Yes | Capability to view user details |
| User not enrolled |
|
Yes | At least one course has to exist
Permission to view participants in course |
| User profile field | Profile field with type-specific matching operations. Custom profile fields are fully supported. | No | Capability to view user details
For custom fields, the visibility status has to be set to "All" |
Certifications
This category contains conditions based on certification-related criteria.
| Condition name | Setting(s) | Scheduled | Prerequisite |
| Certification certified |
|
No | Certifications have to exist
Permission to allocate users Permission to edit certification |
| Certification expired |
|
Yes | Certifications have to exist
Permission to allocate users Permission to edit certification |
| Certification not certified |
|
Yes | Certifications have to exist
Permission to allocate users Permission to edit certification |
| Certification overdue |
|
Yes | Certifications have to exist
Permission to allocate users Permission to edit certification |
| Certification suspended |
|
Yes | Certifications have to exist
Permission to allocate users Permission to edit certification |
| Recertification grace period ends |
|
No | Certifications have to exist
Permission to allocate users Permission to edit certification |
| Recertification period started |
|
No | Certifications have to exist
Permission to allocate users Permission to edit certification |
| Users allocated to certification |
|
Yes | Certifications have to exist
Permission to allocate users Permission to edit certification |
| Users not allocated to certification |
|
Yes | Certifications have to exist
Permission to allocate users Permission to edit certification |
Organisation structure
This category contains conditions dealing with jobs, departments and positions.
| Condition name | Setting(s) | Scheduled | Prerequisite |
| User is in department |
|
No | Departments have to exist
Permission to assign jobs |
| User is not in department |
|
Yes | Departments have to exist
Permission to assign jobs |
| User has position |
|
No | Positions have to exist
Permission to assign jobs |
| User doesn’t have position |
|
Yes | Positions have to exist
Permission to assign jobs |
Program
This category contains conditions based on program criteria.
| Condition name | Setting(s) | Scheduled | Prerequisite |
| Program completed |
|
No | Programs have to exist
Permission to allocate users Permission to edit program |
| Program not completed |
|
Yes | Programs have to exist
Permission to allocate users Permission to edit program |
| Program overdue |
|
Yes | Programs have to exist
Permission to allocate users Permission to edit program |
| Program suspended |
|
Yes | Programs have to exist
Permission to allocate users Permission to edit program |
| Users allocated to program |
|
Yes | Programs have to exist
Permission to allocate users Permission to edit program |
| Users not allocated to program |
|
Yes | Programs have to exist
Permission to allocate users Permission to edit program |
Rules Actions
Conditions represent the THEN part of a dynamic rule. In the Actions tab, you will find a list of actions that will be executed once the previously defined conditions have been met. You have to pick an element from the list of actions and configure its properties to add actions.
Only those actions that the current user has the capability to add are listed. Some actions may be listed but not available, which is the case if no entities associated with the actions exist in the system; for instance, the "Add to cohort" action can only be added if there is at least one cohort the user has rights to see users within.
General actions
This category contains general actions not belonging to any particular category.
| Action name | Setting(s) | Prerequisite |
| Award badge |
|
Badges have to exist
Badge criteria has to be set to “Manual issue by role” Permission to issue badge |
| Issue certificate |
|
Certificates have to exist
Permission to issue certificate |
| Add to cohort |
|
Cohorts have to exist
Permission to add users to cohort |
| Award competency |
|
Competencies have to exist
Permission to award competency |
| Notification |
|
Permission to send messages |
| Users not allocated to program |
|
Programs have to exist |
Notification placeholders
A range of placeholders can be used in the notification body; these placeholders will then be replaced with the appropriate values when the message is sent. All placeholders are enclosed in double curly brackets, for example Template:userfullname. The placeholders available in the message's body change depending on the conditions that have been selected. To see the list of available placeholders, you need to expand the Available placeholders list.
The table shows all the message placeholders, grouped by condition category (including prerequisites):
| Condition category (Prerequisite) | Notification Placeholder | Description |
|
Users (always available) |
{{userfirstname}} | First name |
| {{userfullname}} | Full name | |
|
Site (always available) |
{{sitefullname}} | Full site name |
| {{siteshortname}} | Site short name | |
| {{sitelink}} | Site link | |
|
Courses (Course completed, Course not completed) |
{{courseid}} | Internal course ID used in URLs |
| {{coursefullname}} | Course full name | |
| {{courseshortname}} | Course short name | |
| {{courseurl}} | Course URL | |
| {{coursecompletiondate}} | Course completion date | |
| {{coursegrade}} | Course grade | |
| {{coursecustomfield_<name>}} | Course custom field | |
|
Programs and Certifications (any programs or certifications condition) |
{{programid}} | Internal program ID used in URLs |
| {{programname}} | Program name | |
| {{programcompletedcourses}} | Courses completed in program | |
| {{programcompletiondate}} | Program completion date | |
|
Certifications (any certifications condition) |
{{certificationid}} | Internal certification ID used in URLs |
| {{certificationname}} | Certification name | |
| {{certificationdate}} | Certification date | |
| {{certificationexpirydate}} | Certification expiry date | |
| {{expirydatetimestamp}} | Certification expiry date timestamp | |
| {{certificationreopen}} | Recertification start date | |
| {{certificationprogramname}} | Initial program name for this certification | |
| {{recertificationprogramname}} | Recertification program name | |
| {{certificationgraceperiodend}} | Grace period end date |
Courses
This category contains two course-related actions.
| Action name | Setting(s) | Prerequisite |
| Enrol users into a course |
Note: The enrolment will be activated immediately after the action has been executed. Note: The Dynamic rules enrolment method must be enabled in the site administration for automatic course enrolment to function. |
Courses have to exist |
| Unenrol users from a course |
|
Courses have to exist |
Certifications
This category contains two certification-related actions.
| Action name | Setting(s) | Prerequisite |
| Allocate users to certifications |
|
Certifications have to exist |
| Deallocate users from certifications |
Note: Users can only be unallocated if another dynamic rule allocated them. Users who were allocated manually will not be affected. |
Certifications have to exist |
Organisation structure
This category contains a single action to assign users to a job.
| Action name | Setting(s) | Prerequisite |
| Assign job |
|
Departments and positions have to exist |
Program
This category contains two program-related actions.
| Action name | Setting(s) | Prerequisite |
| Allocate users to programs |
|
Programs have to exist |
| Deallocate users from programs |
Note: Users can only be unallocated if another dynamic rule allocated them. Users who were allocated manually will not be affected. |
Programs have to exist |
Multi-tenancy
This category contains a single action to assign users to a tenant.
| Action name | Setting(s) | Prerequisite |
| Allocate users to tenant |
|
Rules Enabling and Processing
A dynamic rule has to be enabled before it becomes active. A rule requires at least one condition and one action to be enabled. Prior to processing a rule, each condition and action is validated for correctness. If at some future point a rule fails validation (for example, a course or program no longer exists), it will be disabled automatically and will be flagged as containing an error. To re-enable such a rule, you must edit it and correct each erroneous condition and action.
A user can edit a rule only if they have permission to edit all conditions and actions in the rule. If any condition or action contains errors, the user can edit the rule only if they have permission to edit all other conditions and actions and add the condition or action containing an error. For any event-based conditions (i.e. those that depend on an action taking place, such as enrolling a user on a course), any matching conditions are evaluated immediately. The corresponding rule will be executed for the user affected by the event condition (i.e. the user enrolled on a course). All rules that contain non-event-based conditions (scheduled tasks) will be executed during each cron run. Rules, where all conditions are event-based, are excluded from cron processing, but they are processed as ad-hoc cron tasks only once when enabled (so that it is applied to users who matched conditions at the point of enabling the rule).
Rules archiving and deletion
The archiving of a dynamic rule takes place via the standard Archive icon beside the rule. Archived dynamic rules are still available for current and future reports, which might be required in an auditing scenario or when an error has occurred.
Archived rules are preserved for future reference and can be unarchived via the standard Restore icon. It can further be removed permanently using the standard Delete icon.
Rules reporting
Moodle Workplace keeps an internal log, protocolling all rule executions. You can view the log of a rule via the standard Report icon. The following information is displayed for every user that matches the condition: Full name, Email address, Matched time, and the Status (Completed, In Progress or Failed).
Limiting the number of rules
A site administrator can restrict the number of dynamic rules that can be created per site and/or tenant by adding the following setting(s) to the site configuration file. Note, archived rules are counted towards the limit; however, rules created automatically by other plugins (for example, programs and certifications) are not counted towards the limit:
$CFG->tool_dynamicrule_limitsenabled = true;
$CFG->tool_dynamicrule_sitelimit = <VALUE>;
$CFG->tool_dynamicrule_tenantlimit = <VALUE>;
Omitting this configuration, or setting tool_dynamicrule_limitsenabled value to false, indicates that no limit should be applied to the number of dynamic rules that can be created (default). Note that the tenant limit cannot exceed the site limit. Setting limit values to 0 will effectively disable rules creation.
