Run a built-in workflow

Running a built-in workflow is the easiest way to get started. With just one CLI command, in under one minute you can register a workflow, and then trigger it and watch it run. It's super easy.

CLI Setup

If you haven't already installed and logged in to the Relay CLI, you'll need to do that now. We'll be using the CLI here. Getting the CLI set up is the hardest part of this exercise.

About Built-In Workflows

There are a few workflows that are built-in to the Relay server. This means you won't won't need to write custom code using the SDK, nor need to get your code hosted. You can work up to that later. Here we'll be using a couple particular built-in workflows: hello_world and led_demo.

Hello World

The quintessential developer example, of course. This one will do a bit more than just output "hello world". It will ask you for your name, and then repeat it back to you with a greeting. We want to show you a round-trip of voice content.

The first step is to register this workflow with the Relay server, and identify the trigger you want to start this workflow. To do that run, the following Relay CLI command at your shell prompt:

relay workflow create phrase --trigger "hello" --name internal1 --uri relay-local://hello_world --arg greeting=from --install-all

We'll explain all those arguments later. But for now, run the command and trust me. This command should return output that looks like the following:

=== Installed Workflow

 ID                                  Name      Type          Uri                       Args                   Installed on 
 ─────────────────────────────────── ───────── ───────────── ───────────────────────── ────────────────────── ──────────── 
 wf_internal1_5LKGcyTjnWWpLmAkgLQKTD internal1 phrases:hello relay-local://hello_world greeting=from | string all devices

Now, on the device hold down the Assistant button (the one on the side of the device between the '+' and '-' buttons) like a walkie-talkie button, say the word "hello", and let go of the button. The device should then verbally ask the question "What is your name?" and wait for a response. This time, hold down the Talk button on the face of the device in the center of the LED ring while you speak your name. The device should then speak back to you "Hello {yourName}, from {deviceName}".

Tada! You just ran your first voice-triggered workflow.

We'll do one more workflow in a moment below. But first, let's understand a bit more about these arguments now that you've seen them in action.

Tip: the device name is set in Dash (web console).

CLI Arguments

Let's pick apart the CLI command and explain what those arguments are.

relay workflow create ...

This means we are going to create a new registration for a workflow. There are other operations we can do, such as list and delete.

... phrase --trigger "hello" ...

There are different kinds of triggers that can start a workflow, such as a button press, an NFC tap, or a spoken phrase. Here we are creating a spoken phrase trigger. And the phrase to speak is "hello". With Relay's speech recognition capabilities, you can make the phrase pretty much anything you want. Speaking this phrase (while holding down the Assistant button) is what starts the workflow.

... --name internal1 ...

This is the human-readable name of the workflow. Every workflow should have a unique name. There isn't anything magical about this name, it is just a name.

... --uri relay-local://hello_world ...

This is the URL where the workflow code exists that defines what our workflow does. Normally this would be the URL to where your workflow code is. But here we are using a built-in workflow, which you can tell is built-in because it starts with the special protocol relay-local://.

... --arg greeting=from ...

This is a name/value pair that will be passed into the workflow when it gets started. This isn't required on all workflows, but it demonstrates that we can reuse workflow code and enable it to have different behaviors based on parameters that are set on different registrations. (Yes, you can have multiple registrations to the same workflow implementation (URL), to get code reuse.) This built-in workflow expects this greeting argument, so we do need to supply it here.

... --install-all

The wording for this argument sounds like we are installing the workflow on devices. A better explanation is that we are making the trigger available on devices, because we can limit which devices can trigger the workflow. In this case, we are letting all devices on our account have the capability to trigger this workflow.

LED Demo

Let's register another built-in workflow and watch it run. Run the following CLI command at your shell prompt:

relay workflow create phrase --trigger "lights" --name internal2 --uri relay-local://led_demo --install-all

Now hold down the Assistant button (the round one on the side of the device) while you say the trigger phrase "lights", and let go of the button. The device should then announce "To see the next effect, tap the Talk button. Double tap at any time to end the demo." And it will sit patiently waiting for you to tap the big Talk button on the face of the device. Go ahead and tap it once. The workflow will light up the LEDs like a rotating rainbow and verbally announce it as such. Then it will sit patiently again waiting for you to tap the Talk button. Upon that next tap it will show and announce the next LED effect. If you get tired of this before it gets to the last LED effect, just do a double-tap of the Talk button and it should announce it is "stopping LED demo", and you should be back on the channel you started from.

So, what happened to our "hello world" example, did we overwrite it? Nope, multiple workflows can co-exist as long as they have a different trigger. So once the LED demo announced it is done, go ahead and hold down the Assistant button while you say the original trigger phrase "hello" and listen to "hello world" work.

You can also list all the configured workflows using the CLI:

relay workflow list --extended

And it should provide the extended output that looks like this:

=== Installed Workflows

 ID                                            Name                 Type             Uri                                                       Args                                       Installed on               
 ───────────────────────────────────────────── ──────────────────── ──────────────── ───────────────────────────────────────────────────────── ────────────────────────────────────────── ────────────────────────── 
 wf_internal1_5LKGcyTjnWWpLmAkgLQKTD           internal1            phrases:hello    relay-local://hello_world                                 greeting=from | string                     all devices                
 wf_internal2_dvzYUlxsdKB3uzSJUXgnpD           internal2            phrases:lights   relay-local://led_demo                                                                               all devices

You just configured two workflows in Relay, and can invoke either one depending on what you say in to the device.

Are you ready to write your own custom workflow code? If so, continue on.