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.

Specify an execution condition for a trigger in the predicate field for trigger definition. 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.

Set SCHEDULE_ONCE in the eventSource subfield to use a one-time schedule.

Set the time to fire the trigger in the scheduleAt subfield. Specify the time in UNIX time in milliseconds (UTC).

Recurring Schedule

This condition will fire the trigger on the scheduled interval.

Set SCHEDULE in the eventSource subfield to use a recurring schedule.

Specify the time to execute the trigger in the schedule subfield in the cron expression.

State Condition

This condition will fire the trigger based on the latest field values of the thing state.

Set STATES in the eventSource subfield to use the state condition.

The state condition is defined by the following two conditions (read here for details).

• Comparison Condition
• Execution Condition

Note that if the state is a nested JSON data, you can use only the top-level fields for setting the comparison condition.

Comparison Condition

Set the comparison condition in the condition subfield.

Here is a summary of how you define the comparison condition.

• Equal: The condition is true when the specified field has the specified value. The value can be a string, integer, or boolean.

  "condition": {
    "type": "eq",
    "field": "...",
    "value": ...
  }
  

• Not Equal: The condition is true when the specified field does not have the specified value. The value can be a string, integer, or boolean.

  "condition": {
    "type": "not",
    "clause": {
      "type": "eq",
      "field": "...",
      "value" ...
    }
  }
  

  Note that the type not only accept the clause with the type eq. You cannot negate other conditions (e.g., range) with the type not.

• Less Than/Less Than or Equal to: The condition is true when the specified field has the value less than (or equal to) the specified value. The upper limit can be an integer or floating point number.

  "condition": {
    "type": "range",
    "field": "...",
    "upperLimit": ...,
    "upperIncluded": false
  }
  

  Setting the upperIncluded field to false will make the condition "less than". Setting it to true (or not setting the upperIncluded) will make the condition "less than or equal to".

• Greater Than/Greater Than or Equal to: The condition is true when the specified field has the value greater than (or equal to) the specified value. The lower limit can be an integer or floating point number.

  "condition": {
    "type": "range",
    "field": "...",
    "lowerLimit": ...,
    "lowerIncluded": false
  }
  

  Setting the lowerIncluded field to false will make the condition "greater than". Setting it to true (or not setting the lowerIncluded) will make the condition "greater than or equal to".

• And: Concatenate multiple conditions with AND. The condition is true when all the conditions are true.

  "condition": {
    "type": "and",
    "clauses": [
      {"type": "...", ...},
      {"type": "...", ...},
      ...
    ]
  }
  

• Or: Concatenate multiple conditions with OR. The condition is true when at least one of the conditions are true.

  "condition": {
    "type": "or",
    "clauses": [
      {"type": "...", ...},
      {"type": "...", ...},
      ...
    ]
  }
  

Execution Condition

Set the comparison condition in the triggersWhen subfield.

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.

When using CONDITION_TRUE, be aware that the command 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 will be executed every time the thing state is updated as long as the room temperature is over 30 degrees.