Skip to main content

Rules

Rules are a versatile tool, enabling you to automate the Devices and services that connect to the SmartThings Platform. Rules are useful for manipulating Devices automatically when a specific event is triggered, for automating repetitive tasks such as adjusting a light as specific intervals, and for providing users with "set it and forget it" functionality.

We believe that speed is critical to ensuring a great user experience. That's why, when possible, Rules execute locally on a Hub. In order for Rules to execute locally, all Device features and services involved in the Rule must support local execution. Rules involving features or services that do not support local execution are run in the SmartThings Cloud.

info

When a user installs a Rule, only the owner of the SmartThings account the Rule is installed on can modify the Rule. This means that as a developer, you will not be able to make updates to any Rules you create that other users install on their accounts.

If you instead want to run automation logic on your own platform, have the ability to update automation logic after user installation, create a standalone application, or create an application users can install in the SmartThings app, refer to Connected Services for an alternative to Rules.

Visit the Rules API reference documentation to learn more about the Rules API calls available to you. When you’re ready to start creating Rules, visit our Rules API community page. Here you’ll find tutorials on getting started, plus Rule examples, and more.

The Structure of a Rule#

A Rule is defined in JSON format and contains a name, install source, and a list of actions. A single Rule can be used to contain multiple actions within it. These actions represent a tree that is evaluated when the Rule is triggered.

Actions are a core component of the Rules API and define how a Rule behaves. Let's take a look at an example Rule to get a better understanding of the structure and syntax in use.

The Structure of a Rule

This Rule compares the device’s contact sensor (the left side of the equation) to the value defined in the right side of the equation.

Here is a breakdown of the Rule above:

  1. Action - An Action defines what task the Rule is completing and contains at least one Condition. An Action is contained within the actions list - multiple Actions may be specified in a single Rule.
  2. Condition - An evaluation used as a trigger for the action. A Condition is evaluated during Rule execution and is contained within an action. In this case, the Condition is an if statement.
  3. Operation - The Operation defines what process to perform on the operands specified within the Operation. In this case, the Operands are compared for equality with an equals statement.
  4. Operands - The devices or locations involved in a Rule. In this case, a contact sensor and switch are included in the Operation.
  5. Result - The command(s) to perform if the Condition is met. If the Condition is not met, any code in the else block will be executed.

Conditions#

A Condition consists of one or more operations and/or operands. The type of condition you use will determine the number of operations and operands required. For example, an if condition requires two operations (each containing an operand). Visit our GitHub page to view example Automations and see the formatting each type of condition uses.

The following condition statements are supported:

  • command - A simple condition used to manipulate a device.
  • every - Each time the specified condition is met, perform a given action.
  • if - Performs the action(s) specified in the then statement if the condition evaluates to true. Otherwise, the else statement will be executed.
  • sleep - Specifies a time interval to wait before executing the remaining code in the condition statement.

Operations#

Operations are nested within conditions. The following operations are supported:

  • equals
  • greaterThan
  • lessThan
  • greaterThanOrEquals and lessThanOrEquals
  • specific
  • between
  • securityState
  • changes

equals#

This operation compares a left and right side for equal values.

In this example, the switch attribute (operand) given on the left side is evaluated against the string given on the right side. When the left and right values are equivalent, the condition is evaluated as true.

"equals": {
"left": {
"device": {
"devices": ["<insert-your-device-ID-here>"],
"component": "main",
"capability": "switch",
"attribute": "switch"
}
},
"right": {
"string": "on"
}
}

greaterThan and lessThan#

These operations check if a value given on the left side is greater or less than the current value of an attribute specified on the right side.

In this example, if the switch’s current level is greater than the specified integer, the condition is true.

This operation will evaluate to true for each event that is greater than (or less than) the specified value. For example, if you use greaterThan to control your thermostat when the temperature rises above 50, the Rule will evaluate to true and run for each interval over 50. To have a Condition run only once when a value changes to above (or below) a set point, wrap the changes operation around the current greaterThan operation.

