Historian REST interface

The HistorianAPI is a Websocket Interface that transfers JSON data. By default it is listening on port 8083. This can be changed by editing ConfigServer.Settings.

All API requests expect an UTF-8 encoded JSON object. The following properties are used for all requests:

• "function": string, required. Possible are:
• Historian/Read
• Historian/Write
• Historian/AddVariable
• Historian/DeleteVariable
• Historian/ReadVariable
• Historian/ListVariables
• Historian/ReadGlobalSettings
• Historian/WriteGlobalSettings
• Historian/ReadChangeTimestamp
• Historian/DiagVariable
• Historian/ReadStruct
• Historian/WriteStruct
• Historian/ListStructs
• Historian/DeleteStruct
• "id": string or number, optional, returned unmodified to allow identifying the answer

More properties may exist, depending on the function to execute. Any unknown properties are silently ignored. For future compatibility avoid sending undocumented properties.

All API answers are returned as an UTF-8 encoded JSON object. The following properties always exist:

• "function": string, copied from request
• "id": string or number, copied from request if present
• "status": number, status code of request (0 is OK, more values are documented below)

More properties may exist, depending on the function to execute. For future compatibility, the client should ignore any properties it does not recognize.

Function "Historian/Read"

Reads historical values.

Additional request properties:

• "variable": string, required, name of the historian variable to read
• "subvariable": string, optional, name of the sub variable for group variables
• "valuecount": number, optional, maximum number of values to return
• "start", "stop": string, optional, ISO-8601-formatted date, bounds of requested timespan (documented below)
• "resolution": string, required, requested time resolution (documented below)
• "aggregate": string, required, requested aggregate function (documented below)
• "includebounds": boolean, optional, true to include bounds values (one value before and after the specified interval, unless the given bound exactly matches a value); default false
• "reverse": boolean, optional, true to return values in reverse order (newest value first); default false

Notes:

• At least 2 of "start", "stop" and "valuecount" must be given.
• If both "start" and "stop" are given, "start" must not be earlier than "stop".

Additional response properties:

• "variable": string, copied from request
• "subvariable": string, copied from request (if present)
• "values": array of objects, values returned (documented below)
• "blocked": boolean, true if more values exist than could be returned in this answer (limited by "valuecount" or memory constraints)

example request:

{
 "function": "Historian/Read",
 "id": 12345,
 "variable": "New Variable",
 "valuecount": 100,
 "start": "2021-04-20T11:30:00Z",
 "stop": "2021-04-20T11:30:10Z",
 "resolution": "second",
 "aggregate": "avg"
}


example response:

{
 "function": "Historian/Read",
  "id": 12345,
  "status": 0,
  "variable": "New Variable",
  "values": [
   { "quality": 0, "time": "2021-04-20T11:30:00Z", "value": 10 },
   { "quality": 0, "time": "2021-04-20T11:30:02Z", "value": 11 },
   { "quality": 0, "time": "2021-04-20T11:30:04Z", "value": 12 },
   { "quality": 0, "time": "2021-04-20T11:30:06Z", "value": 13 },
   { "quality": 0, "time": "2021-04-20T11:30:08Z", "value": 14 },
   { "quality": 0, "time": "2021-04-20T11:30:10Z", "value": 15 },
  ],
 "blocked": false
}


Function "Historian/Write"

Writes historical values. The Historian only supports adding values in sequential order. Values that are passed out of sequence are silently ignored.

Additional request properties:

• "variable": string, required, name of the historian variable to write
• "values": array of objects, required, values to write (documented below)

Notes:

• For variable groups, each element of "values" has an object as "value", which maps subvariable names to values

Additional response properties:

• "variable": string, copied from request

example request:

{
 "function": "Historian/Write",
 "id": 12345,
 "variable": "New Variable",
 "values": [
  { "quality": 0, "time": "2021-04-20T11:30:00Z", "value": 10 },
  { "quality": 0, "time": "2021-04-20T11:30:02Z", "value": 11 },
  { "quality": 0, "time": "2021-04-20T11:30:04Z", "value": 12 },
  { "quality": 0, "time": "2021-04-20T11:30:06Z", "value": 13 },
  { "quality": 0, "time": "2021-04-20T11:30:08Z", "value": 14 },
  { "quality": 0, "time": "2021-04-20T11:30:10Z", "value": 15 },
 ]
}


example response:/

