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's going to rain in..."
      },
      "titleFormatted": {
        "en": "It !{{is|isn't}} going to rain in [[when]]"
      },
      "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.

Condition cards must return a promise that resolves 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.

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

    return rain.isRaining(); // Promise<boolean>

  })

Action cards must return a promise that resolves once the action is completed, or rejects with an error message that is displayed to the user when the action failed.

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

    return rain.stop(); // Promise<void>

  })

Deprecating cards

Sometimes a Flow card that has been available in the past should be removed. To not break compatibility for users that were using it, add "deprecated": true to your Flow card in /app.json. It will still work, but won't show up anymore in the 'Add Card' list.

Child Topics

• State
• Tokens
• Arguments
• Devices