October Rules API Update -Triggers

New Triggers for the Rules API

There are new features to use as a condition to trigger the automation. We will create a sample rule for each one of them to see how they work. These are:

  • dropsBelow and dropsToOrBelow
  • risesAbove and risesToOrAbove
  • securityState

Requirements

Getting started

  1. Open Postman and create a new POST request.
  2. Put in the Rules request URL (https://api.smartthings.com/v1/rules).
  3. Add the location ID as a query parameter.
  4. Change to the authorization tab, select Bearer Token as type and introduce the PAT.
  5. You will paste the rules in the body tab after selecting it’s raw > JSON type. Make sure to replace the IDs correctly.

Note: for more information about the Rules API, go to the documentation or these posts on Smartthings Community:
Advanced Automations with Rules API
FAQ: Getting Started with Rules API
SmartThings API Listing Location Mode


dropsBelow and dropsToOrBelow

dropsBelow

Automation: Use the dimmer switch to turn off other devices when the value drops to a number between 0-24.

{
    "name": "If switch level value drops below 25, turn off other devices",
    "actions": [
        {
            "if": {
                "dropsBelow": {
                    "left": {
                        "device": {
                            "devices": [
                                "Dimmer device ID"
                            ],
                            "component": "main",
                            "capability": "switchLevel",
                            "attribute": "level"
                        }
                    },
                    "right": {
                        "integer": 25
                    }
                },
                "then": [
                    {
                        "command": {
                            "devices": [
                                "Device 1 ID","Device 2 ID","Device 3 ID",...
                            ],
                            "commands": [
                                {
                                    "component": "main",
                                    "capability": "switch",
                                    "command": "off"
                                }
                            ]
                        }
                    }
                ],
                "else": []
            }
        }
    ]
}

dropsToOrBelow

Automation: Change the location mode (night, sleep, etc.) when the dimmer value drops to a number between 0 and 25.

{
    "name": "If switch level Drops Below or equals 25, change location mode",
    "actions": [
        {
            "if": {
                "dropsToOrBelow": {
                    "left": {
                        "device": {
                            "devices": [
                                "Dimmer switch ID"
                            ],
                            "component": "main",
                            "capability": "switchLevel",
                            "attribute": "level"
                        }
                    },
                    "right": {
                        "integer": 25
                    }
                },
                "then": [
                    {
                        "location": {
                            "mode": "location mode ID"
                        }
                    }
                ],
                "else": []
            }
        }
    ]
}

risesAbove and risesToOrAbove

risesAbove

Automation: When the dimmer value raises to a number higher than 75 (76-100) and location mode is night, turn on other devices (lights, outlets, etc.).

{
    "name": "If switch level Rises Above 75 and location mode is Night, then turn on devices",
    "actions": [
        {
            "if": {
                "and": [
                    {
                        "risesAbove": {
                            "left": {
                                "device": {
                                    "devices": [
                                        "Dimmer switch ID"
                                    ],
                                    "component": "main",
                                    "capability": "switchLevel",
                                    "attribute": "level"
                                }
                            },
                            "right": {
                                "integer": 75
                            }
                        }
                    },
                    {
                        "equals": {
                            "left": {
                              "location": {
                                "attribute": "Mode"
                              }
                            },
                            "right": {
                              "string": "Night mode ID"
                            }
                          }
                    }
                ],
                "then": [
                    {
                        "command": {
                            "devices": [
                                "Device 1 ID","Device 2 ID","Device 3 ID",...
                            ],
                            "commands": [
                                {
                                    "component": "main",
                                    "capability": "switch",
                                    "command": "on"
                                }
                            ]
                        }
                    }
                ],
                "else": []
            }
        }
    ]
}

### risesToOrAbove
Automation: If the dimmer switch value raises to a number between 75 and 100, change its color.


{
"name": "If switch level Rises Above 75 then change its color",
"actions": [
    {
        "if": {
            "risesToOrAbove": {
                "left": {
                    "device": {
                        "devices": [
                            "Dimmer switch ID"
                        ],
                        "component": "main",
                        "capability": "switchLevel",
                        "attribute": "level"
                    }
                },
                "right": {
                    "integer": 75
                }
            },
            "then": [
                {
                    "command": {
                        "devices": [
                            "Dimmer switch ID"
                        ],
                        "commands": [
                            {
                                "component": "main",
                                "capability": "colorControl",
                                "command": "setColor",
                                "arguments":[
                                    {
                                        "map": {
                                          "saturation": {
                                            "integer": 40
                                          },
                                          "level": {
                                            "integer": 25
                                          },
                                          "hue": {
                                            "integer": 20
                                          }
                                        }
                                      }
                                ]
                            }
                        ]
                    }
                }
            ],
            "else": []
        }
    }
]
}

Security State

Automation: If the armed state in Smart Home Security changes to arm Away, turn off the specified devices.

{
    "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",
                    "capability": "switch",
                    "command": "off"
                  }
                ]
              }
            }
          ],
          "else": []
        }
      }
    ]
  }
8 Likes

This should be useful! And i’ll also be the first to request the ability to change security state with the Rules API :smile:

Will this documentation be update to reflect the new triggers?

5 Likes

I second that.
Changing security state via API is a MUST.

4 Likes

+1. It’s completely silly that we have to use the virtual dimmer and rules workaround…

1 Like

Are the Security values ArmedAway, ArmedStay and Disarmed? Are they actually working as I’ve not had any luck so far, though I am novice enough with the Rules API to have cocked it up.

This would be a game changer for me as I can’t save Automations that use Notification as an action but the Rules API can handle it.

1 Like

I’m not sure if his Slack status is accurate, but I think Jody might be on vacation at the moment… so don’t be surprised if you don’t get a response immediately.

1 Like

Only just noticed that a rule I left lying around now recognises ArmedStay and Disarmed but doesn’t seem to recognise ArmedAway. It’s all a bit like flying blind on a rocket cycle as there is no information in the API docs as to what is valid.

Hi there! I verified this behavior, the value is correct (“ArmedAway”). Our engineering team is currently reviewing why this state is not triggering the Rule. I’ll let you know their comments.

1 Like

Having updated the mobile app, I had a click on a few things and discovered that the Armed (Away) state is now triggering the rule. Presumably coincidence but it made me look.

1 Like

Awesome! Thanks for sharing :handshake: