As seen in the Location section, workflows are capable of retrieving information on the location of a device, including the address, latitude and longitude coordinates, indoor location, and more. What we haven't yet discussed is how we can use these location services to trigger workflows. In this section, we will discuss how to trigger workflows through a change in a device's location.

Why Would You Need Location Triggers?

Location triggers enable you to start a workflow that is triggered by a change in a device's location. The locations are not only limited to addresses, but can even be mapped to rooms within a specific building.

For example, say you work as a manager at an amusement park. Each member of your team is in charge of running or supervising a particular ride or exhibit, and you have a First Aid station for medical emergencies. Each member of your team also carries a Relay for communication. However, you want a way to trigger a workflow when an employee enters the First Aid station. You want this trigger to be registered to a workflow that automatically places you on a call with the employee who entered the station, so that you can quickly get in touch with them. We can easily solve this problem using geofence triggers.

To solve this problem, you can first create a geofence around the First Aid station. A geofence represents a geographical location that is surrounded by a virtual "fence". We will talk about how to create these fences later in this section. Next, you want to create a workflow that is triggered whenever a staff member enters the geofence that surrounds the First Aid station. When it is triggered, you can map the trigger to a workflow that places a call to you, where you can then check in with the member. This way, you are notified whenever a member of your staff enters the station, and are automatically placed on a call with them to ensure swift communication.

Another use case could be through indoor position triggers. Say you are in charge of food delivery at a hospital, and would like all of the staff who delivers food to each room to carry Relays for communication. However, you would also like to know when each staff member has finished delivering the meals to all of their rooms. This can be done with position triggers. You place a beacon in various parts of the hospital, and create a workflow that is triggered whenever an employee delivers the last meal on their cart.

By creating a workflow that is triggered when they exit the last room on their floor, you can broadcast a message that notifies the Dash and all other devices in that group that food delivery on that floor is complete. This could improve efficiency of the food deliveries in that hospital by automatically providing updates to the other members of the team and administration whenever a task is completed by a particular member. Then, the available team member could go help other team members that are behind schedule.

Now that you are more familiar with how location triggers can be useful, lets talk about how to set up these triggers on your devices. Lets start with Geofence Triggers.

🚧
Updating a Device's Location
Before you create your workflows that use location triggers, you should keep in mind that the device's location is refreshed every few minutes. Because of this, when you move your device outside of a geofence or into another room, the workflow you have registered will not be triggered instantaneously. Instead, the workflow will be triggered once the updated location is retrieved, or a refresh occurs on the Dash. While testing your workflows, you can refresh the device's location on the Dash after moving it to the new location. Once the device's location is updated on Dash, your workflow should be triggered.

Geofence Triggers

Creating a Geofence

Geofences provide a perimeter around a specified location. Think of it like a virtual "fence" that is surrounding a particular address with a circle. When you create a geofence, it will be tied to your account. This way, all of the devices can trigger workflows based on that geofence. Creating a geofence can be done in just a few simple steps. You can create one through the Relay Dash or through the Relay CLI. Lets start with creating a geofence on Relay Dash.

Creating a Geofence on Relay Dash

The following video walks you through how to create a Geofence on the Relay Dash. There is also a set of steps underneath the video, if you would prefer to follow along that way.

Once you are on the Relay Dash, navigate to the "Location" section, that is located on the far left of the screen.
After clicking on "Location", you should see a list of indoor/outdoor locations, location history, geofence and building admin tools, and beacons. Since we are setting up a geofence, we want to click on the "Geofence Admin" section.
In the "Geofence Admin" section is where you will be able to see all of your geofences. They are represented by a small blue circle surrounding the address where your geofence is set to. You should now see a button labeled "Create Geofence" on the left. Click on the "Create Geofence" button.
After clicking on "Create Geofence", you will be asked at which address you would like to create a geofence. Enter in your desired address and click on it when it comes up below while typing it in.
When you select an address for your geofence, you should see a small circle surrounding the address that you entered. You can click on the map and drag it to tweak where the center of your geofence is located. When you are satisfied with the center of the geofence, you can drag the bar under the map to increase the radius size. Through the Relay Dash, you can set your radius to be anything between 40 and 5000 meters. When you are satisfied with the radius, hit the "Submit" button.
After hitting "Submit", you will be prompted to give your geofence a name. Enter in a name for your geofence and click "Submit".
Once you click "Submit", Dash will tell you that your geofence has been successfully created. That's it! You should now see your geofence under the "Geofence Admin" section.

