Add-on Calculation Webhook

JVM AGENT

Overview

The Add-on Calculation Webhook connector extends the calculation capabilities of Seeq with the compute capabilities of other external systems. When an Add-on Calculation Webhook connection is properly configured, the webhook is triggered in Workbench to make an HTTPS request to the configured endpoint, sending a payload of data to your external server and getting a response back to Workbench. A registered Add-on Calculation Webhook is accessible to Seeq users in the Formula editor as a User Defined Function (UDF).

Prerequisites

The main prerequisite to creating an Add-on Calculation Webhook connection is having a REST API endpoint accessible from the remote agent where the connection is configured. From the Seeq side, make sure that the Features/AddOnCalculations/Webhook/Enabled flag is enabled (Administration > Configuration with Advanced Filter enabled)

The webhook can be triggered when indexing the connection or from a compute request from Workbench. The endpoint needs to send different responses depending on whether the HTTP request was triggered from an indexing operation or from compute operation. The HTTP request sends, as part of the payload, the property action whose value can be either metadata or compute to distinguish between the indexing and compute operations that triggered the HTTP request.

Currently, two types of calculations are supported by the Add-on Calculation Webhook connector: 1) keywise calculations, and 2) sliding-window calculations. The main difference between the two is that window calculations provide expanded data in the HTTP request to perform calculations based on the time window specified (useful when doing data aggregation).

HTTP request payload to your endpoint

Property Name	Values	Data Type	Description
`action`	`compute` or `metadata`	String	The action that triggered the HTTP request.
`signal_data_types`	[ `"NUMERIC"` or `"STRING"`]	Array	Seeq signal types. Only if `action: compute`
`data`	[[ `key1`, `signal1_sample1`, `signal2_sample1`, …],[`key2`, `signal1_sample2`, `signal2_sample2`, …]]	Multidimensional Array	Signal data. Only if `action: compute`
`window_size`		Float	Size of the window in terms of number of samples. Only if `action: compute` and `"inputMode": "WINDOW"` in metadata response

HTTP response from your endpoint

The response from your endpoint must be different depending on whether the request action is compute or metadata

HTTP `metadata` response

The metadata response must be a json object with the following properties.

Property Name	Values	Data Type	Description
`inputMode`	`KEYWISE` or `WINDOW`	String	Determines whether the Seeq HTTP request will send an expanded windowed data timeframe.
`outputType`	`"NUMERIC"` or `"STRING"`	String	The data type of the response from the `compute` action of the endpoint
`udfDefinition`	`Name` - String `Documentation` - String `Formula` - See below `Parameters` - List `Examples` - List	Dictionary	UDF definition. See this page for details.
`udfDefinition.Formula`	`addOnCalculation()` or `addOnCalculationOnWindow`	String	Please see the configuration details for Add- Calculation Engine

HTTP `compute` response

The compute response must be a json object with the following properties.

Property Name	Values	Data Type	Description
`doubleSignal`	[`sample1`, `sample2`, `sample3`, … ]	Array	Array of values that correspond to the samples of the output signal
`signalKeys`	[`timestamp1`, `timestamp2`, `timestamp3`, … ]	Array	Array of timestamps in nanoseconds for the output signal. This is typically re-arrange from the `data` property in the payload of the request
`outputType`	`NUMERIC` or `STRING`	String	Whether the output signal from the endpoint is a numeric or a string signal

Examples

Python endpoint implementation example using Flask

PY

@app.route('/myendpoint', methods=['POST']) 
def mycalculation():     
    action = request.json.get('action')      
    if action == "metadata":         
        return create_metadata()     
    else:           
        signal_data = request.json.get('data')          
        return {             
            "doubleSignal": compute(signal_data),             
            "signalKeys": [sample[0] for sample in signal_data],             
            "outputType": "NUMERIC"         
        }

def create_metadata():     
    return {         
        "inputMode": "KEYWISE",         
        "outputType": "NUMERIC",         
        "udfDefinition": {             
            "Name": "MyAwesomeCalc",             
            "Documentation": "This function calls my endpoint to calculate a transformed signal based on Temperature and Pressure",             
            "Formula": "addOnCalculation(@@scriptId@@, 'NUMERIC', $temperature, $pressure)",             
            "Parameters": [
                {"Name": "temperature", "Formula": "sinusoid()"},                            
                {"Name": "pressure", "Formula": "sinusoid()"}
                ],             
            "Examples": [{
                "Formula": "@@functionName@@($temperature, $pressure)",                           
                "Description": "My calculation based on Temperature and Pressure"
                }]
            }
        }
        
def compute(signal_data):     
    awesome_calculation = ...  # type: list
    return awesome_calculation

Python endpoint implementation using Data Lab

This Jupyter notebook has several examples of endpoint implementations using Data Lab. To use it, import this notebook at a Seeq Data Lab project and save it. The endpoint will be accessible as a REST API endpoint. See https://support.seeq.com/kb/latest/cloud/invoking-a-data-lab-functions-rest-api-endpoint for details to make an HTTP request to the Data Lab endpoints.
api.ipynb

