Connector Transform Scripts
Introduction
You can send data from an external system to Clarity by configuring a Connector and sending HTTP POST requests to Clarity for that Connector. The HTTP POST body can be in any format, and the Transform Script you write for the Connector controls how the body gets interpreted.
The Transform Script is a piece of JavaScript defining a handler function that takes the request body as input, and should return data in the format that Clarity understands, which is described below.
If the input data is in the format described in Output Format, it is not necessary to write a transform script, and the "None" option can be selected.
Quick Example
Let's say your system will post text/plain
data where the first line is an ISO Date/Time, and each following line is a key/value pair:
Here's how the transform script could look:
Script Format
The script must be either a single function declaration, or contain a function named handler
.
Examples of Valid Scripts
Examples of Invalid Scripts
Input Format
Your function will be called with a request
object. Currently it only has the request.body
property.
request.body
request.body
This will be the body of your POST request. Its type depends on the Content-Type
header of your request:
Output Format
Your function must return an object with the following optional properties:
t
t
The timestamp for data values and events in the output that don't specify their own timestamp. Defaults to Clarity's current time.
data
data
Realtime and/or historical data to ingest into Clarity. This must be an object where each key is a tag, and the associated value is data for that tag. Several different formats for the data are supported:
Additionally, you can specify metadata
for a given tag by including a metadata
property alongside the optional t
and v
properties on the value object. The value of metadata
must be an object with the following optional properties:
events
events
Events to display notifications for in Clarity. This must be an array of objects where each object contains the following properties:
Output Examples
These are examples of the object you would return from your handler function.
In this example, an explicit timestamp is given for the foo
datapoint, but the current time in Clarity will be used for bar
:
In this example, the top-level t
timestamp will be used for bar
instead of the current time in Clarity:
In this case, multiple values are given for bar
:
In this case, metadata
is defined for some channels, some of which have values and some of which don't:
An example with events:
Limits
Builtin Transforms
In a dedicated Clarity instance, builtin transforms can be included at the application level. If these are included, the builtin transforms will be shown in the drop-down selector.
Last updated