Creating a Geofence through the Relay CLI

Even though you can easily create a geofence through the Relay Dash, you might want to create one instead through the Relay CLI. The CLI includes a built-in command for creating a geofence on your account. This command allows you to create a geofence with the same parameters as the Relay Dash. To view the complete usage of the command, you can enter relay geofence create --help into the command line.

$ relay geofence create --help
Create geofence

USAGE
  $ relay geofence:create -s <value> -n <value> -r <value> [-N] [-a <value> | -g <value> | -t <value>]

FLAGS
  -n, --name=<value>           (required) friendly name of the geofence
  -r, --radius=<value>         (required) radius in meters that defines the geofence circle
  -s, --subscriber-id=<value>  (required) [default: 5e70d451-7836-4196-b347-8f6278b671f0] subscriber id
  -N, --dry-run
  -a, --address=<value>        street address of the geofence
  -g, --longitude=<value>      longitude coordinate between [-180, 180]
  -t, --latitude=<value>       latitude coordinate between [-90, 90]

DESCRIPTION
  Create geofence

As you can see above, the required flags include the name, radius, and subscriber ID. However, if you do not enter in a subscriber ID, it will just default to the subscriber ID of the account that is currently signed in. Some other flags that you want to include are either the address of your location with the -a flag, or the longitude and latitude of your location, which are -g and -t, respectively. The following example shows how to create a geofence surrounding the address 4200 Six Forks Rd with a radius of 50 meters.

$ relay geofence:create --name=Headquarters --radius=50 --address="4200 Six Forks Rd"

Keep in mind that your geofences cannot overlap. If you create a geofence that already exists on your Dash, or try to create a geofence that overlaps with an existing one, you will get the error message Error: This geofence overlaps with Headquarters. Please pick a new location for your geofence..

After creating your geofence, you can check if it was added successfully by listing out all of the geofences associated with your account.

$ relay geofence list
=== Configured geofence

 ID                     Name         Radius Address           Coordinates                   
 ────────────────────── ──────────── ────── ───────────────── ───────────────────────────── 
 lsmBdoYG4TMOYSbGxfTjjB Headquarters 50     4200 Six Forks Rd 35.8360182,-78.63928709999999

Your geofence should now also appear in the Geofence Admin section on your Dash.

Great! Now that you know how to create a geofence, lets talk about how to use your geofences to create a workflow using the Relay API.

Creating a Geofence Workflow

Now that you have created your geofence, you are ready to create a workflow that is triggered by entering or exiting the geofence. To do this, we will use the relay workflow create geofence command in the CLI. To get the usage on how to create a workflow with this command, can enter relay workflow create geofence --help into the command line.

$ relay workflow create geofence --help
Create or update a workflow triggered by geofence transition

USAGE
  $ relay workflow:create:geofence -n <value> -u <value> --trigger enter|exit --id <value> [-N] [-i <value> | -A] [-t] [-e] [-a <value>] [-b <value>] [-r <value>]

FLAGS
  -n, --name=<value>                  (required) Name of the workflow
  -u, --uri=<value>                   (required) WebSocket URI workflow can be accessed
  --id=<value>                        (required) Geofence ID
  --trigger=<option>                  (required) [default: enter] Transition trigger for the specified geofence
                                      <options: enter|exit>
  -A, --install-all                   Enable rule to install workflow on all device and users on the account
  -N, --dry-run
  -a, --arg=<value>...                String name/value pair workflow arg
  -b, --boolean=arg1=[true|false]...  Boolean name/value pair workflow arg
  -e, --hidden                        Hide channel from originating device
  -i, --install=<value>...            device / user ID to install workflow on
  -r, --number=arg1=100.0...          Number name/value pair workflow arg
  -t, --[no-]transient                Allow workflow to run in the background; otherwise terminate workflow

