Formula Time Series

Simple example

This example explains creating a formula time series and reading time series data from it.

CODE

POST {protocol://host:port/basePath}/api/repositories/{repository}/timeseries HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Content-Length: 311
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

{
  "ID": -1,
  "Name": "Formula_TimeSeries",
  "Description": "This formula time series is for documentation purpose.",
    "Type": 2,
    "Interval": {
    "Value": 2,
    "Multiplier": 15
  },
  "Unit": "kW",
  "Formula":{
  	"1970-01-01T00:00:00Z":"2"
	},
  "Quotation": false,
  "Audit": false,
  "Compressed": false,
  "ExchangeTimeSeries": []
}

Note that the three aforementioned flags Audit, Compressed and Quotation are all set to false. In addition, the Formula attribute is set to a simple dictionary. The key (1970-01-01T00:00:00Z) dictates from what time on the value (the formula, in this case "2") is valid.

Therefore, reading data from the time series always returns the constant value "2" (unless data is read in a different interval and/or unit)

Common Use Case

More commonly, a formula time series will reference other time series and perform calculations on their data. To demonstrate this, we first create a simple time series named "Data_TimeSeries":

Creating a Source Time Series

The data time series will save its data in a 15 minutes interval. The chosen unit is kW. {host} and {repository} .

The whole request would look as follows:

Creating data time series call

CODE

POST {protocol://host:port/basePath}/api/repositories/{repository}/timeseries HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Content-Length: 311
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

{
  "ID": -1,
  "Name": "Data_TimeSeries",
  "Description": "This data time series is for documentation purpose.",
    "Type": 2,
    "Interval": {
    "Value": 2,
    "Multiplier": 15
  },
  "Unit": "kW",
  "Formula":{},
  "Quotation": false,
  "Audit": true,
  "Compressed": false,
  "ExchangeTimeSeries": []
}

By specifying Audit to be true, we essentially define that this is a "normal" time series.

Writing Data to the Source Time Series

The following request writes some data to the time series we just created.

Writing data call

CODE

POST {protocol://host:port/basePath}/api/repositories/{repository}/timeseries/Data_TimeSeries/data HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Content-Length: 222
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

{
	"Interval": {
		"Value": 3,
		"Multiplier": 1
	},
	"Unit": "kW",
	"Data": [
		{
			"From":"2017-03-31T23:00:00Z",
    		"Value": 2.0,
    		"Flag": 9
  		},
    	{
    		"From":"2017-04-01T00:00:00Z",
    		"Value": 3.0,
    		"Flag": 9
  		}
	]
}

Referencing the data in the formula time series

We now modify our existing formula time series to, say, take the data from our "Data_TimeSeries" and multiply it by 10.

We do this by issuing a PUT request against the time series with the updated formula:

CODE

PUT {protocol://host:port/basePath}/api/repositories/{repository}/timeseries/Formula_TimeSeries HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Content-Length: 311
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

{
  "ID": -1,
  "Name": "Formula_TimeSeries",
  "Description": "This formula time series is for documentation purpose.",
    "Type": 2,
    "Interval": {
    "Value": 2,
    "Multiplier": 15
  },
  "Unit": "kW",
  "Formula":{
  	"1970-01-01T00:00:00Z":"2",
  	"2017-04-01T00:00:00Z":"10*[Data_TimeSeries]"
	},
  "Quotation": false,
  "Audit": false,
  "Compressed": false
  "ExchangeTimeSeries": []
}

The Formula dictionary now has an additional entry. This defines that as of April 1st 2017, values should be 10-times that of the value in "Data_TimeSeries".

Reading Data from the Formula Time Series

We can now read the data from the formula time series. The chosen start time is March 31st 2017 at 23:00:00h (UTC) and the end time April first 2017 at 02:00:00h (both in ISO8601 syntax: 2017-03-31T23:00:00Z and 2017-04-01T02:00:00Z). To get the data in one hour intervals, the interval is set to three (numeric value for hours) and the intervalMultiplier to one (can be left out). Note that special characters (":") need to be escaped in the query parameters (character sequence %3A encodes a colon character). This is also important when specifying time stamps in offsets other than UTC (Z), i.e. 2017-01-01T00:00:00+02:00 becomes 2017-01-01T00%3A00%3A00%2B02%3A00 ("+" = %2B)

Reading data call

CODE

GET {protocol://host:port/basePath}/api/repositories/{repository}/timeseries/Formula_TimeSeries/data?from=2017-03-31T23%3A00%3A00Z&to=2017-04-01T02%3A00%3A00Z&interval=3&intervalMultiplier=1 HTTP/1.1
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

The service responds with the following data:

Response by the service

CODE

{
	"Interval": {
		"Value": 3,
		"Multiplier": 1
	},
	"Unit": "kW",
	"Data": [
		{
    		"From": "2017-03-31T23:00:00Z",
    		"Value": 2.0,
    		"Flag": 9
  		},
  		{
    		"From": "2017-04-01T00:00:00Z",
    		"Value": 30.0,
    		"Flag": 9
  		},
  		{
   			"From": "2017-04-01T01:00:00Z",
    		"Value": 0.0,
    		"Flag": 19
  		}
	]
}

Notice: the first value still comes from the first formula in the time series (which is valid from January 1st 1970 onwards), the second value then correctly multiplies the referenced time series value (3) by 10.

Accessing Attributes from within a Formula

Two functions can be used inside formulas that allow access to a time series' attributes:

GetMyAttributeValue

Get's the value of a particular attribute assigned to the formula time series itself.

CODE

IF (GetMyAttributeValue("Test_Attribut_1") = "test2",1, 0)

This formula checks wether the formula time series, assigned attribute "Test_Attribut_1" has the value "test2" and if so, returns the value 1, otherwise the value 0

GetAttributeValue

Get's the value of a particular attribute assigned to another time series.

CODE

IF (GetAttributeValue(101752,"Test_Attribut_1", new DateTime(2019,01,01,23,0,54)) = "test2",1, 0)