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.

Load video

YouTube

YouTube might collect personal data. Privacy Policy

ContinueDismiss

Moodle Workplace Dynamic Rules

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:

1. Add a new rule using the +New rule button
2. Specify the rules header
3. Add one or more rules conditions
4. Add one or more rules actions
5. 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.

If the Include suspended users option is enabled, the rule will evaluate the conditions also against users whose accounts have been suspended. Keep in mind that some actions may not apply fully to suspended users; for example, they will never receive notifications.

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.

Some conditions support the selection of multiple entities, most if which support the configuration of the Criteria when several entities have been selected:

• All criteria have been met: actions are triggered when all selected items are satisfied
• At least one criterion has been met: actions are triggered only once, that is when the second item is satisfied, actions will not be triggered again
• Every time the criterion has been met (coming soon): Equivalent of creating multiple rules, one for each item

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)	Multi-select	Scheduled	Prerequisites
User is member of cohort	Cohort <cohort> Added to cohort on or after this date and time <datetime>	No	No	Cohort has to exist Permission to view cohort
User is not member of cohort	Cohort <cohort>	No	Yes	Cohort has to exist Permission to view cohort
User has achieved competency	Select competency <competency>	No	No	Competency has to exist Permission to view competencies
Course completed	Course <course> Completion date Any time After <datetime> Before <datetime>	No	No	Course has to exist Permission to see at least one user
Course last accessed	Course <course> The user's last course access Ever Never Before <datetime> After <datetime> During the last <period> Prior to the last <period>	No	Yes	Course has to exist Permission to see at least one user
Course not completed	Course <course> This condition is applied to users regardless of their enrollment on the course.	No	Yes	Course has to exist Permission to see at least one user
Time since user was created	Creation date During the last <period> Prior to the last <period>	No	Yes	Capability to view user details
User enrolled	Course <course> Enrolment method <enrolment> Enrolment start date and time is on or after <datetime>	No	No	At least one course has to exist Permission to view participants in course
User last login	The user's last login was Not set (initial setting; cannot be selected) Prior to the last <period> During the last <period> Ever (user has logged on sometime in the past) Never (user has an account but has never logged in)	No	Yes	Capability to view user details
User not enrolled	Course <course> Enrolment method <enrolment>	No	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	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)	Multi-Select	Scheduled	Prerequisite
Certification certified	Certification <certifications> Criteria <criteria> Certified date on or after <datetime> Option to configure the execution of action-related recertifications Only execute actions when the user status changes from "not certified" to "certified" Always execute actions on all re-certifications	Yes	No	Certifications have to exist Permission to allocate users Permission to edit certification
Certification expired	Certification <certification> Expired date on or after <datetime>	No	Yes	Certifications have to exist Permission to allocate users Permission to edit certification
Certification not certified	Certification <certification>	No	Yes	Certifications have to exist Permission to allocate users Permission to edit certification
Certification overdue	Certification <certification> Due date on or after <datetime>	No	Yes	Certifications have to exist Permission to allocate users Permission to edit certification
Certification suspended	Certification <certification> Suspended date on or after <datetime>	No	Yes	Certifications have to exist Permission to allocate users Permission to edit certification
Recertification grace period ends	Certification <certification> Recertification grace period ends on or before <datetime>	No	No	Certifications have to exist Permission to allocate users Permission to edit certification
Recertification period started	Certification <certification> Recertification started on or after <datetime>	No	No	Certifications have to exist Permission to allocate users Permission to edit certification
Users allocated to certification	Certification <certification> Allocated date on or after <datetime>	No	Yes	Certifications have to exist Permission to allocate users Permission to edit certification
Users not allocated to certification	Certification <certification>	No	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)	Multi-Select	Scheduled	Prerequisite
User is in department	Department <departments> Include subdepartments Criteria <criteria> Job start date is on or after <datetime>	Yes	No	Departments have to exist Permission to assign jobs
User is not in department	Department <departments> Include subdepartments	Yes	Yes	Departments have to exist Permission to assign jobs
User has position	Position <positions> Include subposition Critiera <criteria> Job start date is on or after <datetime>	Yes	No	Positions have to exist Permission to assign jobs
User doesn’t have position	Position <positions> Include subposition	Yes	Yes	Positions have to exist Permission to assign jobs

Program

This category contains conditions based on program criteria.

