With the new version PowerTSM 4 a basis for an even more powerful and future-oriented time series management system was created. For this purpose, a completely new API was developed, which not only convinces with a clearer design and an even better documentation than before, but additionally offers several new features.
Security is an important topic and was therefore also considered in such a big change as TSM 4.
From now on, password security is additionally improved by certificates. For easy handling a console program is provided which can manage the passwords.
Furthermore: To ensure the integrity of the files, each executable and compiled file is digitally signed.
The well known HAKOM.Config has now been fully replaced by HAKOM.xml, which is now better structured and easier to understand. This means that the HAKOM.Config is no longer supported and has to be updated.
Apart from that it is now easily possible to configure TSM by any other configuration source like environment variables, command line arguments and so on.
Formerly known as the WebTSM Service, HAKOMs RESTful API for managing time series has been redesigned just like the .NET API has. The new service is available starting with version 4.1.
In version 3.x, the type of time series was defined using the following types:
Start
End
Spontaneous
To make this classification clearer and more extensible, this type was split into two properties in version 4.x:
Function Type — Describes the mathematical function of the data
Cyclic — Describes the interpretation of the data repetition in relation to the interval
There are two function types available:
Step-Right — Stands for a piecewise-constant function, where the value of a data point applies to the interval beginning at the data point’s time. Example: Power values (watts).
Step-Left — Stands for a piecewise-constant function, where the value of a data point applies to the interval ending at the data point’s time. Example: Energy values (watt hour).
Further, a cyclic time series has a value for each interval step and is valid for only one interval step. In contrast, an acyclic time series value is valid until the next value and can therefore have a valid range of multiple interval steps. The value of an acyclic data point is continued as a repetition on the underlying interval steps.
Depending on the function type, in 4.x the timestamp marks the beginning (Step-Right) or the end (Step-Left) of a data point, while in 3.x the timestamp always points to the beginning.
In 3.x there used to be a difference in the way the same intervals were handled when expressed in different ways. For example 2h and 7200 seconds used to yield different results when the interval would go over a daylight savings change. If the interval is 2h, the length of the data point going over the DST change would increase by one hour when it was a change from summer to winter time or decrease by an hour when the change was from winter to summer time, so that all data points would be at the same time of day. In contrast, a 7200 second interval would not undergo this change, so it would appear that data points have shifted by one hour after the change, when they’re in fact the same — it’s the offset to UTC that has changed.
That is no longer the case for most interval types. Of course 1 month will not always be equal to 30 days, nor will a year always equal 365 days, but for smaller measurements (up to a week) it doesn’t matter which unit of time is used, as the changes are now happening through the use of time zones.
Due to the different ways intervals are handled, there will be a difference with reading and writing the same data in 3.x and 4.x when going from winter time to summer time or vice-versa, especially if the interval is more unusual, like 9 days or 42 minutes for example.
If the old functionality is desired (no changes in the duration of the one data point which goes over the DST change), the time zone of the time series should be changed to one without a DST change, e.g. UTC or UTC with the desired offset.
What 3.x called a spontaneous time series is an acyclic time series in 4.x (function type Step-Right, Cyclic = false). The underlying idea is unchanged: a value is stored whenever it changes and stays valid until the next value. This section concerns only acyclic time series - regular fixed-interval (cyclic) time series are not affected.
The migration does not change your stored values or timestamps. What changes is that (1) acyclic time series can no longer have “no interval”, (2) gaps and the end of a series are handled differently, and (3) aggregations over acyclic data are calculated differently.
From PowerTSM 4.8 onwards, acyclic time series without an interval will no longer be supported. Instead, acyclic time series that cannot be assigned a specific interval should be created with the smallest possible interval (1 second or 1 millisecond, depending on the database setting). The definition of the validity of a value for acyclic time series has also changed. A value in an acyclic time series is now valid for the specified interval, but this validity is repeated until a new value (or the value 0 with the Ignore flag) occurs. This modified behavior makes it possible to correctly handle acyclic time series with units that use the interval transformation method “Sum”, e.g. energy or work units such as kWh.
Because a 3.x “no interval” spontaneous series is migrated to a one-second interval, the way data is read back can change - but only when an interval is requested. Reading without an interval returns the same value changes as before (4.x only adds a trailing stopper). Reading with an interval is where the two versions diverge, as the examples below show.
For example:
A time series with the interval aggregation method “Sum” and no interval has the following three data points assigned on the same day:
2026-05-21 05:00 - 10
2026-05-21 08:00 - 20
2026-05-21 09:00 - 30
This request, without an interval, returns almost the same result for a 3.x and a 4.8+ database - the stored values are returned as they are. The only difference is that 4.x appends a trailing Ignore data point (a “stopper”, value 0, flag 0) marking the end of the stored data within the read window:
data?from=2026-05-21Z&to=2026-05-22Z
3.x vs 4.8+ responses (no interval)
3.x Response:
{
"TimeZone": null,
"Interval": {
"Value": 0,
"Multiplier": 1
},
"Unit": "kWh",
"Data": [
{
"From": "2026-05-21T00:00:00Z",
"Value": 0,
"Flag": 19
},
{
"From": "2026-05-21T05:00:00Z",
"Value": 10,
"Flag": 9
},
{
"From": "2026-05-21T08:00:00Z",
"Value": 20,
"Flag": 9
},
{
"From": "2026-05-21T09:00:00Z",
"Value": 30,
"Flag": 9
}
]
}
4.8+ Response — identical values, plus a trailing Ignore stopper:
{
"TimeZone": null,
"Interval": {
"Value": 0,
"Multiplier": 1
},
"Unit": "kWh",
"Data": [
{
"From": "2026-05-21T00:00:00Z",
"Value": 0,
"Flag": 19
},
{
"From": "2026-05-21T05:00:00Z",
"Value": 10,
"Flag": 9
},
{
"From": "2026-05-21T08:00:00Z",
"Value": 20,
"Flag": 9
},
{
"From": "2026-05-21T09:00:00Z",
"Value": 30,
"Flag": 9
},
{
"From": "2026-05-22T00:00:00Z",
"Value": 0,
"Flag": 0
}
]
}
Without a requested interval there is no hidden per-second aggregation: 4.x returns the stored values (10, 20, 30) exactly like 3.x and only adds the trailing Ignore stopper marking the end of the read window. The per-second aggregation happens only when you request an interval, as shown next.
The same request, with a specified interval:
data?from=2026-05-21Z&to=2026-05-22Z&interval=4
3.x vs 4.8+ responses (interval = Day)
3.x Response:
{
"TimeZone": null,
"Interval": {
"Value": 4,
"Multiplier": 1
},
"Unit": "kWh",
"Data": [
{
"From": "2026-05-21T00:00:00Z",
"Value": 60,
"Flag": 19
}
]
}
4.8+ Response:
{
"TimeZone": null,
"Interval": {
"Value": 4,
"Multiplier": 1
},
"Unit": "kWh",
"Data": [
{
"From": "2026-05-21T00:00:00Z",
"Value": 1800000,
"Flag": 19
}
]
}
3.x responds with the aggregation of the explicitly specified values: 10 + 20 + 30 = 60. 4.8+ responds with the sum of all repeating values over each second. The series is in UTC, so the day spans 00:00Z to 24:00Z:
For the first 5h, the value is 0: 5 * 3600 * 0 = 0
From 05:00 to 08:00 (=3h), the value is 10: 3 * 3600 * 10 = 108 000
From 08:00 to 09:00 (=1h), the value is 20: 1 * 3600 * 20 = 72 000
From 09:00 to the end of the day (=15h), the value is 30: 15 * 3600 * 30 = 1 620 000
So the sum for the entire day is 108 000 + 72 000 + 1 620 000 = 1 800 000.
This large 4.8+ total comes from interpreting each value as a quantity per second, because the migrated series now has a one-second interval and a Sum unit. This is exactly why the migration changes the interval transformation method of such series from Sum to Average (see the migration notes below), so that aggregated results stay close to the 3.x behaviour.
There is also a key difference in how an interval request is interpreted:
In 3.x, as soon as you request an interval, a spontaneous series is treated like a Begin (cyclic) series - the value is repeated for every interval step.
In 4.x, the series stays acyclic regardless of the requested interval - only the points where the value changes are returned (plus the stopper).
When using the 4.x HTTP API, the new boolean request parameter cyclic controls this. With cyclic=true the data is expanded to repeating values for every interval step, reproducing the 3.x behaviour (for example, an hourly read repeats 36 000 per hour for as long as the underlying value of 10/second holds). With cyclic=false - the default for an acyclic series - only value changes are returned:
data?from=2026-05-21Z&to=2026-05-22Z&cyclic=true
The value for each second is returned:
{
"unit": {
"identifier": "kWh",
"storageInformation": {
"repositoryName": "TSM_SQLSERVER"
}
},
"interval": {
"type": 1,
"multiplier": 1
},
"cyclic": true,
"function": 1,
"timeZone": "UTC",
"data": [
{
"time": "2026-05-21T00:00:00+00:00",
"value": 0,
"flag": 19
},
{
"time": "2026-05-21T00:00:01+00:00",
"value": 0,
"flag": 19
},
{
"time": "2026-05-21T00:00:02+00:00",
"value": 0,
"flag": 19
},
{
"time": "2026-05-21T00:00:03+00:00",
"value": 0,
"flag": 19
},
{
"time": "2026-05-21T00:00:04+00:00",
"value": 0,
"flag": 19
},
...
data?from=2026-05-21Z&to=2026-05-22Z&cyclic=false
Only value changes are returned:
{
"unit": {
"identifier": "kWh",
"storageInformation": {
"repositoryName": "TSM_SQLSERVER"
}
},
"interval": {
"type": 1,
"multiplier": 1
},
"cyclic": false,
"function": 1,
"timeZone": "UTC",
"data": [
{
"time": "2026-05-21T00:00:00+00:00",
"value": 0,
"flag": 19
},
{
"time": "2026-05-21T05:00:00+00:00",
"value": 10,
"flag": 9
},
{
"time": "2026-05-21T08:00:00+00:00",
"value": 20,
"flag": 9
},
{
"time": "2026-05-21T09:00:00+00:00",
"value": 30,
"flag": 9
},
{
"time": "2026-05-22T00:00:00+00:00",
"value": 0,
"flag": 0
}
]
}
So, to get one row per interval step from an acyclic series in 4.x - the way a 3.x read with an interval behaves - request the interval and add cyclic=true. Without cyclic=true, an acyclic read returns only the value changes, no matter which interval you request.
Writing Acyclic Time Series Data With a Different or Shifted Interval
The storage behaviour of acyclic time series has also been adjusted so that data is now only stored in the time series interval. Prior to storage in the database, data that is not in the time series interval is converted to comply with it. The specified interval for acyclic time series is now becoming more and more important. It is therefore essential to set this interval correctly.
When writing acyclic data through the HTTP API, the point where the last value stops being valid must be marked by adding a final data point flagged Ignore (a “stopper”, value 0) at that timestamp. In 3.x the server derived the end of the series for you, and a value could be left open-ended to stay valid indefinitely. In PowerTSM 4 this is no longer supported: a write whose last data point is not an Ignore stopper is rejected, because a value with no defined end cannot be processed or transformed (for example onto a fixed-interval grid). The old approach of writing an “endless” value at a maximum date is therefore no longer used - always end the data with an Ignore stopper instead.
A few acyclic configurations are not allowed in PowerTSM 4. If you never used them, there is nothing to do:
Acylic time series without an interval: They need to be converted to second (or millisecond interval).
Open ended acyclic time series: Acyclic time series must have a final “stopper”, where the time series ends. Having a final “endless” value is no longer possible.
The old linear interpolation time series type no longer exists.
Compatibility With the Latest PowerTSM 3.x Release
If time series without an interval are created over PowerTSM 3.x on a PowerTSM 4.8 database, the interval is automatically changed to the smallest possible interval in the background.
This change affects formula time series. If a formula time series is defined as an unscheduled time series without an interval, it is calculated differently to unscheduled formula time series with the smallest interval. The different behaviour can be seen in the following example:
Given the following two acyclic time series:
Values of time series A:
Timestamp
Value
Flag
2023-06-18T13:52:14
3
Valid
2023-06-18T19:48:13
4
Valid
Values of time series B:
Timestamp
Value
Flag
2023-06-18T16:27:27
10
Valid
2023-06-18T23:39:01
20
Valid
An acyclic formula time series aggregating time series A and B would have the following different results:
Result for acyclic formula time series with no interval:
Timestamp
Value
Flag
2023-06-18T00:00:00
20.022700502987
Valid
Result for acyclic formula time series with the smallest possible interval (in this example 1 second):
Timestamp
Value
Flag
2023-06-18T00:00:00
0
Missing
2023-06-18T13:52:14
3
Valid
2023-06-18T16:27:27
13
Valid
2023-06-18T19:48:13
14
Valid
2023-06-18T23:39:01
24
Valid
Writing Acyclic Time Series Data With a Different or Shifted Interval
The changed behaviour in writing leads to challenges in compatibility with 3.x. If the values are written in the correct interval, no compatibility problems are to be expected. However, when saving with different or shifted intervals than specified on the time series, there will be a different behaviour between the last PowerTSM 3.x release and PowerTSM 4.
PowerTSM 4 converts data that is not already in the time series interval before storing it. How the conversion changes the values depends on the unit’s interval transformation method:
With a Sum unit (e.g. energy/work such as kWh) the values are summed, and pro-rated for partial intervals. Writing a finer-interval value therefore changes its magnitude, so the stored result differs from the last 3.x release, which kept the spontaneous value as written.
With a non-Sum unit (e.g. a power unit such as kW, which averages) the value is averaged by duration and is not scaled, so 3.x and PowerTSM 4 produce the same result.
The examples below use an acyclic time series whose own interval is one hour and a Sum unit (kWh), with data written at a 15-minute interval.
Writing a value and ending it with an Ignore stopper:
Timestamp
Value
Flag
2026-05-21T13:00:00
100
Valid
2026-05-21T13:45:00
0
Ignore
Version
Result at 13:00
Latest 3.x
100 (the spontaneous value is stored as written)
PowerTSM 4
400, Valid (plus an Ignore stopper at 14:00)
PowerTSM 4 ignores the incomplete tail (13:45-14:00), so the value 100 fills the whole one-hour step and, summed over the four 15-minute steps, becomes 100 * (60 / 15) = 400.
“Filling” the incomplete interval (a work-around suggested in earlier documentation) does not reproduce the 3.x value either - it only changes which flag is reported:
Timestamp
Value
Flag
2026-05-21T13:00:00
100
Valid
2026-05-21T13:45:00
0
Missing
2026-05-21T14:00:00
0
Ignore
Version
Result at 13:00
Latest 3.x
100
PowerTSM 4
300, Missing (the 13:45-14:00 step now counts as 0)
For a Sum unit there is therefore no write-side trick that makes PowerTSM 4 return exactly the 3.x numbers when data is written at a different interval than the time series. Write acyclic data in the time series’ own interval (or define the time series at the interval you actually write). With a non-Sum unit (e.g. kW) no scaling factor applies and both versions already agree.
When updating from PowerTSM 3.x to PowerTSM 4.8, all acyclic time series that do not have an interval set are set to the smallest possible interval (1 second, or 1 millisecond on a database configured for milliseconds). Furthermore, for time series that do not have an interval set but do have a unit with interval transformation method “Sum”, the interval transformation method of the time series is set to Average in order to keep changes to the previous behaviour to a minimum.
This conversion is applied automatically during the upgrade - you do not run anything. Because the Sum to Average change can shift aggregated results slightly, spot-check a few important aggregations (for example a daily Sum or an hourly Average) on these series after the upgrade and confirm the difference is acceptable.
Writing Acyclic Time Series Data With a Different or Shifted Interval
No data conversion is required - reading existing acyclic data written by the last PowerTSM 3.10 release has no known compatibility issues. Reading and writing behaviour still differs, however, as described above (see Interval of Acyclic Time Series and the writing changes).
Note which acyclic time series have no interval (they will be set to 1 second / 1 millisecond) and which use a Sum unit (their transformation method becomes Average).
Save a few “before” numbers from important reports (a daily Sum, an hourly Average) to compare afterwards.
After the upgrade, compare those numbers and investigate only the ones that differ - gaps and the Sum to Average change are the usual causes.
If you write acyclic data via the HTTP API, always end writes with an Ignore stopper where the last value should stop being valid. Open-ended (“endless”) values are no longer supported - the old “endless value at a maximum date” approach must be replaced by an explicit stopper.
From now on PowerTSM 4 also supports data before 1970. This means that from now on a time series is also suitable for historical data. However, the year 1970 remains the default value, which can be defined differently when creating the time series.
Compatibility With the Latest PowerTSM 3.x Release
In 3.x, time series have a start-of-day and a start-of-year property. These two have been consolidated in 4.x and their functionality is now represented by the new start-of-time property. It defines a starting point from which intervals will be calculated for data points when reading and writing data. This allows for more accurate transformations when the interval of the data doesn’t match the interval of the time series. For example, if a time series starts at 01:30 but the data starts at 01:00, assuming both have an interval of 1h, each data point will apply for half of one interval and half of the next, so a data transformation will be necessary.
The latest 3.x release is only partially compatible with this change. Since only the start of the year (in months) and the start of the day (in hours) are taken into account, only a date with the first day of a month and exact hours are interpreted correctly.
In PowerTSM 3.x it is possible to create a time series not only with standard time zones (Windows or IANA), but also with short names (e.g. CET) or with offsets from UTC (e.g. UTC+9).
In PowerTSM 4.x these short names are no longer supported. Custom offsets from UTC are still supported, in a slightly different but more flexible way using the format UTC±hh:mm (e.g. UTC+09:00).
Another important point to note is that the default time zone is now UTC. In version 3.x the default time zone was taken as set in the operating system, which is problematic when running the applications in different time zones.
In PowerTSM 4.x the default time zone can be changed to any Windows or IANA time zone by the following configuration entry: TSM:TimeSeries:Defaults:TimeZone. This time zone applies to all time series for which no time zone is set.
Time series created with a Windows or IANA time zone in 4.x are compatible with 3.x. Custom time zones from 4.x are not supported in 3.x and vice versa.
In version 3.x, there is a time series property called “Audit” which determines whether historical records should be stored to allow time travelling. Audit logs (i.e. who changed what) were always written and could not be configured.
In 4.x, both use cases are now configurable on the time series and the naming has also been adjusted and corrected. The following properties can be activated on a time series in PowerTSM 4:
The table below describes the behavior of the new properties in comparison with version 3.x:
Preserve Audit Log
Preserve Historic Data
Behavior
true
true
An audit log entry is created and the data can be retrieved at any time in the state in which it was at a specific point in time. Same behavior as in 3.x if the property “Audit” is set to true.
true
false
There will be a log entry every time data is written to the repository. The log entry will not contain the actual data, but it will show the editor and period of the written data. Same behavior as in 3.x if the property “Audit” is set to false.
false
true
Not possible in 3.x nor in 4.x, because audit logs are required to read historical data fast & efficiently.
false
false
No audit logs or historical data are stored. Most common use-case: time series data stored at very short intervals, e.g. sensor data. When saving data with version 3.x, an audit log entry will still be written.
During the upgrade the new properties are initialized depending on the existing time series definition and PowerTSM 4.8 will be able to work with them.
In version 3.x, there is a time series property called “Quotation” that determines whether it is a quotation time series. Audit logs and historical records are always stored for these.
In 4.x, it is now possible to select for quotation time series whether audit logs and historical records should be stored or not by setting the new properties “Preserve Audit Log” and “Preserve History Data”.
The table below describes the behavior of quotation time series in comparison with version 3.x:
Quotation
Preserve Audit Log
Preserve Historic Data
Behavior
true
true
true
Same behavior as in 3.x if the property “Quotation” is set to true.
true
true
false
There will be a log entry every time data is written to the repository. The log entry will not contain the actual data, but it will show the editor and period of the written data. The reading and writing of data in 3.x is done with the wrong table and is therefore not compatible with 4.x.
true
false
true
Not possible in 3.x nor in 4.x, because audit logs are required to read historical data fast & efficiently.
true
false
false
No audit logs or historical data are stored. When saving data with version 3.x, the data will be stored in the wrong table and therefore it is not compatible with 4.x.
During the upgrade the new properties “Preserve Audit Log” and “Preserve Historic Data” are initialized depending on the existing time series definition and PowerTSM 4.8 will be able to work with them.
Compressed time series can be customized from TSM 4 onwards. This is made possible by an additional setting CompressionMultiplier. This setting can be used to control how many data records are to be stored in a compressed data block. Depending on the time series and the interval of this time series, the compression can be set variably. The CompressionMultiplier always refers to the interval of the time series. This means that if a time series has a 15-minute interval and the CompressionMultiplier is 96, the data is stored in a daily block.
If no CompressionMultiplier is specified, a default value is used. Default values also depend on the time series interval:
Due to the change in behaviour, backwards compatibility is only supported for cyclical time series with the StepRight (alias Begin) function type and the following intervals:
Formula time series have been completely redesigned in PowerTSM 4 to simplify and standardize the implementation of custom formulas by using the new PowerTSM .NET API.
Custom functions and also the time series formula itself (e.g. function calls) are not compatible with PowerTSM 3.x.
There are three notable breaking changes from formulas in 3.x versions:
When referencing another time series, the format has changed slightly: instead of having to reference time series by their numeric id, they can now be referenced by their name again. When referencing a time series by their id, this must be explicitly stated. This is to support repositories that use something other than integers to identify time series (i.e. GUIDs, hashes, etc.).
When writing custom functions for use in formulas (formerly known as EvalComponents) the following things have changed:
Custom functions must be written in C# as opposed to VB.Net
Custom functions must implement a specific interface (HAKOM.TSM.Net.Api.Calculation.Formulas.CustomFunctions.ICustomFunction)
Both precompiled custom functions (as .dll files) as well as raw code (.csx files) are supported
When calling a function from the static Math class, the actual value needs to be passed instead of an ITimeSeriesData object — so instead of calling Math.Abs([someTimeSeries]) you must call Math.Abs([someTimeSeries].Value).
In addition, the supported programming language was changed from Visual Basic .Net to C#.
The standard 3.x attribute types will continue to be supported, although new user-specific attribute types will not be recognized in PowerTSM App 3.x and may cause errors.
The persistence of attribute assignments has changed in PowerTSM 4.x. This leads to performance improvements when searching for and aggregating time series by attributes.
The existing persistence of the attribute assignment is automatically migrated during the upgrade so that it remains fully functional and compatible with version 4.8.
In the future, some already known features, but also completely new ones will be added. Also new versions of the known TSM apps will appear. Apart from that, let us surprise you with what is still to come.