Building Custom Insights¶
ExoSense supports a way to plug-in custom asset signal transforms and rules. This plug-in type service is referred to as Insights or Insight Modules. The Insight Module itself is a service that exposes the defined interfaces ExoSense requires and includes one or many functions
An Insight Module may include many functions of type transform and rule, the available functions are dynamically loaded when users go to add a new transform (shows available transform functions) or rule (shows available rule functions
End User Experience¶
End users are presented with a set of transform and rule functions in the Asset Configuration window, this information is loaded dynamically when the user goes to add a new transform or rule.
Exosite's Insight Interface Concepts¶
- The Insight functions are Streaming -- they are inserted into the data pipeline flow and process every input signals' values
- Insight functions are of type
rule. Transforms output another signal, Rules output a Status.
- At their core, Insights are not expected to be stateful; similar to other Transformations like Join and Linear Gain, they operate on the latest value of Signal data.
- For a given Join on SignalA and SignalB, each time a piece of data comes in from either of those Signals, the Join runs (and returns a joined value).
- The Join Transform uses the last seen value of any Signal not present in the data sent to the Join at any given time.
Creating your own¶
There are two paths to create your own Insight modules and functions. Either path will allow your end-users to insert these functions into their Asset configuration based on the definitions for inputs, constants, and outputs.
- Custom Inline Insights
- External Self-Hosted Insights
The ability to create, host, and use custom insights is available at specific Exosite business account and ExoSense application tiers.
ExoSense Custom Inline Insights¶
ExoSense supports building and managing custom Insight functions in the application. This is the easiest way to create your own data transformations, rules, and streaming analytics.
External Self Hosted Insights¶
Exosite Exchange Element¶
To use an externally hosted Insight Module with ExoSense, it must first be added as an element into Exosite's IoT Exchange within your Exosite Account. These elements use a Swagger definition to define the API interface.
The swagger definition for the Service is found in this repository: insight-template.yaml. Use swagger.io to view the incoming and outgoing data format.
It must use the element tag in the swagger definition as shown below for ExoSense to identify it as a service it can consume
tags: - name: insight description: Insight Module
- The Exchange Service created for an Insight defines the URL to be requested when ExoSense needs to do any of the following:
- get high-level information about the Insight
- get a list of available functions for a group, along with their required parameters
- get info about a specific function, along with its required parameters process incoming Signal data (i.e. "run the function")
The service can be hosted anywhere, including:
- Exosite's Murano Application Platform
- Amazon Web Services
- Microsoft Azure
- Google Cloud Products
- The code behind the Insight is entirely up to its creator; as long as it conforms to the Swagger definition, ExoSense will happily send and receive data from it.
- The code that makes up an Insight can be written in any language available within the chosen host.
To create and host as a custom Murano solution, use the following template which can be deployed from Exchange.
Contact support for templates to run in other infrastructure.
HTTP Web Service¶
Hosted somewhere with public endpoints
This endpoint is used to get high-level information about an Insight. The name displayed within the ExoSense UI, the Insight description, and whether or not a group_id is required are supplied via this endpoint.
This endpoint is used to get all the necessary information about a specific Function, including:
Input Signals (inlets)
Output Signals (outlets)
This endpoint is used to supply a list of Functions (and their info/requirements/meta-data) available to a specific Group (supplied as a Group ID)
This endpoint is used to process Signal data and return a new Signal(s)
Hosted Swagger API definition¶
Use the following template Insight API Swagger Template and only change the following:
- basePath (in many cases the host URL is sufficient and this should be left as "/")
The Insights Interface Schema is found here which details the interface details