Condition name	Setting(s)	Multi-Select	Scheduled	Prerequisite
Program completed	Program <programs> Criteria <criteria> Completion date on or after <datetime>	Yes	No	Programs have to exist Permission to allocate users Permission to edit program
Program not completed	Program <program>	No	Yes	Programs have to exist Permission to allocate users Permission to edit program
Program overdue	Program <program> Due date on or after <datetime>	No	Yes	Programs have to exist Permission to allocate users Permission to edit program
Program suspended	Program <program> Suspended date on or after <datetime>	No	Yes	Programs have to exist Permission to allocate users Permission to edit program
Users allocated to program	Program <program> Allocation date on or after <datetime>	No	Yes	Programs have to exist Permission to allocate users Permission to edit program
Users not allocated to program	Program <program>	No	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	Select badge <badge>	Badges have to exist Badge criteria has to be set to “Manual issue by role” Permission to issue badge
Issue certificate	Select certificate <certificate> Expiry date Select <datetime> After <period>	Certificates have to exist Permission to issue certificate
Add to cohort	Cohort <cohort>	Cohorts have to exist Permission to add users to cohort
Award competency	Select competency <competency> Suspended date on or after <datetime>	Competencies have to exist Permission to award competency
Notification	Subject: title of notification to be sent out Body: Message text in HTML, including images and notification placeholders Send to Matching users Department lead Manager Multi-language content is fully supported for notifications.	Permission to send messages
Users not allocated to program	Program <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 {{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	Course <course> Role <role>: the course role the users will be granted End date <datetime>: the Enrolment ends course setting will be set to the selected date; the Enrolment starts setting to the date of the execution of the rule Duration <period>: the Enrolment duration course setting will be set to the selection period; otherwise, it will be Unlimited. Group name: the name of the group the users will be added to. Note that the group has to exist; otherwise, this setting will be ignored. 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	Course <course> Enrolment method <method> Action Disable enrolment: The user's access to the course is disabled, but the course role isn't removed. This is equivalent to suspending the user's enrollment; it still appears in the grade book and completion report, the user just can't access the course anymore. Disable enrolment and remove roles: This is the same as the previous step, plus the user's course role is removed. That way, access to the course is suspended, and its appearance in the completion report is hidden, but the user is still enrolled in the course. Unenrol user from course: The user is no longer enrolled in the course, and all records, such as the progress report, have been removed	Courses have to exist

Multi-language support in notifications

Both, the Subject and the Body fields support multi-language content. The Multi-language content filter has to be enabled and configured to allow notifications in multiple languages. Once activated, the Multi-language content filter supports the <span lang="xx"class="multilang"> tag, where xx represents the language pack code, for example, en for English or de for German.

Notifications will be sent in the recipient's language. Thus, if a German speaking manager has an Italian speaking team member, the manager will receive the message in German while the team member will receive the message in Italian. Using multi-lingual notifications can also cater for cultural idiosyncrasies such as calling staff in by first name in some countries and by surname in others.

Multi-language support in notifications also works with the Multilang2 plugin which some institutions might prefer over the built-in multi-language content filter.

Certifications

This category contains two certification-related actions.

Action name	Setting(s)	Prerequisite
Allocate users to certifications	Certification <certification> Start date Keep certification defaults Select date <datetime>	Certifications have to exist
Deallocate users from certifications	Certification <certification> 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	Department <department> Position <position> Start date Date of rule execution Date of user creation Select date <date> End date None Relative to start date <period> Select date <date>	Departments and positions have to exist

Program

This category contains two program-related actions.

Action name	Setting(s)	Prerequisite
Allocate users to programs	Program <program> Start date Keep program defaults Select date <datetime>	Programs have to exist
Deallocate users from programs	Program <program> 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	Tenant <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).

Cross-tenant Dynamic Rules

Automations can be configured in the Shared Space. You can create conditions and actions using Programs, Certifications, and Organisation structures that are defined in Shared space, as well as courses, cohorts, and certificates that are shared, that is they do not belong to any tenant's category. When creating a rule in the Shared Space, only relevant conditions and actions are available. The usage of non-shared entities will be added in the future versions.

Cross-tenant rules are created in the Shared Space, like any other shared entity. Shared rules will be shown in the Dynamic Rules interface in all tenants, with a Shared Space badge. These rules can be only edited, enabled, disabled, or archived in Shared Space.

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.