Overview

Routes in the Hologram ecosystem provide convenient methods to trigger actions (data storage, Email, SMS, webhooks, and many more), which are triggered by the presence or even absence of a device message’s topic.

Routes can be configured on the Hologram Dashboard or using the REST API.

Route components

A route consists of 3 parts, which follow an ingress/egress pattern:

  1. The topic/topics that triggers the route. Every message that comes in from one of your devices will be scanned for the selected topics and then trigger the route if it matches. If you have more than one topic, you can choose whether the route should trigger a message matching any of the topics (boolean OR) or all of the topics (boolean AND).
Cloud messaging form
  1. Operator Apps that are chained together to achieve various effects like modifying message data or listening for the absence of the selected topics.
Cloud messaging form
  1. Action Apps that perform some specific effect, such as communication (email, sms etc.), integrations with other services (IFTTT, Slack, etc), or storage (AWS bucket etc.).
Cloud messaging form

Accessing data

Most apps can include the data and meta-data from a message. To access this data when configuring the app, you can use our basic templating syntax and variables. They are accessed in the following manner:

<<foobar>></foobar>

Example 1: Including message data in an email action app

Cloud messaging form

The above example uses the <<decdata>> variable which refers to the “decoded data”, (usually encoded in Base64 when being transmitted.) This will be populated with the actual message data before the email is sent to you.</decdata>

Available variables

  • received: ISO8601-formatted UTC timestamp when the Data Engine received the message
  • tags: JSON-formatted array of topics belonging to the message
  • device.name: Human-readable name of the device
  • device.id: Integer ID of the device
  • data: Base64-encoded representation of the data payload
  • decdata: Decoded (raw) representation of the data payload. This may not be valid if the message has a non-text payload.
  • decdata.fieldName: Access a JSON field in the data payload, for example, decdata.voltage. Results in an empty string if the payload isn’t valid JSON or if the field isn’t present.

NOTE: If the decoded data(decdata) is JSON, you can access each field with dot notation: <<decdata.foobar>></decdata.foobar>

Example 2: Formatting message data for a webhook POST body

One common use case is to construct a JSON body for a webhook app. For example, the body field could be:

{
 "temperature": <<decdata.temperature>>,</decdata.temperature>
 "source_device": "<<device_id>>",</device_id>
 "datetime": "<<received>>"</received>
}

Which would result in a POST request body sent to your webhook with the following:

{
 "temperature": 23.5,
 "source_device": "12345",
 "datetime": "2016-09-27T18:53:09.302915"
}

App types

The following are the details of the current app integrations.

NOTE: We are constantly adding to this list and are open to integrate with any service you may need.

Modifier

The Modifier app transforms the format of each message using templates. This can be useful for including message metadata in the payload itself, or for decoupling the device’s message format from the format that gets sent to downstream services.

Modifier routing rule

Heartbeat

The Heartbeat app emits an event if it does not receive data from its subscribed topics for a period of time. This can be useful to generate alerts when devices go offline.

As an example, let’s create an alert to send an email when the device with ID 12345 fails to write a message for 15 minutes.

Configuration for Heartbeat route

Email

Sends an email with the specified subject and body to one or more recipients.

Parameters:

  • Recipients: Comma-separated list of email addresses
  • Subject: Subject line for the email
  • Message: Template for the body of the message.
Email route form

Slack

Slack is a group messaging application that has great support for integrating with external services. Hologram’s Slack integration posts matching messages to a configurable Slack channel.

First, generate a Slack webhook URL by visiting the Incoming Webhooks page. Make sure you’re signed into the correct Slack team, then pick which channel to route Hologram messages to. Click the Add Incoming Webhooks integration button to generate a new integration URL. From this page you can also change the icon and name that Slack displays when Hologram posts a message.

Create a Hologram route select Slack as the action app. The Slack route has three parameters:

  • Slack Webhook URL: The URL you generated above. It should begin with https://hooks.slack.com/.
  • Slack Channel: Optionally override the channel to post to. If left blank, Slack defaults to the channel specified in the Incoming Webhook configuration.
  • Message: The message that will be posted to Slack. This field supports the template format and defaults to <<decdata>>. If you set it to be blank, the message will be two lines: the first line is the message payload in text format, the second line is a JSON representation of the message, including metadata such as received time and message topics.</decdata>

Custom integrations with webhooks

If you need to send messages to an app or service that Hologram doesn’t natively support, you may use one of the Webhook app types to generate an HTTP POST request to any URL. This is useful for integrating with your own custom web app.

TIP: To verify the contents and format of webhooks, it can be useful to send them to an HTTP request inspector such as RequestBin. Use your generated RequestBin URL as the destination URL in the route config, then refresh the RequestBin inspector page after you send a message to the Data Engine. It should then display the HTTP headers and content of the corresponding webhook.

Advanced webhook builder

The Advanced Webhook Builder action app sends HTTP POST requests that you can customize via templates. This rule is more flexible than the Custom Webhook URLdestination–you can use it when the destination application expects an HTTP request in a specific format.

When sending JSON content, make sure to include the correct content-type header so that your application can process it correctly. You can do this by specifying a Content-Typeheader with a value of application/json

content type header example

Some webhooks may expect a different content type. Consult the appropriate documentation for the service that you are using.

It’s also possible to include template variables in the destination URL. This is useful for sending data as URL query string parameters. For example, the URL

https://example.com/webhook?device=<<device_id>>&data=<<data>></data></device_id>

will send the device_id and data variables as query string parameters.

Custom webhook URL

The Custom Webhook URL app has been deprecated. New applications should use the Advanced Webhook Builder instead.

The Custom Webhook URL destination sends a form-urlencoded HTTP POST request with a message’s data payload and metadata in a pre-defined format. The request includes a payload field which contains a JSON representation of the message. The payload’s format is as follows:

{
 "received": "2016-09-27T18:53:09.302915",
 "authtype": "psk",
 "tags": ["TOPIC1", "_DEVICE_12345_"],
 "device_name": "My Device",
 "errorcode": 0,
 "timestamp": "0",
 "data": "SGVsbG8sIHdvcmxkIQo=",
 "device_id": 12345
}

The data field contains a base64-encoded representation of the data payload.

When developing an application that accepts webhooks, it’s important to have a reliable way to check that an HTTP request is coming from the intended source. The Custom Webhook URL destination lets you specify a key to be included in every webhook that gets sent. Then, your application can check for the presence of this key to ensure that the request indeed originated from Hologram. The request body includes this string as a field called key, alongside the payload.