DESCRIPTION
  Create or update a workflow triggered by geofence transition

This command requires you to pass in the ID of the geofence that you would like to create the workflow around, whether you would like the workflow to be triggered by a device entering or exiting the geofence, and the usual name and URN specifications. For example, lets say you want to create a workflow that is triggered by any of your devices exiting the geofence that we just created above. You would enter the following into the command line:

relay workflow:create:geofence --name="geofence example" --trigger=exit --id=lsmBdoYG4TMOYSbGxfTjjB --uri="wss://myserver.myhost.com/workflow_name" --install-all

Notice that we used the same ID that was associated "Headquarters" in the "ID" section after using the relay geofence list command. Also note that we installed the workflow on all of the devices on our account using the --install-all flag, but you can install the workflow on any particular devices, like how you would when registering any other workflow. Now we are ready to test out our geofence trigger! After exiting the 50 meter geofence surrounding the address 4200 Six Forks Rd, it will trigger a workflow on that device. Feel free to try this out on any of the sample workflows located on Relay's github in any of the supported languages.

Indoor Position Triggers

Creating an Indoor Location

To create an indoor location, you'll need some Relay beacons. These beacons allow you to locate where your devices are in a building, even down to what floor and room they are in. The beacons work by periodically broadcasting out their MAC address. When the Relay device does a Bluetooth scan and sees the MAC address of the strongest beacon signal, the device knows it is near that beacon and thus in that room.

The following is a video that walks you through how to create a "Room" with a beacon on the Relay Dash. There is also a set of steps underneath the video, if you would prefer to follow along that way.

On the Relay Dash, you should see a section called "Location". Click on that section.
After clicking on "Location", you should see a list of indoor/outdoor locations, location history, geofence and building admin tools, and beacons. Since we want to set up a new location, we will need to click on "Building Admin".
Once you are in "Building Admin", you should see a button labeled "Create Building". If you don't already have a building set up on the Dash, click on the "Create Building" button. However, if you have already created a building, you can skip to step 5.
After clicking on "Create Building", you will be prompted to enter in a name for your building. Enter in the name and hit "Submit". Dash will tell you that the building has been created successfully.
Now, you should see a button that says "Create Floor". If you don't see the "Create Floor" button, just navigate back to the "Building Admin", and click on the name of the building you just made. If you have already created a floor, you can skip to step 7. Else, hit the "Create Floor" button.
Now you will be prompted to enter in a name for your floor, such as "1st Floor". Enter in a name and click "Submit".
In your building, you should now see the name of the floor you just created. Click on the name of the floor. If you just created the floor, it should say "No rooms created yet".
Within the floor, you should see a button on the left labeled "Create Room". If you have already created a room, skip to step 10. Else, click on that button.
As before, you will be prompted to enter in a name for your room. Give your room a name and click "Submit".
Now, on the floor, you should see the room that you just created. Under the room you should see "No configured beacons". This is where your beacons come in. Click on the arrow beside the room name.
Open up your beacon and pull out the blue tab, then close the beacon again.
Back on the Dash, you should see a button to the left that says "Add Beacons". Click on that.
You are now prompted to enter in the last four characters of the beacon MAC address. Turn the beacon over to the bottom, so that the Relay logo is now facing upwards. On the side with a QR code you should see the MAC address. Enter in the last four digits of the MAC address and click "Submit".
Now, you should see your beacon show up in the room you have just created! It may take a few minutes for the beacon to send out its first "ping". Once the beacon is working and sends out a "ping", it should say that your device is in the room that you just created under the "Indoor Locations" section on Dash.

