Skip to content

ExoSense Insights Schema

Last Update: 2022-01-18


This schema defines the interface for Exosite's streaming 'Insight Interface' which provides the ability to build logical operations and analytics in the form of transform, rule, and action functions that can be used in the ExoSense data pipeline to handle digital asset signal data.

This information specifies the required functions and data scheme for building an External Insight. External refers to a seperate service that supports the required endpoints as defined below. This schema information may also be used to understand the data flow and objects for the ExoSense Inline Insights.

Insight modules contain one or many functions (one or multiple types). Each function provides it's own informaiton - in this way the interace is dynamic for loading into the ExoSense user interface.

A new Insight module is defined by a swagger file and published as a ExoSense Insight service in Exosite's IoT Marketplace.

Download an example swagger template file

Reference & Definitions

Term Definition
Insight Module of analytic Functions to perform calculations on Asset Signals.
Function Member of an Insight module.
Datapoint Single instance of a Signal Data stream, with a timestamp.
Linkage ExoSense Pipeline term for non-Signal blocks on the Asset Config page of the UI.

API Paths

There are three required paths that an Insight must support:

Optionally, an Insight can support the following paths:

Insight Module Info

The GET /info endpoint serves to retrieve information about an Insight and is expected to return the following payload keys:

Key Type Required Description
name string true The friendly name for the Insight, which will be presented in the ExoSense UI.
description string true High-level description of the Insight.
group_id_required boolean true Whether or not the result of POST /insights should be filtered based on a user-provided Group ID.
wants_lifecycle_events boolean false Whether or not the Insight requires lifecycle events to be sent.


  "name": "Acme Co. Insight",
  "group_id_required": true,
  "description": "Insight exposing algorithms to predict the life of your Acme product.",
  "wants_lifecycle_events": true

Function List

The POST /insights endpoint returns a list of applicable Functions exposed by the Insight and information about those Functions.

The request body can have the following keys:

Key Type Required Description
group_id string false Which group of Functions to return.
limit integer false How many Functions to return.
offset integer false Offset or paginate returned Functions.


  "group_id": "CH00123",
  "limit": 4,
  "offset": 0

The response body should have the following keys:

Key Type Required Description
total integer true The number of Functions in the group.
count integer true The number of Functions returned.
insights array true Array of Function Info blocks, which will be presented by name in the ExoSense UI.

