Groups

When dealing with multiple devices at one time, you need a way to address that group. That's where the groups API comes in. In this section, we will discuss how to use the different functions pertaining to groups and how to create a URN for a group that you could use as a target parameter.

📘
URN type for Groups
Because the group utilities described below do not need to interact with a device, there is no target parameter to the group utility methods, thus no URN parameter is needed.

Group are manually constructed in Dash, where you can pick a name for the group and then manually add each member to the group as desired. Once the group is defined in Dash, then you can use these functions on those groups.

Constructing Group URNs

Some of the utility methods that Relay has available for groups are constructing a group URN, and parsing out a group's name from a group URN.

We can access functions that deal with URNs by importing the Uri module. Uri contains helpful functions that create a group URN from a group name. Uri also can work in reverse, where it gets a group name or device from a URN. For example, to create a URN for a group, we can use the groupName() function:

import { relay, Event, createWorkflow, Uri  } from '@relaypro/sdk'

...

const groupWorkflow = createWorkflow(workflow => {
    workflow.on(Event.START, async (event) => {
        const { trigger: { args: { source_uri } } } = event
        // Create a URN based off of a group name.  Here, the groupName function returns
        // a string that represents the URN of the Engineering group
        const groupUrn = Uri.groupName('Engineering')
    })
})
...

# group utilities are in the top-level class instead of Uri
@my_workflow.on_start
async def start_handler(workflow, trigger):
		# Create a URN based off of a group name.  Here, the groupName function returns
  	# a string that represents the URN of the Engineering group
    groupUrn = relay.group_name('Engineering')

using RelayDotNet;
...
public override async void OnStart(IDictionary<string, object> dictionary)
{
  // Create a URN based off of a group name.  Here, the groupName function returns
  // a string that represents the URN of the Engineering group
	string groupUrn = RelayUri.GroupName('Engineering');
}

import com.relaypro.sdk.RelayUri;
...
@Override
public void onStart(Relay relay, StartEvent startEvent) {
  super.onStart(relay, startEvent);
  // Create a URN based off of a group name.  Here, the groupName function returns
  // a string that represents the URN of the Engineering group
	String groupUrn = RelayUri.groupName("Engineering");
}

import (
  "relay-go/pkg/sdk"
  ...
)

api.OnStart(func(startEvent sdk.StartEvent) {
  groupUrn := sdk.GroupName("Engineering")
})

The above function returns urn:relay-resource:name:group:Engineering.

Getting a Group Name from URN

To get the simple name of a group from a group URN, you can use the parseGroupName() function. There is a similar function parseDeviceName() that will take the URN of a device and return the name of that device. For example:

// This gets the group name from the URN.  Here, it will return 'Engineering'
Uri.parseGroupName('urn:relay-resource:name:group:Engineering')

// This gets the name of the device from the URN.  Here it will return 'Abby'
Uri.parseDeviceName('urn:relay-resource:name:interaction:group?device=urn%3Arelay-resource%3Aname%3Adevice%3AAbby')

# This gets the group name from the URN.  Here, it will return 'Engineering'
relay.parse_group_name('urn:relay-resource:name:group:Engineering')

# This gets the name of the device from the URN.  Here it will return 'Abby'
relay.parse_device_name('urn:relay-resource:name:interaction:group?device=urn%3Arelay-resource%3Aname%3Adevice%3AAbby')

// This gets the group name from the URN.  Here, it will return 'Engineering'
RelayUri.ParseGroupName('urn:relay-resource:name:group:Engineering')

// This gets the name of the device from the URN.  Here it will return 'Abby'
RelayUri.ParseDeviceName('urn:relay-resource:name:interaction:group?device=urn%3Arelay-resource%3Aname%3Adevice%3AAbby')

// This gets the group name from the URN.  Here, it will return 'Engineering'
RelayUri.parseGroupName("urn:relay-resource:name:group:Engineering");

// This gets the name of the device from the URN.  Here it will return 'Abby'
RelayUri.parseDeviceName('urn:relay-resource:name:interaction:group?device=urn%3Arelay-resource%3Aname%3Adevice%3AAbby');

// This gets the group name from the URN.  Here, it will return 'Engineering'
sdk.ParseGroupName("urn:relay-resource:name:group:Engineering")

// This gets the name of the device from the URN.  Here it will return 'Abby'
sdk.ParseDeviceName("urn:relay-resource:name:interaction:group?device=urn%3Arelay-resource%3Aname%3Adevice%3AAbby")

Constructing different URN's or parsing out their group or device name can be useful when creating workflows with other functions in the SDK. For example, constructing a group URN would be very useful for sending notifications to a group in one invocation. Since notifications require a group URN, you would need a way to construct one based off of the name of the group that you would like to send your message to. The Uri.groupName() function enables you to create a group URN from the group name, so that you can relay a message to all of the devices in that group. To see that example, visit the Notifications section.

Other Functions for Groups

There are other functions that support constructing a group URN or parsing out different information from the URN. To view some of these other functions, visit the Utilities section.

📘URN type for Groups

Constructing Group URNs

Getting a Group Name from URN

Other Functions for Groups

📘
URN type for Groups