Working with Time Series Data

Time Series Data

In HAKOM TSM a time series can store time series data on up to 3 time dimensions:

Data dimension: persisting current values
History dimension: persisting changed / historicized values
Quotation dimension: persisting versions

Each of these three dimensions can be used in any time series data operation, including time series data queries via formula references.

More about the possibilities with time series dimensions can be found here: Audit and Quotation

Read Data

Time series data can be easily obtained either via TSM App or WebTSM Services API.

TSM App:

Click on Load in the TSM Ribbon
Select the Name of the time series in the Time Series section, or use the time series search:
1. Press the Search... button in the Time Series section of the TSM window
2. Fill in the desired search parameters (like Name, Unit, Attributes)
3. Press the Search button
4. Select one or more time series
  
  Tip
  
  Using the Add button, the selection can be put into memory and combined with other search results:
5. Press OK
Select Interval, Unit and if necessary further parameters (such as descending and / or missing as null)
Press the Open button

Tip

Using the drop down menu of the Open button, data can be loaded into a new workbook (default behaviour) or into a new worksheet of an existing workbook.

WebTSM Services API:

Get data of single time series:
```
GET /repositories/:reposiory/timeseries/:ID|Name/data
?from=<fromDate>&to=<toDate>
```
Response format of single requests
Default "Self Contained Format" with From, Value, Flag per data point and Interval plus Unit in the data header (to get this format, use following parameter in URL or Accept/Content-Type header: format=timestamp):
XML
```
{
  "Interval": {
    "Value": 1,
    "Multiplier": 3600
  },
  "Unit": "cm/m2",
  "Data": [
    {
      "From": "2010-01-01T00:00:00Z",
      "Value": 1.5,
      "Flag": 9
    },
	{
      "From": "2010-01-01T01:00:00Z",
      "Value": 2.0,
      "Flag": 9
    }
  ]
}
```
From - To "timespan" Format (to get this format, use following parameter in URL or Accept/Content-Type header: format=timespan):
XML
```
[
  {
    "From": "2017-05-01T00:00:00Z",
    "To": "2017-05-01T01:00:00Z",
    "Value": 1.5,
    "Flag": 9
  },
  {
    "From": "2017-05-01T01:00:00Z",
    "To": "2017-05-01T02:00:00Z",
    "Value": 2.0,
    "Flag": 9
  }
]
```
Tip

The date format of the timestamps can also be modified using the dateFormat parameter (in URL or Accept/Content-Type header):
dateFormat=ISO8601 (or 0) → ISO 8601 time stamps (default)
dateFormat=EpochSeconds (or 1) → seconds since Unix epoch
dateFormat=EpochMilliseconds (or 2) → milliseconds since Unix epoch
Get multiple time series in bulk:
```
GET /repositories/:reposiory/timeseriescollections/data
?from=<fromDate>&to=<toDate>&name=<TS.1>&name=<TS.N>&interval=<interval>&intervalMultiplier=<intervalMultiplier>
```
Tip

Parameter Name and ID can be passed to /timeseriescollections/data several times, even in combination.
Response format of bulk requests
A bulk request delivers exactly the same formats / date formats as single requests, but the responses are wrapped in an envelope per time series. The envelope has the following structure:
[ { "ID": 3, "Name": "Test-TimeSeries", "Data": { "Interval": { "Value": 1, "Multiplier": 3600 }, "Unit": "cm/m2", "Data": [ { "From": "2010-01-01T00:00:00Z", "Value": 123.4, "Flag": 9 } ] }, "Message": "", "Details": "", "Status": 200 } ]
Tip

A bulk response is always returned, even if individual time series are not available or cannot be calculated due to formula errors. For this reason, each time series in the bulk response receives its own Http Status Code (Status), Message (e.g. error messages) and Details (e.g. stack trace of error messages) in addition to ID, Name and Data. Thus it is possible to trace if and which time series could be retrieved successfully.

Get the sum of multiple time series by Name:

GET /repositories/:reposiory/timeseriescollections/data/sum
?from=<fromDate>&to=<toDate>&attribute=<TS.1>&name=<TS.N>&interval=<interval>&intervalMultiplier=<intervalMultiplier>