See Insight Function Info


  "total": 7,
  "count": 4,
  "insights": [
    { "name": "Function1", ... },
    { "name": "Function2", ... },
    { "name": "Function3", ... },
    { "name": "Function4", ... }

Processing Signal Data

The POST /process endpoint will be called with the Signal Data as specified in the section above. What the Insight Function does with that payload is up to its author, but it is expected that this endpoint will return an array of arrays.

The inner array is for output Signal Datapoints for a specific Outlet. In the future, the outer array will be used to hold different Outlets' inner arrays.

A Function that returns nothing will respond with an empty array of arrays: [[]].

Specific Function

The GET /insight/{function_id} endpoint returns a single Function Info block corresponding to its member Function with the same function_id.

Lifecycle Events

The POST /lifecycle endpoint is optional and serves to inform the Insight about creation and deletion events.

This endpoint will receive a body with the following keys:

Key Type Description
event string "create" or "delete"
id string The Linkage ID for this specific instance of the Insight Function
args object The same args object as sent to the /process endpoint

Core Payload Objects

The two primary payloads encountered with Insights, the Insight Function Info and Signal Data objects, are described here in detail.

Insight Function Info

Insight Function Info is used to generate the ExoSense UI when adding a Function to a Signal and to inform the ExoSense Pipeline on what information the Function needs to calculate a result.

The object has the following keys:

Key Type Required Description
id string true The unique ID used for this Function. Internal to the Insight Module.
name string true The friendly name for this Function.
description string true The description of this Function.
type string true The type (transform, rule, or action) of this Function. Default is transform, if not provided.
inlets array true Specify the Input Signals.
outlets object true Specify the Output Signal.
constants array false Specify parameters for users to provide when adding this Function.


Insight Functions can be one of three types: transform, rule, or action. Their classification into one of these buckets determines how ExoSense and the Pipeline treats them. The default type is trasnform if not specified.


The inlets key is an array of Inlet objects, each of which can have the following keys:

Key Type Required Description
tag string true Tag to use to identify the Inlet. Shows up in Signal Datapoint tags.
name string true Friendly name for the Inlet.
description string true Useful description for this Inlet.
data_type string false Optionally require specific data_type.
data_unit string false Optionally require specific data_unit.
primitive_type string false Optionally require specific primitive_type.


The outlets key is an array of Outlet objects, which can have the following keys:

Key Type Required Description
data_type string true Specify the output data_type.
data_unit string false Optionally specify the output data_unit.
name string true Friendly name for the Outlet.
description string true Useful description for this Outlet.
suggested_name string false A suggestion for what to name signals that get created for this outlet.


Constants inform the ExoSense UI about parameters that users will supply when they add the Function to one or more Signals. Each Constant in the constants array can have the following properties:

Key Type Required Description
name string true Name for this constant. Users will see this in the UI.
type string true The type of constant: value can be "string" or "number".
description string false Helpful description of this constant.
default -- false Default value if left blank. Can be a string or a number, depending on type.
enum array false Array of allowed values.
enum_presented array false Array of meta names for the enum arrary that will be shown in the UI.
maximum number false For number type, largest the value can be.
minimum number false For number type, smallest the value can be.
multiple boolean false Default False. When set to true, allows constant to be added multiple times.


  "constants": [
      "name": "days",
      "type": "number",
      "description": "The number of previous days to analyze",
      "default": 1,
      "maximum": 7,
      "minimum": 1
      "name": "aggregation_function",
      "type": "string",
      "description": "The aggregation function to use",
      "enum": ["avg", "max", "min", "count", "sum"],
      "default": "avg"

Signal Data

When an Insight Function receives Signal Data, the object the Function receives has three to five top-level keys:

Key Type Required Description
id string true The ID of the Linkage this Signal Datapoint was sent from.
data array true List of Signal Datapoints.
args object true Information about the specific Insight including values for user-provided Constants.


The ID is the specific instance of the Insight Function. If an Asset has four signals—A, B, C, and D—and they are Inlets to a Transform Function like the following:

A --\
     |-- Transform -- AB
B --/

C --\
     |-- Transform -- CD
D --/

Then the first and second Transforms will have different IDs. In the ExoSense Pipeline, these instances are known as Linkages, and the ID is the Linkage ID.

The ID field is critical for multiple-Inlet Insight Functions, as that Function will receive the Inlet Signal Datapoints separately and will need to keep track of their relationships.


Signal Data passed around ExoSense to and from an Insight has a common schema.

Signal Data objects have the following keys:

Key Type Required Description
origin string true Publishing ID.
generated string true Publishing ID that created this Signal Datapoint.
ts integer true Unix timestamp in microseconds of when the data originated in Murano.
value -- true Value for this instance of data.
tags object false Tags helpful in identifying the original source of the data.
gts integer false Unix timestamp in microseconds of when this Signal Datapoint was generated.
ttl integer false Time to live for Signal Datapoint.


Tags include general info about the Signal Datapoint as well as inlet, which ties an individual Datapoint back to its Inlet using the Inlet tag.

  "tags": {
    "resource": "data_in",
    "pid": $product_id,
    "metric": $data_in_key,
    "identity": $device_identity,
    "data_unit": $data_unit,
    "data_type": $data_type,
    "primitive_type": $primitive_type,
    "inlet": $inlet_tag


Origin describes the source of the Datapoint. Frequently this source is a Device Channel, but could also be from a Signal injection, in which case the Origin will be the UUID of the Signal.

The most common origin is in the following format:


For most situations in ExoSense, the <RESOURCE_ID> is data_in.


The Args block in Signal Data contains the following keys:

Key Type Required Description
function_id string true ID of the Function.
group_id string false Group ID if one exists.
constants object false Constant parameters.

Function Type Information


Transforms are used to convert, evaluate, and process one or more streaming signals for purposes of data conversion or analytics. The outcome is one or more signals that can be used for visualization, further analytics, rules, and reporting.

Transform function specifics

Transform functions use the super set of the Insight interface functionality documented in this schema.


The use case for rule type functions is to evaluate signal data and determine if a condition status has changed, which the most basic examples are for a value to be equal or not equal to a constant value or if a numeric value has crossed a threshold.

Rule function specifics

Example of Rule Insight Function Info

    "name": "SomeRule",
    "description": "SomeRule description",
    "type": "rule",
    "constants": [
        "name": "const1",
        "description": "desc for const1",
        "type": "string"
        "name": "level",
        "description": "The alert level if the substring is found",
        "type": "number",
        "enum": [1, 2, 3, 4],
        "default": 1
    "outlets": {
      "primitive_type": "JSON",
      "data_type": "STATUS",

Status Data Type

The output of a rule insight is a JSON string.

Key Type Required Description
level integer true Alert severity
type string false
value string false

Status Levels

Level Value
Normal 0
Info 1
Warning 2
Critical 3
Error 4

User defined addendum messages

The notifications and rule event logs may include an extension message that can be added by an end user. To enable this per Rule function, the function must include the following reserved named constants.

    name: "messageMatch",
    description: "Extra details for when value does match",
    type: "string",
    name: "messageElse",
    description: "Extra details for when value does not match",
    type: "string",
    default: "The value didn't match",

Refer to Constants for details on properties.


The use case for action type functions is to send a rule status change value(a condition event) to a service that will consume and use that information to take some action such as send a notification, create a maintenance ticket, or register the condition for historical purposes.

Action function specifics

  • The value for type in the Insight Function Info is action.
  • Actions are used with rules, meaning an action subscribes to the output of a Rule's Status signal. Actions only support one inlet, which the type is required to be STATUS. (Signal -> Rule -> Status Signal -> Action)
  • Action functions have no outlet.

Example Action Insight Function Info

    "name": "Some Action",
    "description": "Some Action description",
    "type": "action",
    "constants": [
        "name": "const1",
        "description": "desc for const1",
        "type": "string"
    "inlets": [
        "primitive_type": "JSON",
        "data_type": "STATUS",

Change log

  • Depreceate and remove of Callback (cbi) functionality
  • Add information for enum_presented and multiple key options for Constants.
  • Deprecate and full removal of support for including signal history in the /process operation. Recommendation: Store history and/or state in the external insight service.
  • Adding 'action' function type support
  • Move content sections around with api routes first, adding overview, and table reformating.
  • New document to detail insight transform and rule interface with ExoSense

Last update: December 1, 2021
Back to top