Cloud Services Router User's Guide (Beta)

Overview

Integrations often involve complex (high-level) APIs and protocols to be implemented on client devices, which also limits the functionality a device can support to only that which has been implemented in firmware.

Our Cloud Services Router liberates devices from the responsibility of implementing application-specific APIs and protocols, and liberates data from the confines of firmware capability limitations, by offering a Cloud-based message queue and Cloud-based protocol translation platform. Our Cloud Services Router enables one-click integrations as well as custom integrations with your own web apps (via webhook).

 

CSR Data Input Concepts

Data Injection Points

Our Cloud Services Router supports multiple data input mechanisms and protocols for compatibility with a variety of data sources and devices. For more information, please refer to the Cloud Services Router API Documentation containing technical implementation details geared toward developers.

 

Data Tags (Topic Channels)

Data that arrives in our Cloud Services Router is tagged with additional metadata called tags (also referred to as topics or channels). These are analogous to hashtags on social media (like Twitter) or channels/rooms on Internet chat services (like IRC). Tags are intended to provide context to data on what the data represents, where the data originated, and/or why the data was generated. Tags are the primary basis for triggering routing rules, which conditionally route data to their proper destinations.

Device-defined Tags

Device developers are encouraged to bountifully use tags to provide significant context to data being injected into our Cloud Services Router. Good data tagging improves the ability to implement new routing rules and Cloud services integrations in the future with ideally no device reconfiguring or firmware updating.

Please refer to your own device’s documentation on its use of tagging. For more information on how to tag device data for a device you are developing, please refer to the Cloud Services Router API Documentation containing technical implementation details geared toward developers.

System Tags

Certain types of data input mechanisms and protocols, as well as certain system events, can trigger automatic tagging of device data. System tags are appended to any other device data tags (if applicable), and system tag names begin with and end with two underscore (__) characters. System tag names are reserved and devices are unable to assign system tags to their own data (for integrity and security reasons).

For a complete listing of system tags that have been implemented, please refer to the System Tags Reference below.

 

Routing Data to Destination(s)

Installing Apps (Creating New Routing Rules)

In order to route device/source data from the Cloud Services Router queue to a destination of your choosing, a routing rule must be configured with conditions that match the data or its metadata. New routing rules are created by a process we refer to as installing apps (applications).

To install a new app (and configure a new routing rule), proceed to the Data Routes tab in the Device Management Portal and click the Install New App button. A dialog will appear that will ask you to define conditions that must be matched in order for data to be routed to the application and to select from a marketplace of available destination apps in order to provide convenient one-click service integrations. Data that enters the Cloud Services Router queue and that matches the routing conditions will be routed to the selected destination app according to the newly-created routing rule. Note that an app may be installed any number of times as a part of different routing rules.

If you want to route data to a URL of your own choosing (for instance, POSTing data to your own web app) you will need to customize your own webhooks. This is discussed below.

 

Defining Routing Conditions

Currently, the only type of routing conditions supported by routing rules is tag (topic/channel) subscription (matching). While creating a new routing rule, users are asked to enter one or more tags.

Tags entered as a part of a routing rule effectively subscribe the selected destination app to data marked with one or more of the supplied tags (that is, subscribe the destination app to that topic or channel). Note that entering multiple tags as a part of a routing rule is equivalent to a logical OR operation.

Configuring Custom Webhooks

While creating a new routing rule, one of the available one-click app integrations to choose from is a Custom Webhook URL (Your Own App). This app provides users with the ability to route data to a URL of their own choosing for custom web app support, and requires that a URL parameter be provided where data will be POSTed to.

 

Reference

System Tags Reference

System tags are automatically generated by our system. Note that system tags begin with and end with two underscore (__) characters.

Event Triggered System Tags More Information
A circuit-switched device originated (mobile originated) SMS is received via our long code __SMS__
__SMSDO__
Data that is injected into the CSR queue via SMS long code will contain these tags. (see also: CSR API Documentation: Injecting Data via SMS)

 

See Also

Developers: For more information about implementing our Cloud Services Router on your devices and data sources, please see the Cloud Services Router API Documentation containing technical implementation details.