Get the sum of multiple time series via assigned Attributes:

GET /repositories/:reposiory/timeseriescollections/data/sum
?from=<fromDate>&to=<toDate>&attribute=<attribute>|<value>&attribute=<attribute>|<value>&interval=<interval>&intervalMultiplier=<intervalMultiplier>

Get time series data via Ad Hoc Formula:

GET /repositories/:reposiory/calculations
?from=<fromDate>&to=<toDate>&calculationInterval=<calculation-interval>&calculationIntervalMultiplier=<calculation-intervalMultiplier>&formula=<formula>

Get multiple ad hoc formula results:

POST/repositories/:reposiory/calculations
?from=<fromDate>&to=<toDate>&calculationInterval=<calculation-interval>&calculationIntervalMultiplier=<calculation-intervalMultiplier>&formula=<formula>

JS

Minimum Request Body:
[
    {
        "Name": "<Calculation name>",
        "Formula": "<formula>",
        "CalculationInterval": "<interval>",
        "CalculationIntervalMultiplier": "<intervalMultiplier>"
    },
    {
        "Name": "<Calculation name>",
        "Formula": "<formula>",
        "CalculationInterval": "<interval>",
        "CalculationIntervalMultiplier": "<intervalMultiplier>"
    }
]

Get time series data from tree nodes (hierarchical attributes) - Get main nodes:

GET /repositories/:reposiory/trees/:ID|Name/sum
?from=<fromDate>&to=<toDate>&attribute=<TS.1>&name=<TS.N>&interval=<interval>&intervalMultiplier=<intervalMultiplier>

Get time series data from tree nodes (hierarchical attributes) - Get sub nodes:
```
GET /repositories/:reposiory/trees/:ID|Name/nodes/:nodeId/sum
?from=<fromDate>&to=<toDate>&attribute=<TS.1>&name=<TS.N>&interval=<interval>&intervalMultiplier=<intervalMultiplier>
```
Tip

The following parameters might be useful when working with tree nodes:
- timeSeriesAttributes (search by additional attributes)
- includeTimeSeries (includes time series definitions in the response → useful to find what time series is assigned to what node)
- includeSubNodes (includes sub nodes details in the results)
- sumType: includingSubNodes, excludingSubNodes

More about the WebTSM Services API can be found here: Open API Reference

Write Data

Time series data can be saved / updated either from TSM App or via WebTSM Services API.

TSM App:

Open any existing TSM Excel time series template containing data of the required time series or load the required time series (see chapter Get data) and adjust the data accordingly
In TSM Ribbon, click on Save → time series data will be saved (if no contradictionary control functions are present in the corresponding time series column).

Tip

In row 16 of the TSM Excel time series template you may control whether to read, save or ignore a specific column by adding following control commands:

don't read
don't save
ignore

WebTSM Services API:

Tip

The request bodies for data post methods are identical to those for data get methods.

Save single time series data:

POST /repositories/:reposiory/timeseries/:ID|Name/data

Save multiple time series data in bulk:

POST /repositories/:reposiory/timeseriescollections/data

More about the WebTSM Services API can be found here: Open API Reference

In What Period Does My Time Series Have Data?

HAKOM TSM prefilters all data requests to time periods where data is available for a given time series for you, this reduces database request time. For this feature updated time periods saved the audits are used. To get the time period when a given time series has data you can use the meta information feature of the WebTSM Services API, that includes the data period of the given time series:

XML

{
  "DataPeriod": {
    "From": "2017-04-01T00:00:00Z",
    "To": "2017-04-01T08:00:00Z"
  }
}

To get the meta information you may use the following paths:

Use time series search path with includeMetaInfo parameter to return meta info for multiple time series at once (see Find Time Series)
```
GET /repositories/:repository/timeseries?<search parameter, e.g. name=xyz>&includeMetaInfo=true 
```
Use metainfo path to easily return meta info for one specific time series
```
GET /repositories/:repository/timeseries/:ID|Name/metainfo
```

We recommend the following videos under Video Tutorials:

Handling Time Series Data
Bulk Operations