Rules
In order to understand rules more easily, please become familiar with the concept of tasks.
Rules incorporate and extend the structure of single instantly launched tasks by adding automation to the execution logic via a complex element called trigger, and enriching the available execution options. The trigger enables the automatic execution of a management task upon the occurrence of certain events and conditions. Thus, rules not only automate the mass device management process, but provide a number of ways in which this automation can be tailored to the needs of the use case.
Rule elements
The main elements of a rule are its trigger plus the elements which are also present in tasks - action, scope and execution options. Each element is described in more detail below.
Trigger
Triggers serve the first few stages in the rule evaluation process, which result in the launching of one or several tasks within the rule.
One rule may have multiple triggers, and each trigger is a pair of an event and a condition (optional). There may also be one general condition on rule level, which applies to all triggers.
The occurrence of such an event automatically starts the rule evaluation process, whereas the condition serves as a barrier for whether this should lead to the launching of a task, i.e. to the actual execution of an action on the managed devices.
If we have to outline the rule's process flow (see the figure above), it would include the following steps:
Fire rule. When one of the events specified in a rule's trigger occurs, the rule as a whole is fired but the execution of its action doesn't start just yet. Considering that a rule may have multiple triggers, it may be fired by each of them.
Evaluate condition. Then the Mass Management Engine evaluates the condition corresponding to this event (if any) and the general condition of the rule (if any) and checks whether they are satisfied. If these conditions are evaluated to true and the event relates to the scope, the rule is triggered.
Each time the rule is triggered, this automatically leads to the launching of a task which executes the action of the rule.
A rule can be triggered multiple times - as many times as an event, defined in its triggers occurs and the corresponding condition is satisfied.
One triggering of the rule leads to the launching of one task. Within the task - just as already described in the Tasks section - the action script is executed multiple times - once per device in the scope or once in the system outside the context of a particular device.
The event, whose purpose is to fire the rule, consists of a type and data, for example:
eventType:"FeaturesEvents/com.acme:Thermostat:1.0.0/PropertyChanged/Status/currentTemperature", eventData: {deviceId=..., featureId=..., propertyId=..., value=...}The condition, which determines whether the firing of the rule will lead to the execution of an action on the managed devices, may be defined as:
an RQL filter matched against the event data
a Groovy script that will be evaluated to true or false
The general condition, which is applicable to the whole rule, can be defined in the same format - as an RQL filter or a Groovy condition script. The general condition is applicable for all cases of rule triggering, i.e. it is evaluated when any of the events defined in some of the triggers occurs.
The system provides three built-in trigger event types, namely manual, Cron and device event triggers. Check their individual pages for more details.
Action
The action of a rule is a Groovy script, which defines the effect which will be produced on the managed devices upon execution of the rule and the included tasks. For more details, refer to Tasks.
One rule can have only one action script, therefore all tasks originating from the same rule will execute the same action script.
Scope
The scope element of rules is the same as the one described for tasks. As a brief reminder, the two alternatives to choose from are device scope for management actions on devices, and system scope for management actions executed outside the context of a particular device. There are several ways to define device scope, described in Tasks.
When the rule is triggered by a device-related event, then the task is launched in the scope of this particular device. Otherwise, the task is launched in the same scope as the scope of the rule.
To understand rules better, check Rule examples - Start bundle.
Execution options
The rule execution options allow fine-tuning of the mass device management process.
|
Execution option |
Value type |
Description |
|
Execution overlapping |
Enum |
Defines whether multiple tasks on a device can be overlapped or should be replaced. The three possible options in this group are:
|
|
Once per device |
Boolean |
Defines whether the rule should be executed only once or multiple times per device in the scope. If set to true, once the rule execution has finished on a particular device, any subsequent triggering of the rule will be skipped and will not launch a new task involving this device. This behavior applies regardless of whether the previous rule has finished with success, error or warning. |
|
Concurrency limit |
Integer |
The maximum number of devices for which the rule will be executed simultaneously. Keep in mind that the Concurrency limit option is not absolutely strict and has built-in tolerance for minor deviations in the device count. For example, if you have set a Concurrency limit of 1000, it may be possible that the rule is executed on 1005 devices. Such small deviations are tolerated as keeping strict device count sync can come at the expense of efficiency. |
|
Concurrency timeout |
Integer |
This option defines a concurrency timeout in seconds upon which a non-confirmed execution will expire and will stop occupying room in the concurrency limit. |
|
Automatically disable |
Boolean |
Defines whether the rule should be automatically disabled after all devices in the scope have passed through the triggering condition and all launched executions have finished. When no more executions are expected, this option will stop the system from listening for events. This option must always be combined with the once-per-device option. |
|
Time constraint |
This option defines the time slot in which task execution is allowed. This is necessary because long-running tasks might need to interrupt and resume at certain time-schedules, for example updates that should run only during the night but due to the large number of devices the update process takes several nights. As described in Tasks |
|
|
Priority |
Integer |
This options allows you to set priorities to rules that are triggered by the same event and affect the same device i.e. when we have multiple rules with scope - the same device. In that sense, the priority can be viewed as the order in which commands from multiple rules will reach the specific single device. The priority value must be between 1 and 65535, and the higher the value the sooner the rule will be executed. If the rule with the highest priority fails, the execution order continues with the second in priority. If a rule does not have a priority set it is sent to the device irregardless of the other rule's priorities and does not conform with them. Keep in mind, that the Priority option should not be used in combination with the Time constraint or Concurrency limit options as the execution ordering will become too complex. |
Rule life cycle at a glance
At every stage of its life cycle, a rule is assigned a particular execution state by the system which helps its monitoring and management, e.g. when a rule has just been created, it is assigned a DEFINED state. Once the operator enables it, its state becomes ENABLED, and respectively - when it is disabled it enters a DISABLED state. A FAILED_TO_ENABLE state means that the rule cannot be enabled due to a system error or problems with the condition evaluation.
The possible operations on a whole rule are create, enable, disable, modify, fire and delete.
A rule needs to be enabled by the operator in order to be fired and respectively triggered, while modifying it is possible only when the rule is disabled. If you delete a rule, all RUNNING tasks launched by the rule will be automatically canceled.
From the perspective of a rule, you can also monitor and manage all tasks launched by it.