Note, that in order to have a positions workflow working, you need at least 2 beacons for testing purposes. If you have only one beacon and want to test a workflow that is triggered when a device exits a room, the dashboard will only know if the device exited a room if it is now in a new room. So, when you move your device far away from the beacon, the dashboard will no longer have an indoor location for the device, so it will not really know if it exited the room or not; it will only know that the device's indoor location is no longer known.

So, to be able to test your workflows, repeat steps 8 through 14 so that you create a new room with a new beacon. You can even create a new floor with a new room and beacon if you prefer. You just need to register 2 beacons associated with 2 different locations. Once your beacons are set up, you should see that your device's indoor location is in the room that it is the closest to.

Now that you have successfully created a building with beacons, you are ready to create a positions workflow.

Creating a Position Workflow

After adding all of your rooms and their beacons on the Relay Dash, you can use the Relay CLI to create a workflow that is triggered by a device moving from one room to another.

You can see all of the venues, or buildings, that you created on the Relay Dash by entering the relay venues command onto the command line. Here, we created a building named "Office" on the Relay Dash beforehand. Copy the venue ID that shows up beside your building, you're going to need it to get the different rooms in that building.

$ relay venues
 ID                     Name   
 ────────────────────── ────── 
 m1GCyfiANmsymG7mcMQMrD office

Now that you have the venue's ID, you can get the different rooms, or positions, that are within the venue using the relay positions command. The positions command takes in one flag, -v, which is the ID of the venue.

$ relay positions -v m1GCyfiANmsymG7mcMQMrD
 ID                        Name               
 ───────────────────────── ────────────────── 
 QNaWZg4oS0O5IiAz1Dhn8B    3rd floor > breakroom 
 WH9C4Tt39C8F9AdZsOhE0R1lD 3rd floor > kitchen

Beside the name of each position, you should see their corresponding IDs. Copy the ID of the position that you would like to create your positions trigger off of. Now that you have the ID of the position, you can create a position workflow. To get the usage on creating a positions workflow, you can enter in the relay workflow create position --help command.

$ relay workflow create position --help
Create or update a workflow triggered by a position transition

USAGE
  $ relay workflow:create:position -n <value> -u <value> --trigger entry|exit --id <value> [-N] [-i <value> | -A] [-t] [-e] [-a <value>] [-b <value>] [-r <value>]

FLAGS
  -n, --name=<value>                  (required) Name of the workflow
  -u, --uri=<value>                   (required) WebSocket URI workflow can be accessed
  --id=<value>                        (required) Position ID
  --trigger=<option>                  (required) [default: entry] Transition trigger for the specified position
                                      <options: entry|exit>
  -A, --install-all                   Enable rule to install workflow on all device and users on the account
  -N, --dry-run
  -a, --arg=<value>...                String name/value pair workflow arg
  -b, --boolean=arg1=[true|false]...  Boolean name/value pair workflow arg
  -e, --hidden                        Hide channel from originating device
  -i, --install=<value>...            device / user ID to install workflow on
  -r, --number=arg1=100.0...          Number name/value pair workflow arg
  -t, --[no-]transient                Allow workflow to run in the background; otherwise terminate workflow

DESCRIPTION
  Create or update a workflow triggered by a position transition

This command requires you to pass in the ID of the position that you would like to create the workflow around, whether you would like the workflow to be triggered by a device entering or exiting the position, and the usual name and URN specifications. For example, lets say you want to create a workflow that is triggered by any of your devices entering the breakroom, which is one of the positions we had listed above. You would enter the following into the command line:

relay workflow:create:position --trigger=entry --id=G7ktCly6Jpg3ImvKQtqA2A --name="position example" --uri='wss://myserver.myhost.com/workflow_name' --install-all

Notice that we used the same ID that was associated in the "ID" section for the breakroom when we listed out the positions. Also note that we installed the workflow on all of the devices on our account using the --install-all flag, but you can install the workflow on any particular devices, like you would when registering any other workflow. Now we are ready to test out our position trigger! After entering the breakroom, it will trigger a workflow on that device. Feel free to try this out on any of the sample workflows located on Relay's github in any of the supported languages.

Now you know how to create a trigger based on a device's location!