HTTP POST request (payload to your endpoint during indexing)

{"action": "metadata"}

HTTP response from your endpoint when action is metadata

KEYWISE calculation (See UDF definition for more details. )

CODE

{
    "inputMode": "KEYWISE",
    "outputType": "NUMERIC",
    "udfDefinition": {
        "Name": "numericNegation",
        "Documentation": "original function",
        "Formula": "addOnCalculation(@@scriptId@@, $signal)",
        "Parameters": [{
                "Name": "signal",
                "Formula": "sinusoid()"
            }
        ],
        "Examples": [{
                "Formula": "$series.@@functionName@@()",
                "Description": "Negate"
            }
        ]
    }
}

WINDOW calculation

CODE

{
    "inputMode": "WINDOW",
    "outputType": "NUMERIC",
    "udfDefinition": {
        "Name": "movingAverage",
        "Documentation": "This function can compute the moving average",
        "Formula": "addOnCalculationOnWindow(@@scriptId@@, 1/hour, 1day, startKey(), $signal)",
        "Parameters": [{
                "Name": "signal",
                "Formula": "sinusoid()"
            }
        ],
        "Examples": [{
                "Formula": "$series.@@functionName@@()",
                "Description": "Compute the moving average of $series"
            }
        ]
    }
}

HTTP POST request (payload to your endpoint when request is triggered by compute)

KEYWISE calculation

CODE

{
    "action": "compute",
    "signal_data_types": ["NUMERIC"],
    "data": [[1712588760000000000, 64.79883458], [1712588880000000000, 64.7721975], ..., [1712600400000000000, 64.580117], [1712600520000000000, 64.53718506], [1712600640000000000, 64.46625369]]
}

WINDOW calculation

CODE

{
	"action": "compute",
	"signal_data_types": ["NUMERIC"],
	"data": [[1715457600000000000, 82.43574576], [1715461200000000000, 87.63449123], ..., [1715637600000000000, null], [1715641200000000000, null]],
	"window_size": 24
}

HTTP response from your endpoint when action is compute

KEYWISE or WINDOW calculation

CODE

{
	"doubleSignal": [-64.79883458, -64.7721975, ..., -64.580117, -64.53718506, -64.46625369],
	"signalKeys": [1712588760000000000, 1712588880000000000, ..., 1712600400000000000, 1712600520000000000, 1712600640000000000],
	"outputType": "NUMERIC"
}

Configuration

This is an example configuration template that is displayed in the Additional Configuration box that appears when you click Configure for an existing datasource (or if a new datasource is being created, in the Create new datasource connection modal that appears after clicking Add Datasource) on the Datasources administration page.

CODE

{
    "AuthenticationType": "BEARER_TOKEN",
    "Url": "<endpointUrl>",
    "PackageName": "<packageName>",
    "Token": "<your token>",
    "Version": null,
    "ConnectTimeoutInSeconds": 120,
    "ReadTimeoutInSeconds": 300,
    "CallTimeoutInSeconds": 3600
}

Additional Configuration

If your API endpoint requires authentication, only Bearer Token authentication is supported by the Add-on Calculation Webhook connector.

Property Name	Default Value	Data Type	Description
`AuthenticationType`	`BEARER_TOKEN` or `SEEQ_DATA_LAB_FUNCTIONS`	String	Use `BEARER_TOKEN` if your endpoint requires an Bearer Token Authentication. Use `SEEQ_DATA_LAB_FUNCTIONS` if calling a Data Lab endpoint or your endpoint does not required authentication.
`Url`	null	String	The URL of your endpoint
`PackageName`	null	String	The name of the UDF package in Formula
`Token`	null	String	Token if `BEARER_TOKEN` is selected for `AuthenticationType`
`Version`	null	String
`ConnectTimeoutInSeconds`	`120`	Integer
`ReadTimeoutInSeconds`	`300`	Integer
`CallTimeoutInSeconds`	`3600`	Integer

If your endpoint is set up in a Data Lab project, you must provide the Agents group with Read and Write permissions to the DataLab project that hosts the API endpoint.

Known Issues

There are no known issues with this connector. Please report any issues you find to our support portal.

Please report any other issues you find to our support portal.

Troubleshooting

If you are having issues connecting to or accessing data from the Add-on Calculation Webhook, view our guide for troubleshooting datasource issues. Also, check out the https://support.seeq.com/kb/latest/cloud/add-on-calculation-engine and https://support.seeq.com/kb/latest/cloud/creating-user-defined-formula-functionssupport pages.

Performance considerations

Connecting to the Add-on Calculation Webhook does not have any special performance considerations. View our guide on optimizing datasource performance for general guidance.

Overview

Prerequisites

HTTP request payload to your endpoint

HTTP response from your endpoint

HTTP metadata response

HTTP compute response

Examples

Configuration

Additional Configuration

Known Issues

Troubleshooting

Performance considerations

HTTP `metadata` response

HTTP `compute` response