"greaterThan": {
"left": {
"integer": 50
},
"right": {
"device": {
"devices": ["your-device-id-here"],
"component": "main",
"capability": "switchLevel",
"attribute": "level"
}
}
}

lessThanOrEquals and greaterThanOrEquals#

These operations are variations on lessThan and greaterThan and add a secondary check for equality.

In the example below, a specified integer on the left side is evaluated against the current level of a switch. If the switch’s current level is less than or equal to the specified integer, the operation is true.

This operation will evaluate to true for each event that is greater than (or less than) the specified value. For example, if you use greaterThanOrEquals to control your thermostat when the temperature is equal or greater than 50, the Rule will evaluate to true and run for each interval at 50 and above (run once at 51, run again at 52, etc.). To have a Condition run only once when a value rises above (or below) a set point, wrap the changes operation around the current greaterThanOrEquals operation.

"lessThanOrEquals": {
"left": {
"integer": 50
},
"right": {
"device": {
"devices": ["your-device-id-here"],
"component": "main",
"capability": "switchLevel",
"attribute": "level"
}
}
}

specific#

This operation is used in conjunction with the every condition and gives a specific instance under which the operation evaluates to true.

In the example below, the operation will evaluate to true every day at 11:55 AM and change the specified location’s mode.

"every": {
"specific": {
"reference": "Noon",
"offset": {
"value": {
"integer": -65
},
"unit": "Minute"
}
},
"actions": [
{
"location": {
"mode": "your-location-mode-id-here"
}
}
]
}

between#

Check if a given attribute is between two provided values.

In this example, if the attribute level falls between the start and end integers, the operation is true.

"between": {
"value": {
"device": {
"devices": ["your-device-id-here"],
"component": "main",
"capability": "switchLevel",
"attribute": "level"
}
},
"start": {
"integer": 50
},
"end": {
"integer": 75
}
}

securityState#

If the state of Smart Home Security changes to a specified value, perform a set of actions.

The Rule excerpt below checks for the Smart Home Security state to change to ArmedAway and controls a set of Devices when the state is met.

{
"name": "If SHM changes to armAway, turn off devices.",
"actions": [
{
"if": {
"equals": {
"left": {
"location": {
"attribute": "Security"
}
},
"right": {
"string": "ArmedAway"
}
},
"then": [
{
"command": {
"devices": [
"device 1 ID","device 2 ID","device 3 ID",...
],
"commands": [
{
"component": "main",

changes#

changes is an operation that tracks the state of the operation it contains, returning true when the state of the inner operation transitions from false to true.

changes with lessThan:#

In the example below, the operation evaluates to true if the dimmer’s switch level changes to less than the given value of 50. It will not evaluate to true again until the dimmer first changes to 50 or above, and then changes to below 50 again.

"changes": {
"lessThan": {
"left": {
"device": {
"devices": [
"{{your-device-id-here}}"
],
"component": "main",
"capability": "switchLevel",
"attribute": "level",
}
},
"right": {
"integer": 50
}
}
}

Operands#

Operands are used within operations. The operand is evaluated against a value (often an integer or string) specified in the condition you elect to use for your Rule. Simply put, an operand is the Device or Location you want to evaluate in a Rule.

Supported operands include:

  • Device - For evaluating a device attribute.
  • Location - For evaluating a location mode state.
  • Array - An array containing multiple operands.
  • Scene - A previously created Scene can be activated from within a Rule.

Logical Operators#

Logical operators (and, or, and not) enable you to use more than one operation (or operand), or change the logic of a Rule's condition.

and / or#

"if": {
"and": [
{
"equals": {
"left": {
"location": {
"attribute": "Mode"
}
},
"right": {
"string": "<insert-the-mode-id-here>"
}
}
},
{
"between": {...}
}
],
"then":[...]
}

not#

This operator inverts the operation. In the example below, if the switch’s current state is different than on, the condition evaluates to true.

"if": {
"not": {
"equals": {
"left": {
"device": {
"devices": [
"<insert-device-id-here>"
],
"component": "main",
"capability": "switch",
"attribute": "switch"
}
},
"right": {
"string": "on"
}
}
},
"then":[...]
}