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 samewss
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 the
workflow 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.
Updated 9 months ago