Home

Helper Methods

Suggest Edits

The SDK includes helper methods/functions that are available to use throughout your workflows. Here we discuss what these are.

Utilities included in the SDK

  • isInteractionUri: returns true if the URN passed into the function is an interaction URN

  • isRelayUri: returns true if the URN passed into the function is a Relay URN

  • makeTargetUris: takes a target as the parameter and returns a target URI.

  • parseDeviceName: parses the name of a device out of the URN that is passed in

  • parseDeviceId: parses the ID of the device out of the URN that is passed in

  • parseGroupName: parses the group name out of the URN that is passed in

  • parseGroupId: parses the ID of the group out of the URN that is passed in

  • groupId: constructs and returns a URN from a group ID as a string

  • groupName: constructs and returns a URN from a group name as a string

  • groupMember: takes a group member and device ID as strings as parameters and creates and returns a URN

  • deviceId: takes a device ID as a string as a parameter and creates and returns a URN

  • deviceName: takes a device name as a string as the parameter and creates and returns a URN

  • allDevicesWithStatus: takes the name of the interaction and the state of the interaction lifecycle as parameters and returns all of the devices in that interaction and state of lifecycle as a string

  • allDevices: returns all of the devices as a string associated with the account

  • genericOriginator: returns the URN of the server as a string

Using the Utilities

All of these utilities are included in the SDK upon installation. In order to access these utilities in your workflow, you need to import the files that they are defined in. These utilities are here to help you when creating your workflows. For example, many of the utilities assist in creating URNs. Since we need to have target, source, and interaction URNs, it is helpful to have a way to construct them without having to create each of these URNs by hand.

These utilities have many other capabilities besides creating URNs, such as checking if a URN is a a Relay or interaction URN, or parsing out a group or device name from a URN. You can also retrieve all of the devices associated with your account, or specify a single device that you need to retrieve. These functions allow you to create workflows that are straightforward and efficient. You can learn more about these functions in the API.

Special Utilities

There are a couple utilities that are unique, in that they can run outside of your workflow server, on any network-connected system you'd like. The goal of these utilities are to handle the network calls and authentication for you. Yes, this would mean using the Relay SDK on a machine that is not your workflow server.

  • triggerWorkflow: creates and sends an authenticated HTTP trigger to the Relay server to start a registered workflow. This trigger can include parameters as strings that can get passed into the workflow. This is intended to start a workflow remotely, from whatever network-connected system you want. We expect that this would be used in third-party systems, as an external standards-based way to start a workflow. For example, if you have a third-party Sales system, upon a new sale you could configure your Sales system to send an HTTP trigger to the Relay server to start a workflow that might do something like speak out information about that new sale on Relay devices. If desired, you could also use this utility within a workflow to trigger a separate workflow. If you aren't familiar with Relay's HTTP Trigger, follow the link to learn more.

  • fetchDevice: takes a device ID as a parameter, make an authenticated HTTP request, and returns a lot of device info, more than you can get via the API. See the linked page for a description of what gets returned.

Updated over 1 year ago