Skip to main content
Limited access: Routes access is limited to certain legacy contracted organizations. If you are having issues with routes, please reach out to support.
Routes in the Hologram ecosystem provide convenient methods to trigger actions — data storage, Email, webhooks, and many more — by the presence or even absence of topics attached to a device message. Routes can be configured under the Routes section in the main menu.

​
Route components

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

Selecting topics for a route

The topic/topics that the route acts upon. A route can act on the presence or absence of these selected topics. Topics can also be combined with with AND or OR logic.
Selecting topics for a route
2

Operator apps chain example

Operator Apps that are chained together to achieve various effects like modifying message data or listening for the absence of the selected topics.
Operator apps chain example
3

Action apps overview

Action Apps that notify other services of the triggered event. Notification methods include email, SMS, webhooks, or Slack.
Action apps overview

​
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.
Note: A route is triggered by any of the selected topics (logical OR).

​
Example: Include message data in an Email action app

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

​
Available variables

  • <<received>> - ISO8601 UTC timestamp when Data Engine received the message
  • <<tags>> - Array of topics for the message
  • <<device.name>> - Human-readable device name
  • <<device.id>> - Integer device ID
  • <<data>> - Base64-encoded payload
  • <<decdata>> - Decoded payload (if text)
  • <<decdata.fieldName>> - Access a JSON field if the payload is JSON (e.g. <<decdata.voltage>>)
Warning: Variables are not available for heartbeat triggers.

​
Example: Include message data in a webhook route

One common use case is to construct a JSON body for a webhook route. For example, the body field could be: 
{
  "temperature": <<decdata.temperature>>,
  "source_device": "<<device.id>>",
  "datetime": "<<received>>",
}
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

​
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 app example

​
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 that receives regular TCP communications every 10 minutes fails to write a message for 15 minutes.
Heartbeat rule configuration
Warning: Variables are not available for heartbeats because the alert triggers when no message has been received, and there is no message data available.

​
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 app parameters

​
Custom webhook integrations

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.

​
SMS

Sends an SMS with the specified message to one or more recipients. Parameters:
  • Recipients - Comma-separated list of phone numbers.
  • Message - Template for the body of the message.

​
Deprecated app types

The following app types are no longer supported and will be removed in a future release:
  • Slack legacy webhooks
  • IFTTT webhooks
  • Losant webhooks
  • Losant device send state
  • Amazon S3 routing