Rules vs Routines

I have several routines currently installed in my hub. Whereas there’s a UI that helps you create a routine, the documentation on the format of a rule is surely lacking today. It’s unfortunate that there’s no ability to capture an existing routine in JSON format so that you can refine it as a rule.

For people creating rules, is it a question of guessing the syntax or is there a better way?

Thanks

2 Likes

The Rules API is documented here

Rules API

and some sample rules are documented here

Rules Examples

And rather than trying to use a tool like Postman to create and manage your rules, there is an easier interface available via the API Browser+ from @TAustin.

Rules are defined in the API Reference so the syntax is well defined. I wouldn’t go as far as well explained but certainly well defined.

I have yet to find out how to see the Rules that the app manages as Routines. It would be handy to see exactly what they have implemented as it isn’t always clear.

Scenes are really just single payload only Rules wearing a frock. They uncomfortably straddle the divide between developer tools and end user tools. They are recognised as a type of Automation alongside Rules in the developer documentation and the API (Routines are not covered in either). However they can only be managed like Routines in the app and are subject to the same editing abuses when devices are deleted which I find inexcusable. It is possible to see the actual Rules though.

Perhaps surprisingly, Routines and Scenes have access to functionality that is not documented in the API reference. Sometimes you can use it anyway if you figure out the syntax (e.g. executing Scenes), but other stuff is just unsupported (notifications). Toggle is another thing the Routines can do that is undocumented and possible also unsupported.

But I have now …

1 Like

Do share…

Basically https://api.smartthings.com/ isn’t the only API out there. There is one I am currently calling the Client API (https://client.smartthings.com/) that uses the same authorization. I’ve known it is there for ages so how I’ve never discovered https://client.smartthings.com/rules (optional ?locationId={{locationId}} filter) outputs your Routines is baffling me.

I am reliably informed that you can indeed use it to create Routines as you might expect.

1 Like

@TAustin Something you can add to the API Browser+?

I just pushed it out :slight_smile:

1 Like

Awesome! Is that API actually documented anywhere? Can we find out if there is additional info to be gleaned?

1 Like

FYI, I tried to implement a delete and so far have been unsuccessful.

Strangely, trying it from Postman and I get a successful return, but the routine didn’t actually get deleted. Trying it from my web app gives me this error:

{"requestId":"FABFF867-C8ED-41D6-8B17-D89E655C04F0","error":{"code":"ForbiddenError","message":"delete-behaviors-bulk-fail-invalid-scopes","details":[]}}

Looks like I’m missing a super secret scope in my token.

Such as the rules created by Smart Lighting? Got those too. Todd has been advised …

1 Like

Curious, how are you finding additional endpoints to query?

I didn’t. I figured out that as Smart Lighting is an app plugin, not a SmartApp (despite where it gets listed), its Rules must be in the same place as the Routines are and it was just a matter of overriding the default filtering. As Routines and Rules have SMARTTHINGS in capitals as the creator I figured that might be significant and I couldn’t think of anything around that could be using the known possibility of RECIPE. Presumably there might be other recipe creators in the app in future, but that is a bridge to cross then.

Oh, and if anyone is wondering about Routines created by templates, those are just ordinary Routines with a bit more metadata saying which template was used.

Exposing the Smart Lighting rules yesterday has helped me with a couple of longer lasting questions, namely what is a ‘recipe’ and what is the ‘ARB’. Obviously I was well aware that a /recipes endpoint existed and ‘RB’ always seemed likely to stand for ‘Rule Builder’. I had a few thoughts about what the ‘A’ ought to stand for (disappointingly, it is ‘Advanced’).

My knowledge remains superficial, but having read a Smart Lighting rule it became trivial to then find its previous generation which I am going to call recipeVersionInstall as I don’t know what else to call it. That consists of a recipeVersion and its configuration data, with the recipeVersion being a combination of a template rule and configuration placeholders, and yes there is a recipe in there too, but there is no body to that.

Where does the ARB come in? Beats me, but it gets a credit in the rule and recipeVersionInstall metadata.

I don’t have any real point to make. I am just observing that none of what I could see looked engineered as a one-off solution and it seemed to have a more conventional flow to it compared to Routines.

@orangebucket Thanks for sharing this link

I also went through my own automations.

I have question about

    "sequence": {
      "then": "Parallel",
      "else": "Parallel"
    }

    "sequence": {
      "then": "Serial",
      "else": "Serial"
    }

What is the purpose of these sequence definition?

That particular form of sequence is associated with an if action. In that action you will also have a then and possibly an else that each contains an array of actions. The sequence determines whether those actions are executed one after the other in the order they are defined (serial) or all at the same time (parallel).

You will also find a sequence at the top level. So …

actions: [
    ...
],
sequence: {
    "actions": "Serial"
}

That will allow you to make the same choice with the actions array.

1 Like

Sorry to be dense…what does the URL look like to get the Smart Lighting rules?

hmmmmm

I get them using:

https://client.smartthings.com/rules?creators=RECIPE

with an optional locationId={{locationId}} if you have multiple locations.

In theory that would get you any rules the client apps create from recipes, but Smart Lighting seems to be the only one out there at the moment.

1 Like

Yeah, well while I wouldn’t say this is a grey area, it could be a tad whiter.

Personally I think that given the relative lack of guidance material it is potentially game changing for those interested in working with Rules.