Difference between revisions of "Dynamic rules"

Jump to: navigation, search
(Limiting number of dynamic rules: Added new config param)
(Changes associated with capabilities feature added.)
Line 9: Line 9:
 
Dynamic rules can be accessed from the Workplace launcher.
 
Dynamic rules can be accessed from the Workplace launcher.
  
We can create a new rule by clicking the "New rule" button and giving the rule a name. We tick the “enable matching frequency limitation” option to limit how many times this rule will be triggered in a certain period. For example, let's say that this rule cannot be triggered more than once in one hour.
+
We can create a new rule by clicking the "New rule" button and giving the rule a name.
 +
 
 +
“Rule action limits” option defines the maximum number of times actions should apply. As soon as users match the rule [[#conditions]], the [[#actions]] will be applied to them. 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.
  
 
== Limiting number of dynamic rules ==
 
== Limiting number of dynamic rules ==
Line 23: Line 25:
  
 
= Conditions =
 
= Conditions =
On the conditions tab we'll find a listing of predefined conditions for each entity that can be evaluated in order to trigger some actions. Each condition has its own editable properties. For example, using the drop down menus let’s select users from the Department “Europe” and who have completed the onboarding program. Once they're configured properly we click on “Save Changes”.  
+
On the conditions tab we'll find a listing of predefined conditions for each entity that can be evaluated in order to trigger some actions. Only conditions that current user has capability to add are listed. Some conditions may be listed, but not available if there are no entities associated with it exist in the system (e.g. "Course completed" condition can only be added if there is at least one course that user has rights to see users within). Each condition has its own editable properties. Once they're configured properly we click on “Save Changes”.  
  
We can always come back later and change or delete these settings using the "Edit condition" icon.
+
We can always come back later and change these settings using the "Edit condition" icon or delete condition.
  
 
At the bottom of the tab, we can check how many users would meet these conditions, and by clicking on “view matching users” we can easily check the complete user listing.
 
At the bottom of the tab, we can check how many users would meet these conditions, and by clicking on “view matching users” we can easily check the complete user listing.
  
 
= Actions =
 
= Actions =
Now let's switch to the actions tab, to define what we want to happen when the conditions are met. In this example, we want to allocate the users to a certification so we click on "Allocate users to certification" and select the appropriate certification.
+
On the actions tab we'll find a listing of actions that allow to define what we want to happen when the conditions are met. For example, if we want to allocate the users to a certification so we click on "Allocate users to certification" and select the appropriate certification.
 +
 
 +
Only actions that current user has capability to add are listed. Some actions may be listed, but not available if there are no entities associated with it exist in the system (e.g. "Add to cohort" action can only be added if there is at least one cohort that user has rights to see users within).
  
 
= Activating a rule =
 
= Activating a rule =
 
Now that the rule contains at least one condition and one action, we can activate it by clicking the Enable button. Prior to enabling we will be shown a notification to remind us of how many users will be affected by the rule. We click “enable” and the rule will be executed as an adhoc task during the next [[Cron|cron]] run.
 
Now that the rule contains at least one condition and one action, we can activate it by clicking the Enable button. Prior to enabling we will be shown a notification to remind us of how many users will be affected by the rule. We click “enable” and the rule will be executed as an adhoc task during the next [[Cron|cron]] run.
 +
 +
User is able to activate rule only if she has permission to edit all conditions and actions in the rule.
 +
 +
= Editing a rule =
 +
User can edit a rule only if she has permission to edit all conditions and actions in the rule. If any condition or action contains errors, user can edit the rule only if she has permissions to edit all other conditions and actions and has adding capability for the condition or action entitiy containing an error.
 +
 +
If some users matched the rule already, rule consitions become read-only. Actions can be editited at any point.
  
 
= Rule processing =
 
= Rule processing =
  
Note that prior to processing a rule, each condition and action is validated for correctness. If at some future point a rule fails validation (for example because a course no longer exists) it will be disabled automatically and will be flagged as containing an error. Validation occurs each time a rule is processed. To re-enable such a rule, we must edit it and correct each condition and action.
+
Note that prior to processing a rule, each condition and action is validated for correctness. If at some future point a rule fails validation (for example because a course no longer exists) it will be disabled automatically and will be flagged as containing an error. To re-enable such a rule, we must edit it and correct each condition and action.
 +
 
 +
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 who was affected by the event condition (i.e. the user who was enrolled on a course). All rules that contain non event-based conditions will be executed during each cron run. Rules where all conditions are event-based are excluded from cron processing, but they are processed as cron ad-hoc task only once when enabled (so that it is applied to users who matched conditions at the point of enabling the rule).
 +
 
 +
= Duplicating the rule =
  
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 who was affected by the event condition (i.e. the user who was enrolled on a course). All rules that contain non event-based conditions will be executed during each cron run.
+
Duplicating the rule allows to create a copy of the rule with identical conditions and actions, so it can be modified according to requirements. User is able to duplicate rule only if she has permission to edit all conditions and actions in the rule.
  
 
= Active/archived rules =
 
= Active/archived rules =
 
The Active rules tab lists all rules that are currently active on your site. We can toggle whether an individual rule is enabled or not by using the Enable/Disable rule toggle in the rules table.
 
The Active rules tab lists all rules that are currently active on your site. We can toggle whether an individual rule is enabled or not by using the Enable/Disable rule toggle in the rules table.
  
Pressing the Archive rule button will disable that rule and move it to the Archived tab, allowing it to be preserved for reference in the future. Archived rules cannot be enabled again until they are moved back to the Active tab.
+
Pressing the Archive rule button will disable that rule and move it to the Archived tab, allowing it to be preserved for reference in the future. Archived rules cannot be enabled again until they are moved back to the Active tab. User is able to archive rule only if she has permission to edit all conditions and actions in the rule.

Revision as of 10:19, 1 July 2020

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


Overview

The dynamic rules feature allows you to create “if this then that” rules based on one or more conditions to execute the selected actions. Each plug-in implements its own conditions and actions to be used in any dynamic rule. Other Workplace features make use of dynamic rules to automate some of their actions, like issuing badges or certificates, or granting competencies.

Moodle Workplace

Creating dynamic rules

Dynamic rules can be accessed from the Workplace launcher.

We can create a new rule by clicking the "New rule" button and giving the rule a name.

“Rule action limits” option defines the maximum number of times actions should apply. As soon as users match the rule #conditions, the #actions will be applied to them. 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.

Limiting number of dynamic rules

A site administrator can restrict the number of dynamic rules that can be created per site/tenant by adding the following line(s) to the site configuration (note that archived rules are also counted towards the limit, and rules created automatically by other plugins 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. Note that a tenant limit cannot exceed a site limit. Setting values to 0 will effectively disable rules creation.

Conditions

On the conditions tab we'll find a listing of predefined conditions for each entity that can be evaluated in order to trigger some actions. Only conditions that current user has capability to add are listed. Some conditions may be listed, but not available if there are no entities associated with it exist in the system (e.g. "Course completed" condition can only be added if there is at least one course that user has rights to see users within). Each condition has its own editable properties. Once they're configured properly we click on “Save Changes”.

We can always come back later and change these settings using the "Edit condition" icon or delete condition.

At the bottom of the tab, we can check how many users would meet these conditions, and by clicking on “view matching users” we can easily check the complete user listing.

Actions

On the actions tab we'll find a listing of actions that allow to define what we want to happen when the conditions are met. For example, if we want to allocate the users to a certification so we click on "Allocate users to certification" and select the appropriate certification.

Only actions that current user has capability to add are listed. Some actions may be listed, but not available if there are no entities associated with it exist in the system (e.g. "Add to cohort" action can only be added if there is at least one cohort that user has rights to see users within).

Activating a rule

Now that the rule contains at least one condition and one action, we can activate it by clicking the Enable button. Prior to enabling we will be shown a notification to remind us of how many users will be affected by the rule. We click “enable” and the rule will be executed as an adhoc task during the next cron run.

User is able to activate rule only if she has permission to edit all conditions and actions in the rule.

Editing a rule

User can edit a rule only if she has permission to edit all conditions and actions in the rule. If any condition or action contains errors, user can edit the rule only if she has permissions to edit all other conditions and actions and has adding capability for the condition or action entitiy containing an error.

If some users matched the rule already, rule consitions become read-only. Actions can be editited at any point.

Rule processing

Note that prior to processing a rule, each condition and action is validated for correctness. If at some future point a rule fails validation (for example because a course no longer exists) it will be disabled automatically and will be flagged as containing an error. To re-enable such a rule, we must edit it and correct each condition and action.

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 who was affected by the event condition (i.e. the user who was enrolled on a course). All rules that contain non event-based conditions will be executed during each cron run. Rules where all conditions are event-based are excluded from cron processing, but they are processed as cron ad-hoc task only once when enabled (so that it is applied to users who matched conditions at the point of enabling the rule).

Duplicating the rule

Duplicating the rule allows to create a copy of the rule with identical conditions and actions, so it can be modified according to requirements. User is able to duplicate rule only if she has permission to edit all conditions and actions in the rule.

Active/archived rules

The Active rules tab lists all rules that are currently active on your site. We can toggle whether an individual rule is enabled or not by using the Enable/Disable rule toggle in the rules table.

Pressing the Archive rule button will disable that rule and move it to the Archived tab, allowing it to be preserved for reference in the future. Archived rules cannot be enabled again until they are moved back to the Active tab. User is able to archive rule only if she has permission to edit all conditions and actions in the rule.