{
 "function": "Historian/Write",
 "id": 12345,
 "status": 0,
 "variable": "New Variable"
}


Function "Historian/AddVariable"

Adds a new variable to the Historian. Variables are identified by a unique name. Calling this function with a name that already exists allows changing some properties. When trying to change properties that are not changeable (especially anything that affects file storage format), an error occurs.

Additional request properties:

• "variable": object, required, describes the variable to add/modify (documented below)

Additional response properties:

• "variable": string, the variable name, copied from request

example request:

{
 "function": "Historian/AddVariable",
 "id": 12345,
 "variable":
 {
  "name": "New Variable",
  "type": "UInt16",
  "enabled": true,
  "opc_enabled": true,
  "opc_conn": "S7-1500",
  "opc_variable": "Datablocks.OPC_DB.Temperature",
  "opc_resolution": "second",
  "file_save": false,
  "mem_size": 100
 }
}

example response:

{
 "function": "Historian/AddVariable",
 "id": 12345,
 "status": 0,
 "variable": "New Variable"
}


Function "Historian/DeleteVariable"

Deletes a variable from the Historian. In case of file logging, the data files are not removed.

Additional request properties:

• "variable": string, required, the variable name

Additional response properties:

• "variable": string, the variable name, copied from request

example request:

{
 "function": "Historian/DeleteVariable",
 "id": 12345,
 "variable": "New Variable"
}


example response:

{
 "function": "Historian/DeleteVariable",
 "id": 12345,
 "status": 0,
 "variable": "New Variable"
}

Function "Historian/ReadVariable"

Reads a variable configuration from the Historian.

Additional request properties:

• "variable": string, required, the variable name

Additional response properties:

• "variable": object, the variable configuration (documented below)

example request:

{
 "function": "Historian/ReadVariable",
 "id": 12345,
 "variable": "New Variable"
}

example response:

{
 "function": "Historian/ReadVariable",
 "id": 12345,
 "status": 0,
 "variable":
 {
  "name": "New Variable",
  "type": "UInt16",
  "enabled": true,
  "opc_enabled": true,
  "opc_conn": "S7-1500",
  "opc_variable": "Datablocks.OPC_DB.Temperature",
  "opc_resolution": "second",
  "file_save": false,
  "mem_size": 100
 }
}


Function "Historian/ListVariables"

Reads the list of variable configurations from the Historian.

Additional request properties:

• "startoffset": number, optional, number of first returned variable; 0 if not given
• "variablecount": number, optional, maximum number of variables to return, 100 if not given

Additional response properties:

• "variables": array of object, the variable configurations (documented below)
• "blocked": boolean, true if more variables exist than could be returned in this answer (limited by "variablecount" or memory constraints)

example request:

{
 "function": "Historian/ListVariables",
 "id": 12345,
 "startoffset": 0,
 "variablecount": 100
}


example response:

{
 "function": "Historian/ListVariables",
 "id": 12345,
 "status": 0,
 "variables": [
 {
  "name": "New Variable",
  "type": "UInt16",
  "enabled": true,
  "opc_enabled": true,
  "opc_conn": "S7-1500",
  "opc_variable": "Datablocks.OPC_DB.Temperature",
  "opc_resolution": "second",
  "file_save": false,
  "mem_size": 100
 }
 ],
 "blocked": false
}

Function "Historian/ReadGlobalSettings"

Reads the global settings object of the historian

Additional request properties:

• none

Additional response properties:

• "mindiskspace": number, minimum free disk space (in MiB)

example request:

{
 "function": "Historian/ReadGlobalSettings",
 "id": 12345
}


example response:

{
 "function": "Historian/ReadGlobalSettings",
 "id": 12345,
 "status": 0,
 "mindiskspace": 1000
}


Function "Historian/WriteGlobalSettings"

Writes the global settings object of the historian

Additional request properties:

• "mindiskspace": number, minimum free disk space (in MiB)

Additional response properties:

• none

example request:

{
 "function": "Historian/WriteGlobalSettings",
 "id": 12345,
 "mindiskspace": 1000
}


example response:

{
 "function": "Historian/WriteGlobalSettings",
 "id": 12345,
 "status": 0
}


Function "Historian/ReadChangeTimestamp"

Reads the timestamp of the last historian variable change (addition, modification or deletion).

Additional request properties:

• none

Additional response properties:

• "time": string, ISO-8601-formatted timestamp (documented below)

