1. Hologram
  2. Hologram Cloud and developer tools
  3. Hologram Cloud

Hologram Routes

Routes in the Hologram ecosystem provide convenient methods to trigger actions (data storage, Email, 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.

Limited access functionality
Routes functionality is limited to certain legacy accounts. For more information, please reach out to our sales team.

Route components

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

1) The topic/topics that the route acts upon. A route can act on the presence or absence of these selected topics.

Note: A route is triggered by any of the selected topics. In other words, a route subscribes to the union (OR) of its list of topics.

2) Operator Apps that are chained together to achieve various effects like modifying message data or listening for the absence of the selected topics.

3) Action Apps that perform some specific effect, such as communication (email, Slack, etc.), integrations with other services (IFTTT, Slack, etc), or storage (AWS bucket etc.).

routes.png

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: .

Example 1: Including message data in an Email action app

The above example uses the <<decdata>> variable which refers to the “decoded data." Data is usually encoded in Base64 when being transmitted. However, the email body will be populated with the actual message data before the email is sent to you.

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.

Note: Variables are not available for heartbeat because of the nature of the alert (triggers on a lack of message).

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":
}

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

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

App types

The following are the details of the current app integrations.

Note: Please contact success@hologram.io for additional support or if there is a specific app integration you are looking for.

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.

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.

Note: Variables are not available for heartbeat because of the nature of the alert (triggers on a lack of message).

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.

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. 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.

AT&T M2X

M2X is a platform by AT&T for logging and streaming data from device sources to destinations in the cloud. M2X organizes data within devices, where each device can have one or more streams of numerical or text data. Hologram’s M2X integration forwards messages from Hologram devices to a stream on a corresponding M2X device.

In order for Hologram to authenticate to your M2X account, you must provide an M2X API master key. To find your master key, access your account settings by clicking on your account name at the top-right, then selecting Account Settings from the dropdown menu. Copy the automatically created master key from this page:

Create a Hologram route, and select AT&T M2X as the action app. The M2X route has four parameters:

  • API Key – The master API key found on the M2X account settings page.
  • Device ID – The ID of the M2X Device to publish the data to.
  • Stream Name – The name of the stream to publish the message to. Default is hologram_default.
  • Data Payload – Data that will be pushed to M2X. Accepts variables.

Device and Stream Mapping

Hologram relies on M2X’s Device Serial identifier for mapping between Hologram and M2X devices. Hologram routes messages from a Hologram device with ID 12345 to the M2X device with serial konekt_12345. If an M2X device with this serial doesn’t exist, Hologram will automatically create it.

If the destination device doesn’t have a stream with the given stream name, Hologram will create a non-numeric stream. This allows you to store arbitrary text payloads in M2X. However, if you pre-create a numeric stream with the given name, M2X will attempt to parse the data payload as a number. This can be useful for devices sending numeric sensor readings to the Hologram Cloud.

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.

Note: 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 URL destination–you can use it when the destination application expects an HTTP request in a specific format.

When sending JSON content, make sure to select the Send JSON Content Type checkbox. This sets the HTTP Content-Type header so that the receiving application knows to interpret the body as JSON.

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>>

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

Custom Webhook URL

Note: 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.

Was this article helpful?
0 out of 0 found this helpful