Data model

Gathered data or settings are associated with sensors and configurable items. Each sensor or configurable item belongs to a host.

To uniquely identify a sensor or configuration item you must specify its key and its host.

Sensors and configurable values have a history of previous values. Configurable values also have information about the latest configuration change request recieved by the API.

Sensors may have an associated alarm which produces alarm events. Alarm events may have one or more acknowledgements.

All times are represented in Unix-time, which means the number of seconds passed since 1970-01-01 00:00:00 UTC.

Hosts

The JSON representation of a host is an object like this:

{
  "name": "Box_cdef",
  "host": "d0ff50abcdef",
  "lastclock": 1416586490,
  "items": [ ... ],
  "ip": "10.0.0.1"
}
  • host is the unique identifier of a host, used for the {host} part of request paths.
  • name is not guaranteed to be permanent or unique
  • lastclock indicates the latest value measured from this host. It may be null if there has not yet been any data collected
  • items is an array of the sensors and configurable items belonging to the host. It is left out in some cases.

Sensors

The JSON representation of a sensor data is an object like this:

{
  "name": "pump 3.40004 BT1 Outdoor temp",
  "unit": "degC",
  "lastclock": 1416586545,
  "lastvalue": 2.4,
  "key": "modbus.pump.F1345.3.40004",
  "configurable": false
}
  • key is unique per host, but is not necessarily globally unique. It is used for the {item} part of request paths.
  • name is not guaranteed to be permanent or unique
  • unit specifies the meaning of the value
  • configurable is false for sensors
  • lastvalue is the latest sensor value, may be null if there has never been any data collected
  • lastclock indicates time when lastvalue was measured, may be null if there has never been any data collected

Configurable items

The JSON representation of a configurable item is just like a sensor, except its configurable value is true, and it has a config property:

{
  "name": "pump 3.47024 Own Curve P3",
  "unit": "degC",
  "lastclock": 1416586606,
  "config": {
    "audit": [],
    "target": null,
    "lastclock": null,
    "status": "SUCCESS",
    "expected": null
  },
  "lastvalue": 46,
  "key": "modbus.pump.F1345.3.47024",
  "configurable": true
}
  • The config object contains information about the latest configuration change received by the API. Note that this config change has not necessarily been successfully applied.
  • target is the desired new value, may be null if no configuration request has been made
  • expected is the value expected before the change, may be null if no configuration request has been made
  • audit is an array of strings with information identifying who or what initiated the change
  • lastclock indicates when this configuration change was received, may be null if no configuration request has been made
  • status is one of PENDING, SUCCESS, FAILED

History

The JSON representation of a sensor value history is an array:

[
  [1416586366, 2.2],
  [1416586426, 2.3],
  [1416586485, 2.3],
  [1416586545, 2.4],
  ...
]
  • History data is represented as pairs of earlier lastclock and lastvalue values.
  • The values are guaranteed to be in order, but there may be gaps in the data.

Trend

Trend data are collated series of data for an interval, representing the minimum, average, maximum for the period, as well as a count of samples.

The JSON representation is a time-series of objects:

[
  [1458763440, {"num": 60, "min": 0.1, "avg": 1.2, "max": 2.0}],
  [1458767040, {"num": 60, "min": 0.2, "avg": 1.2, "max": 2.0}],
  [1458770640, {"num": 55, "min": 0.2, "avg": 1.2, "max": 2.0}]
]

Trend data also comes in more specific calls that look exactly like the history data. See below for API call section.

Alarm events

Alarm events represent instances when alarm triggers or when they turn off. Its JSON representation is an object:

{
  "eventid": 4711,
  "host": "d0ff50abcdef",
  "key": "modbus.corrigo2.regin_ch.2.24",
  "value": "problem",
  "clock": 1421944072,
  "description": "Circulation pump not running",
  "severity": [3, "C-Larm"]
  "acknowledgements": [ ... ]
}
  • eventid is the unique identifier of an event, necessary for acknowledging an event
  • host is the unique identifier of a host, used for the {host} part of request paths.
  • key is unique per host, but is not necessarily globally unique. It is used for the {item} part of request paths.
  • value is the type of event, which may be:
    • problem indicating that the alarm was triggered
    • OK indicating that the problem is resolved
    • unknown in rare occasions when data is missing
  • clock indicates when the event occurred
  • description is a human readable description of the problem this event relates to
  • acknowledgements is an array of acknowledgement messages for this event. The array may be empty.
  • severity is a pair [num, "text"]:
    • numerical part is priority (3 == lowest, 5 == highest)
    • text is a textual description ("A-Larm", "B-Larm", "C-Larm")

Acknowledgements

Event acknowledgements can be used to document actions taken for an alarm. They are represented as a simple JSON object:

{
  "clock": 1421943944,
  "message": "Service technician dispatched"
}
  • clock indicates when the acknowledgement was made
  • message contains free-form text

Triggers

The JSON representation of a trigger data is an object like this:

{
  "triggerid": 17,
  "description": "Frost alarm",
  "hosts": [ ... ],
  "lastchange": 1421944072,
  "value": "OK",
  "severity": [5, "A-Larm"]
}
  • triggerid is an unique id of this trigger
  • description contains free-form text
  • hosts is an array of all hosts affected by this trigger
  • value is the current value of the trigger
  • lastchange is the timestamp the trigger last changed state
  • severity is a pair [num, "text"]:
    • numerical part is priority (3 == lowest, 5 == highest)
    • text is a textual description ("A-Larm", "B-Larm", "C-Larm")