Not clear which conditions can trigger an event

Developer Programs Rules API
1

From your documentation, it’s not clear to me which actions can fire events, i.e., on which conditions rules can be triggered. I see this documentation:

In the Rules API a trigger acts as a way to start the execution of a rule. When we create a rule with an EqualsCondition that uses a DeviceOperand the device being used will then act as a trigger for the rule.

So, this is clear. But what if I want to run something at a certain time. I can use an every action, which presumably causes a trigger at a specified (specific) time. But where is this documented? Is it equally possible to use an IfAction at a certain time? For example, this Rule below is supposed to trigger at 7:45 in the morning IF this is before sunrise (so, at 7:45 if it’s dark).

It’s not clear to me if this will cause a trigger, or if I have to rewrite it using every instead. I’d like some more explicit documentation on what exactly causes a trigger event, triggering a Rule, and what does not. At least I don’t see it here: API | Developer Documentation | SmartThings or here: Rules | Developer Documentation | SmartThings

[
  {
    "if": {
      "and": [
        {
          "greaterThanOrEquals": {
            "left": {
              "time": {
                "reference": "Now"
              }
            },
            "right": {
              "time": {
                "reference": "Midnight",
                "offset": {
                  "value": {
                    "integer": 27900
                  },
                  "unit": "Second"
                }
              }
            }
          }
        },
        {
          "lessThan": {
            "left": {
              "time": {
                "reference": "Now"
              }
            },
            "right": {
              "time": {
                "reference": "Sunrise"
              }
            }
          }
        }
      ],
      "then": [
        { ... }

Or should it be changed to something like this for it to work?

[
  {
    "every": {
      "specific": {
        "reference": "Midnight",
        "offset": {
          "value": { "integer": 27900 },
          "unit": "Second"
        }
      },
      "actions": [
        {
          "if": {
            "lessThan": {
              "left": { "time": { "reference": "Now" } },
              "right": { "time": { "reference": "Sunrise" } }
            },
            "then": [
              { ... }
2

As far as I know the only operands that can act as triggers are device and location as they have the trigger property.

Scheduled execution requires every.

3

Hi, @niek

Indeed, as Graham mentioned above, if you want to trigger something at a specific time, you need the property “every”.

"When they are included in the “IF” property, they need an actual trigger to run, since the Rules engine cannot check every second if the time condition is met or not. In this case, they would be similar to a precondition, and you would need a configuration like:

“IF a device changes its status AND the current time is between X and Y, then, run something”

I will review the documentation and let the team know that it isn’t clear what can be a trigger. But what I can think of to explain it is that triggers are basically a status change in a device or location mode, that is why we have the operands of greaterThan, Equals, etc.

4

Thank you both for the answers! I like Graham’s answer where there’s a clear indicator in the documentation to know if something can act as a trigger, but it still doesn’t distinguish between a regular time in an IfAction, and a time as specified in an EveryAction. So, I think it could still made a lot more clear (in this documentation: Rules | Developer Documentation | SmartThings ) what can act as a trigger event, and what can not. I do understand your reasoning, @nayelyz , and it makes sense (also after checking my various existing app-generated Rules’s JSON in my.smartthings), but I can also imagine that the Rules API engine could have theoretically been implemented smart enough to know when it should trigger based on a regular time comparison as well. Since I don’t know the implementation details, it just leaves me guessing what can be a trigger. It would be nicer to clarify it more precisely to remove any guesswork from the equation :slight_smile:

I do really like the SmartThings architecture with the Lua Edge Drivers + Rules API, making on-device execution possible in a lean, efficient way, with relatively low system resources. E.g., I think Home Assistant needs at least 2GB of RAM, whereas the SmartThings hub has 512MB or so, if what I read somewhere is correct. This more efficient, leaner design with fewer “moving parts” should also be more reliable and simpler. So, well done! And the documentation is also generally good, only this part wasn’t very clear :slight_smile:

Thanks again!

5

If you are familiar with SmartThings apps (in the sense of SmartApps for automations etc), I find it helpful to know that each Rule is implemented as an installed instance of an app which has the undocumented BEHAVIOR type. Just like any installed app the Rules can create Subscriptions and Schedules and those are documented in the API Reference. Sadly the Rules don’t seem to use the Health related subscriptions.

They seem to have gone for a pretty rigid demarcation of subscriptions and schedules as the if and every actions.