Flow

The Flow Editor is where users create Flows for their Homey. As a developer, you can add new functionality from your app to the Flow Editor by exposing various cards.

A Flow consists of cards in three columns: when, and, then.

  • Cards in the when... column are called triggers. Your app tells Homey to fire a trigger, which will then run all of the user's flows with this trigger.
  • Cards in the ...and... column are called conditions. These are things that must be true, for the flow to continue. For example it is raining, or the vacuum cleaner is cleaning.
  • Cards in the ...then column are called actions. These are fired when the trigger has been fired, and all conditions are met.

Your app can expose any of these three card types, by defining them in your /app.json.

If your app contains one or more drivers, please note that most device classes already have their own flow cards. So most of the time it's not necessary to create them yourself.

/app.json

"id": "com.weather.example",
...
"flow": {
    "triggers": [
        {
            "id": "rain_start",
            "title": {
                "en": "It starts raining"
            }
        },
        {
            "id": "rain_stop",
            "title": {
                "en": "It stops raining"
            }
        }
    ],
    "conditions": [
        {
            "id": "is_raining",
            "title": {
                "en": "It !{{is|isn't}} raining"
            }
        },
        {
            "id": "raining_in",
            "title": {
                "en": "It is going to rain in..."
            },
            "args": [
                {
                    "name": "when",
                    "type": "dropdown",
                    "values": [
                        {
                            "id": "5",
                            "label": {
                                "en": "5 minutes"
                            }
                        },
                        {
                            "id": "10",
                            "label": {
                                "en": "10 minutes"
                            }
                        },
                        {
                            "id": "15",
                            "label": {
                                "en": "15 minutes"
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "actions": [
        {
            "id": "stop_raining",
            "title": {
                "en": "Make it stop raining. Haha."
            }
        }
    ]
}

Triggering a flow

To fire a trigger, run the following code from anywhere in your app:

/app.js

let rainStartTrigger = new Homey.FlowCardTrigger('rain_start');
rainStartTrigger
    .register()
    .trigger()
        .catch( this.error )
        .then( this.log )

All of the Flows on the Homey, with the trigger rain_start will now fire.

More advanced triggers can be achieved using Tokens, State and Devices.

Listening for events

In your app, you should register a run listener for each Flow card. Conditions and Actions should always do this, and Triggers only when they have one or more Arguments.

Cards must resolve with a true value for the Flow to continue, or a false value to stop the Flow from executing. When the card is rejected, the Flow stops executing as well.

/app.js

let rainingCondition = new Homey.FlowCardCondition('is_raining');
rainingCondition
    .register()
    .registerRunListener(( args, state ) => {

        let raining = rain.isRaining(); // true or false
        return Promise.resolve( raining );

    })

let stopRainingAction = new Homey.FlowCardAction('stop_raining');
stopRainingAction
    .register()
    .registerRunListener(( args, state ) => {

        let isStopped = rain.stop(); // true or false
        return Promise.resolve( isStopped );

    })

Child Topics