Registering your workflows

Registration Structure

A Relay workflow registration contains how to trigger it and which devices can trigger it, where to establish the websocket connection when the trigger is observed, and other configuration details. Here are some examples of the workflow registration documentation in the CLI:

$ relay workflow --help
Manage workflow configurations

USAGE
  $ relay workflow COMMAND

TOPICS
  workflow args    List a workflow's args
  workflow create  Create or update a workflow triggered by crossing a charging or discharging threshold of any device on the account

COMMANDS
  workflow args       List a workflow's args
  workflow delete     Destructively delete and remove a workflow
  workflow install    Install an existing workflow into one or more devices
  workflow list       List workflow configurations
  workflow uninstall  Uninstall an existing workflow from one or more devices

$ relay workflow create --help

USAGE
  $ relay workflow create COMMAND

COMMANDS
  workflow create battery  Create or update a workflow triggered by crossing a charging or discharging threshold of any device on the account
  workflow create button   Create or update a workflow triggered by button taps
  workflow create call     Create or update a workflow triggered by inbound or outbound calling
  workflow create event    Create or update a workflow triggered by event emitted by Relay device
  workflow create http     Create or update a workflow triggered by an HTTP request
  workflow create phrase   Create or update a workflow triggered by a spoken phrase
  workflow create timer    Create or update a workflow triggered immediately or with a repeating rule

Install to Device/User IDs

You do have control over which devices can invoke your workflow. You might think of this as "installing the workflow" on devices from a user perspective. This is not technically accurate, as the workflow is actually installed on a workflow server. Really this is about the Relay server listening for triggers from selected devices. Normally, you'll probably want your workflow to be able to get triggered from all the devices on your account. But in case not, we can support that too.

To have all devices on your account be able to trigger your workflow, use the --install-all option in the relay workflow create command.

To instead select a subset of devices that can trigger the workflow, use their 16-digit ID (starts with 99000) with the --install= option when creating or registering a workflow. You can retrieve device IDs from the Dash web console under Users -> device as shown at the bottom of this screenshot:

Normally you would "install" the workflow to the devices at the time of the workflow registration by using the --install-all or --install= options of the relay workflow create command. However, you can add additional devices later to your existing workflow by using the relay workflow install command.

Triggers

Each workflow registration has a trigger action that kicks off the workflow. The trigger can be an action on the Relay device (like a button tap), a remote trigger (HTTP API call), a spoken phrase, or scheduled to occur on a specific time/date. In the example below, we are using a phrase event to start the workflow when the user speaks 'Hello' into the Relay Assistant (either while on the assistant channel, or using the channel button).

$ relay workflow create phrase --trigger=hello --uri 'wss://myserver.myhost.com/helloworld' --name=hello-phrase --install_all

There are additional types such as button and http. For more details see the Triggers section.

Websocket URL and Parameters

Once triggered, the Relay server will invoke a websocket connection to the URL you provided where your Relay SDK-based workflow application lives. In addition to the URL, you can also specify arguments that are sent when the workflow starts. These are key/value pairs that your workflow can access, without those values being hardcoded in your workflow source code. These key/value pairs are provided to the workflow registration by you, and will have the same values on every workflow invocation. This can be helpful if you want to have different triggers with different behaviors all run inside one workflow definition, where that workflow definition has some if statements that branch on these values.

📘

Same workflow with different triggers

It is possible to register the same workflow multiple times, but each registration having a different trigger. Then your workflow can be invoked multiple ways, while having a single copy of your workflow source code and a single hosted environment. To do so, use the CLI's workflow create command with the same wss URI but with different triggers. For example, one via phrase, another via button press, another via http trigger, etc.

Note that each workflow instance will have some metadata available to it that describes how it was triggered: URN of originating device, transcription of phrase spoken, etc. This data comes in the trigger object passed in to the START event handler. For example, printing the trigger argument to the START event handler results in this:

trigger={'args': {'phrase': 'hello', 'source_uri': 'urn:relay-resource:name:device:Bob'}, 'type': 'phrase'}

📘

Parameters to workflows

You may consider using different args (i.e., --arg, --boolean', --numberon theworkflow create` command) on registration, especially if you have multiple registrations of the same workflow source code, if you want to have parameterized behaviors in your workflow. These key/value args are provided to your workflow instance depending on which registration was triggered.

Note that an HTTP Trigger can provide its own additional set of key/value pairs by placing them in a special place in its POST payload. See the HTTP Trigger section for more information on that.

If during the registration you receive the error missing_capability then contact Relay Support. You can manually check that you have this capability by running a CLI command.