example request: {
 "function": "Historian/ReadChangeTimestamp",
 "id": 12345
}
example response: {
 "function": "Historian/ReadChangeTimestamp",
 "id": 12345,
 "status": 0,
 "time": "2021-04-20T11:30:00Z"
}


Function "Historian/DiagVariable"

Reads diagnostic information for a historian variable.

Additional request properties:

• "variable": string, required, the variable name

Additional response properties:

• "variable": string, the variable name, copied from request
• "starttime": string, ISO-8601-formatted timestamp (documented below), timestamp of oldest available value
• "currenttime": string, ISO-8601-formatted timestamp (documented below), timestamp of most recent value
• "currentquality": number, quality code of the most recent value (0 is OK, more values are documented below)
• "writeerror": number, error code of the most recent disk write operation (0 is OK, more values are documented below)

example request:

{
 "function": "Historian/DiagVariable",
 "id": 12345,
 "variable": "New Variable"
}


example response:

{
 "function": "Historian/DiagVariable",
 "id": 12345,
 "status": 0,
 "variable": "New Variable",
 "starttime": "2021-04-20T11:30:00Z",
 "currenttime": "2021-04-20T11:30:10Z",
 "currentquality": 0
}


Function "Historian/ReadStruct"

Reads structure information for a historian variable. Can be used to decode structured data.

Additional request properties:

• "variable": string, required, the variable name
• "structname": string, required, the structure name

Additional response properties:

• "variable": string, the variable name, copied from request
• "structname": string, the structure name, copied from request
• "structcomment": string, optional, the structure comment (if present)
• "structdata": array of objects, the structure elements (documented below)

example request:

