Dynamic rules

From MoodleDocs
workplacelogo.png This feature is part of Moodle Workplace™, which is available through Moodle Partners.

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.

Moodle Workplace

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 - Overview.png

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.
Dynamic rules - reminder.png

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.

Dynamic rules - conditions.png

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
  • Cohort <cohort>
  • Added to cohort on or after this date and time <datetime>
No Cohort has to exist

Permission to view cohort

User is not member of cohort
  • Cohort <cohort>
Yes Cohort has to exist

Permission to view cohort

User has achieved competency
  • Select competency <competency>
No Competency has to exist

Permission to view competencies

Course completed
  • Course <course>
  • Completion date
    • Any time
    • After <datetime>
    • Before <datetime>
No 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.

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>
Yes Capability to view user details
User enrolled
  • Course <course>
  • Enrolment method <enrolment>
  • Enrolment start date and time is on or after <datetime>
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)
Yes Capability to view user details
User not enrolled
  • Course <course>
  • Enrolment method <enrolment>
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
  • Certification <certification>
  • Certified date on or after <datetime>
No Certifications have to exist

Permission to allocate users

Permission to edit certification

Certification expired
  • Certification <certification>
  • Expired date on or after <datetime>
Yes Certifications have to exist

Permission to allocate users

Permission to edit certification

Certification not certified
  • Certification <certification>
Yes Certifications have to exist

Permission to allocate users

Permission to edit certification

Certification overdue
  • Certification <certification>
  • Due date on or after <datetime>
Yes Certifications have to exist

Permission to allocate users

Permission to edit certification

Certification suspended
  • Certification <certification>
  • Suspended date on or after <datetime>
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 Certifications have to exist

Permission to allocate users

Permission to edit certification

Recertification period started
  • Certification <certification>
  • Recertification started on or after <datetime>
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>
Yes Certifications have to exist

Permission to allocate users

Permission to edit certification

Users not allocated to certification
  • Certification <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
  • Department <department>
  • Include subdepartments
  • Job start date is on or after <datetime>
No Departments have to exist

Permission to assign jobs

User is not in department
  • Department <department>
  • Include subdepartments
Yes Departments have to exist

Permission to assign jobs

User has position
  • Position <position>
  • Include subposition
  • Job start date is on or after <datetime>
No Positions have to exist

Permission to assign jobs

User doesn’t have position
  • Position <position>
  • Include subposition
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
  • Program <program>
  • Completion date on or after <datetime>
No Programs have to exist

Permission to allocate users

Permission to edit program

Program not completed
  • Program <program>
Yes Programs have to exist

Permission to allocate users

Permission to edit program

Program overdue
  • Program <program>
  • Due date on or after <datetime>
Yes Programs have to exist

Permission to allocate users

Permission to edit program

Program suspended
  • Program <program>
  • Suspended date on or after <datetime>
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>
Yes Programs have to exist

Permission to allocate users

Permission to edit program

Users not allocated to program
  • Program <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.

Dynamic rules - actions.png

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>
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
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 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.

Dynamic rules - notifications.png

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>
  • 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

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.

Dynamic rules - Errors.png

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).

Dynamic rules - reporting.png

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.