Trigger Execution Conditions
A trigger is registered with an execution condition and a command or server code to execute when the execution condition is met. You can use the following three conditions:
- One-Time Schedule
- Recurring Schedule
- State Condition
One-Time Schedule
This condition will fire the trigger just once at the designated time.
Use the ScheduleOncePredicate class to use a one-time schedule.
Specify the time to execute the trigger in scheduleAt. Specify the time in UNIX time in milliseconds (UTC).
Recurring Schedule
This condition will fire the trigger on the scheduled interval.
Use the SchedulePredicate class to use a recurring schedule.
Specify the time to execute the trigger in schedule in the cron expression.
State Condition
This condition will fire the trigger based on the latest field values of the thing state. The trigger condition is composed of two parts. The first part is the comparison condition that defines how to make the comparison with the state, and the second part is the execution condition that defines how to associate the comparison condition and the actual trigger execution.
Use the StatePredicate class to use the state condition.
The state condition is defined by the following two conditions.
Comparison Condition
You will specify how to make the comparison with the latest state's fields using the subclasses of the Clause class. Please also check the class diagram.
You will use the following methods in the Clause subclass to define the condition.
| Method | Comparison to be defined |
|---|---|
| EqualsClause Initializer | True if the field value is equal to the specified value. |
| NotEqualsClause Initializer | True if the field value is not equal to the specified value. You will first create an EqualsClause object and then pass it to NotEqualsClause as an argument. |
| RangeClause Initializer (field:lowerLimit:lowerIncluded: upperLimit:upperIncluded:) |
True if the field value is in between the specified values. You can also specify if you want to treat the upper and lower values inclusively or exclusively. |
| RangeClause Initializer (field:upperLimit:upperIncluded) | True if the field value is less than (less than or equal to) the specified value. |
| RangeClause Initializer (field:lowerLimit:lowerIncluded) | True if the field value is greater than (greater than or equal to) the specified value. |
| AndClause Initializer | Concatenate multiple conditions with AND. True if all the specified Clauses are true. |
| OrClause Initializer | Concatenate multiple conditions with OR. True if at least one of the specified Clauses is true. |
Use the combination of the above methods to create a Clause instance that defines your comparison condition.
Execution Condition
| Value | Association to be made |
|---|---|
| TriggersWhen.CONDITION_TRUE | Execute the trigger if the comparison condition is true. |
| TriggersWhen.CONDITION_FALSE_TO_TRUE | Execute the trigger if the comparison condition was false and becomes true. |
| TriggersWhen.CONDITION_CHANGED | Execute the trigger if the comparison condition changes. |
If you want to set the association like "when the comparison condition is false" and "when the condition was true and becomes false", please consider reverting the comparison conditions. You can also use EqualsClause(clause, false).
When using CONDITION_TRUE, be aware that the command/server code could be executed every time the state is updated. If you set a condition "the room temperature is above 30 degrees" with CONDITION_TRUE, for example, the associated command/server code will be executed every time the thing state is updated as long as the room temperature is over 30 degrees.
If you register multiple triggers with the same condition, all of them will execute the designated command/server code when the specified condition is met. Please avoid registering duplicate triggers by checking a list of triggers.