{
 "function": "Historian/ReadStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}


example response:

{
 "function": "Historian/ReadStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure",
 "structcomment": "commment text ...",
 "structdata": [
  {
   "name": "element 1",
   "type": "uint8",
   "arraylength": 10
  },
  {
   "name": "element 2",
   "type": "uint32"
  }
 ]
}


Function "Historian/WriteStruct"

Writes structure information for a historian variable. The Historian doesn't use this, but it can be read back via "Historian/ReadStruct".

Additional request properties:

• "variable": string, required, the variable name
• "structname": string, required, the structure name
• "structcomment": string, optional, the structure comment
• "structdata": array of objects, the structure elements (documented below)

Additional response properties:

• "variable": string, the variable name, copied from request
• "structname": string, the structure name, copied from request

example request:

{
 "function": "Historian/WriteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure",
 "structcomment": "commment text ...",
 "structdata": [
  {
   "name": "element 1",
   "type": "uint8",
   "arraylength": 10
  },
  {
   "name": "element 2",
   "type": "uint32"
  }
 ]
}


example response:

{
 "function": "Historian/WriteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}


Historian/ListStructs

Lists structure information for a historian variable.

Additional request properties:

• "variable": string, required, the variable name
• "startoffset": number, optional, the start offset; 0 if not given

Additional response properties:

• "variable": string, the variable name, copied from request
• "structs": array of objects:
  • "structname": string, the structure name
  • "structcomment": string, optional, the structure comment (if present)
  • "structdata": array of objects, the structure elements (documented below)
• "blocked": boolean, true if more structures exist than could be returned in this answer (limited by memory constraints)

example request:

{
 "function": "Historian/ListStructs",
 "id": 12345,
 "variable": "New Variable",
 "startoffset": 0
}


example response:

{
 "function": "Historian/ListStructs",
 "id": 12345,
 "variable": "New Variable",
 "structs": [
  {
   "structname": "New Structure",
   "structcomment": "commment text ...",
   "structdata": [
    {
     "name": "element 1",
     "type": "uint8",
     "arraylength": 10
    },
    {
     "name": "element 2",
     "type": "uint32"
    }
   ]
  }
 ]
}


Function "Historian/DeleteStruct"

Deletes structure information for a historian variable.

Additional request properties:

• "variable": string, required, the variable name
• "structname": string, optional, the structure name; if not given, all structures are deleted

Additional response properties:

• "variable": string, the variable name, copied from request
• "structname": string, the structure name, copied from request (if present)

example request:

{
 "function": "Historian/DeleteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}


example response:

{
 "function": "Historian/DeleteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}


value objects

properties:

• "quality": number, optional, quality code of the value, 0 if not given (0 is OK, more values are documented below)
• "time": string, optional, ISO-8601-formatted timestamp (documented below) current time if not given
• "value": any type, data value; format depends on data type of variable
• boolean: boolean
• int8/16/32/64, uint8/16/32/64: number, fractional values not allowed
• float, double: number, optinally including fractions
• string: string
• timestamp: string (ISO-8601 time format)
• structure: array of numbers (0-255), binary structure data
• or an array of the values above

example:

{ "quality": 0, "time": "2021-04-20T11:30:00Z", "value": 10 }


variable object

general properties:

• "name": string, required, unique name of the variable
• "type": string, optional, data type of the variable data (documented below)
• "structname": string, required if "type" is "structure", name of structure; ignored otherwise
• "arraylength": number, optional, length of array; if not given, 1 is assumed
• "elementlength": number, required if "type" is "string" or "structure" length of one array element, given in bytes; ignored otherwise
• "enabled": boolean, optional, true if variable is enabled (uses memory and license), false if variable is disabled (doesn't work, does not use memory or license, can be reenabled if needed); default false
• "sub_variables": array of object, required unless "type" is given, list of sub variables to combine in one historian variable
  • "name": string, required, unique name of the variable
  • "type": string, required, data type of the variable data (documented below)
    Note: "structure" is not supoprted
  • "elementlength": number, required if "type" is "string" or "structure" length of one array element, given in bytes; ignored otherwise
  • "opc_conn": string, required if "opc_enabled" is true, name of connection to read from
  • "opc_group": string, optional, group name of connection to read from
  • "opc_variable": string, required if "opc_enabled" is true, name of variable to read from

properties for OPC data acquisation:

• "opc_enabled": boolean, optional, true if OPC data acquisation is enabled; default false
• "opc_conn": string, required if "opc_enabled" is true and "type" is given, name of connection to read from
• "opc_group": string, optional, group name of connection to read from
• "opc_variable": string, required if "opc_enabled" is true and "type" is given, name of variable to read from
• "opc_resolution": string, required if "opc_enabled" is true, resolution for OPC reading (documented below)

properties for data storage:

• "file_save": boolean, optional, true to save to file; default false
• "aggregates": array of string, optional, list of aggregates to save (documented below)
• "aggregate_calcoffset": number, optional, byte-offset (if "type" is "structure") or index (if "type" is a simple type and "arraylength" is > 1) of the data element that is used for aggregate calculations; default 0
• "aggregate_type": string, optional, data type used for aggregate calculation (if "type" is "structure"); default uint8; ignored otherwise
• "file_resolution": string, required if "file_save" is true, time after which a new data file is started (documented below)
• "file_maxcount": number, optional, maximum number of data files to keep; default 0 = unlimited
• "file_mindiskspace": number, optional, minimum free disk space (in MiB); default 0 = use global setting
• "mem_size": number, required if "file_save" is false, size of in-memory storage (in MiB)

example:

{
 "name": "New Variable",
 "type": "uint16",
 "enabled": true,
 "opc_enabled": true,
 "opc_conn": "S7-1500",
 "opc_variable": "Datablocks.OPC_DB.Temperature",
 "opc_resolution": "second",
 "file_save": false,
 "mem_size": 100
}


structure element object

properties:

• "name": string, required, the element name
• "comment": string, optional, the element comment
• "type": string, required, data type of the structure element (documented below)
• "structname": string, required if "type" is "structure", name of structure; ignored otherwise
• "arraylength": number, optional, length of array; if not given, 1 is assumed
• "elementlength": number, optional; if "type" is "string": maximum length of one string, given in bytes, no fixed length if not given or 0; ignored otherwise
• "lengthfieldname": string, optional, the element name of the element that gives a dynamic array length; this oferrides "arraylength"; the length field must have a numeric type
• "switchfieldname": string, optional, the element name of the element that marks this element as "present" or "absent"; the switch fiels must have a numeric or boolean type
• "switchvalue": number or boolean, optional, the value of the "switchfield" that marks this element as "present"
• "packed": boolean, optional, true if multiple boolean fields should be packed together in one byte; default false
• "padding": boolean, true if this field is a padding field that contains no useful data; default false

structure layout rules:

• "boolean" elements occupy 1 bit.
• all numeric elements occupy as many bytes as needed (documented below).
• "string" elements have a 4-byte length element followed by the character data (usually UTF-8 encoded). If "elementlength" is given, the character data are padded to this length with "\x00" bytes to ensure a fixed structure layout. Othweise no implicit padding exists.
• "time" elements occupy 12 bytes: 8 byte UNIX-Timestamp (seconds since 1970-01-01 00:00:00 UTC) and 4 byte Nanoseconds
• "structure" elements occupy as many bytes as required for their encoding
• all elements except "boolean" start at a byte boundary (align 1). Padding bytes (if required) must be specified explicitly via "padding": true
• "boolean" elements start at a byte boundary if:
  • they have an "arraylength" other than 1 or a "lengthfieldname"
  • and "packed" is false (or unspecified)
• "boolean" elements are packed in one byte if:
  • the "arraylength" is unspecified or 1 and no "lengthfieldname" exists
  • or "packed" is true
• If required, implicit padding bits are inserted after "boolean" elements.

resolution values

• "maximum": save/return all available values
• "second": save/return one value per second
• "minute": save/return one value per minute
• "hour": save/return one value per hour
• "day": save/return one value per day
• "week": save/return one value per week
• "month": save/return one value per month
• "year": save/return one value per year

aggregate values

• "value": return actual values (for lower resolutions: firat value of the interval)
• "min": return minimum value in given interval
• "max": return maximum value in given interval
• "avg": return average value in given interval
• "count": return number of saved value in given interval

ISO-8601 time format

note: this is only a subset of ISO-8601

2021-04-20T11:30:10.123+00:00
^    ^  ^  ^  ^  ^  ^  ^------- optional Timezone offset, allowed are "Z" (UTC)
|    |  |  |  |  |  |           or a zone difference in hours (and optionally
|    |  |  |  |  |  |           minutes), positive is east, UTC if not given
|    |  |  |  |  |  +---------- optional second fractions, up to 9 digits are
|    |  |  |  |  |              supported
|    |  |  |  |  +------------- second, always 2 digits
|    |  |  |  +---------------- minute, always 2 digits
|    |  |  +------------------- hour, always 2 digits, 24-hour format
|    |  +---------------------- day, always 2 digits
|    +------------------------- month, always 2 digits
+------------------------------ year, always 4 digits


Other ISO-8601 formats (e.g. week numbers, day-of-year, ...) are not supported. All returned timestamp values are in UTC.

Data types

• "boolean": truth value (false or true)
• "uint8", "uint16", "uint32", "uint64": unsigned integral types with 8-64 bit (1-8 bytes)
• "int8", "int16", "int32", "int64": signed integral types with 8-64 bit (1-8 bytes)
• "float", "double": IEEE-floating-point values with 32 or 64 bit (4 or 8 bytes)
• "string": character string, UTF-8 encoded
• "time": timestamp, transferred on JSON API as ISO-8601 string
• "structure": structured data type, transferred on JSON API as array of uint8

Status codes

• 0: OK
• 102: No Variable - the given variable name was not found
• 103: Out of Memory - a memory allocation failed
• 108: Not Ready - a valid but unimplemented function was called
• 143: Bad Opcode - an unknown function was called
• 144: Bad Length - a value given has a wrong length
• 1304: Disk Full - no space left on disk, or the allocated quota is exceeded
• 1307: Access Denied - the requested operation is not allowed
• 1308: No write access - the write operation failed
• 1319: Invalid Value - a value given is wrong
• 1324: License Limit - the operation would exceed a license limit

Other numbers signal an unspecified or undocumented error. Please contact TANI support in such cases.

Quality codes

• 0: Good - variable value is valid
• 1: Configuration Error - a configuration problem exists (e.g a missing connection)
• 2: Not Connected - the connection could not be established
• 3: Device Failure - the communication target device failed
• 4: Sensor Failure - the value to read is invalid or missing
• 5: Last Known Value - a temporary communication problem prevents fetching new values
• 6: Communication Failure - an unknown communication error occurted (e.g. wrong protocol)
• 7: Out Of Service - the communication target is temporarily not available
• 8: Waiting for Initial Data - the state after connection establish until the first valid data arrives
• 9: Write Protected - (for write operation only) the value can not be written
• 10: Corrected Value - the value was abnormal or out of range and has been corrected
• 12: Read Protected - (for read operations only) the value can not be read
• 13: Convert Failed - a type conversion failed
• 14: Overload - not enough resources to process the request (e.g out of memory)

Other numbers signal an unspecified or undocumented error. Please contact TANI support in such cases.