Using Custom Functions
This page describes how custom functions are registered and how to use them through the PowerTSM HTTP API, both in formula time series and in ad hoc calculations.
Registration
Section titled “Registration”Custom functions must be registered by placing them in the custom functions path configured in HAKOM:TSM:Calculation:Formulas:CustomFunctions.
Supported file types:
- Precompiled DLLs (
.dllfiles): Compiled .NET assemblies - C# Script files (
.csxfiles): Raw C# code files compiled at runtime
How such a function is written is described in Creating Custom Functions. This page covers how to call functions that are already available to the service.
Custom functions are available through the HTTP API. You can either create a formula time series that defines how to calculate values or perform direct ad hoc calculations by providing a formula with the HTTP request. Both modes and their parameters are described in Calculating Formulas; this page only covers what is specific to custom functions.
Formula Time Series
Section titled “Formula Time Series”To use a custom function in a formula time series, make a request to the endpoint POST /repositories/{repository}/timeSeries. A list of formulas can be specified for the key formula. An entry consists of a key-value pair where the key is a timestamp and the value contains the formula with custom functions.
Request
POST /repositories/{repository}/timeSeriesRequest Body
{ "Name": "formula_test1", "Unit": { "identifier": "°C", "storageInformation": { "repositoryName": "TSM_POSTGRESQL" } }, "Interval": { "Type": 3, "Multiplier": 1 }, "Cyclic": true, "FunctionType": 1, "Formula": { "1971-12-31T23:00:00Z": " BestValue([id:10005],[id:10006]) " }}Ad Hoc Calculations
Section titled “Ad Hoc Calculations”An ad hoc calculation can be executed by making a request to this endpoint:
GET /repositories/{repository}/calculations/formulasThe response is similar to the timeSeries/data endpoint. But instead of reading a time series directly, a formula containing one or multiple time series needs to be provided.
The formula is URL-encoded from ([id:14]+[id:15]) to %28%5Bid%3A14%5D%2B%5Bid%3A15%5D%29.
Request
GET /repositories/TSM_SQLSERVER/calculations/formulas?formulaString=%28%5Bid%3A14%5D%2B%5Bid%3A15%5D%29&from=2025-12-05&to=2025-12-06&calculationCyclic=False&calculationFunctionType=1&calculationIntervalType=3Query Parameters
Section titled “Query Parameters”The endpoint takes the same parameters regardless of whether the formula uses custom functions. They are documented under Query Parameters.
Complete Example: BestValue
Section titled “Complete Example: BestValue”Full example, assuming two existing spontaneous time series (ids: 123, 456) in repository TSM_ABC. Get the best values between those two time series for the interval 2024-12-19 to 2024-12-22 (by second):
Request
GET /repositories/TSM_ABC/calculations/formulas?formulaString=BestValue%28%5Bid%3A123%5D%2C%5Bid%3A456%5D%29&from=2024-12-19&to=2024-12-22&calculationCyclic=false&calculationFunctionType=1&calculationIntervalType=1Parameters:
| Parameter | Value |
|---|---|
formulaString |
BestValue%28%5Bid%3A123%5D%2C%5Bid%3A456%5D%29 the URL encoded form of BestValue([id:123],[id:456]) |
from |
2024-12-19 |
to |
2024-12-22 |
calculationCyclic |
false |
calculationFunctionType |
1 |
calculationIntervalType |
1 |
The meaning of each parameter is documented under Query Parameters.