Data model

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

A host may be bound to a prototype, set up in a.fa.se. From the prototype it is possible to determine which host fulfills a certain role, even when devices are replaced.

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.

Prototypes

Prototypes from a.fa.se define the roles that devices/hosts fulfill.

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

{
  "id": "9e222f14-5b1f-4790-bcac-afa8a675b592",
  "site": "S:t Larsgatan",
  "name": "Smartbox CDEF",
  "host": "d0ff50abcdef",
}
  • id is the unique identifier of the prototype
  • site the location of the device, is not guaranteed to be permanent or unique.
  • name the role of the device, is not guaranteed to be permanent or unique.
  • host is the identifier of the host bound to this prototype

To keep a permanent reference to a device, store a reference to the prototype id instead of the host. If a device is replaced the host will change, but the prototype will be bound to the new host.

The list of prototypes should be regularly checked to determine which host is currently bound to a prototype.

The list of prototypes is better suited than the list of hosts for presenting a device selection in a GUI. The separate site and name information gives more options for presenting their names, and the prototype id is available.

Hosts

Devices in a.fa.se are referred to as hosts in the API.

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 alarms trigger or when they are resolved. Its JSON representation is an object:

{
  "eventid": 4711,
  "host": "d0ff50abcdef",
  "key": "modbus.corrigo2.regin_ch.2.24",
  "value": "OK",
  "clock": 1421944072,
  "description": "Circulation pump not running",
  "severity": [3, "C-Larm"],
  "acknowledgements": [ ... ],
  "problem_id": 4707
}
  • 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
  • severity is a pair [num, "text"]:
    • the number part is priority (3 == lowest, 5 == highest)
    • text is a textual description ("A-Larm", "B-Larm", "C-Larm")
  • acknowledgements is an array of acknowledgement messages for this event. The array may be empty.
  • problem_id is the identifier of the problem event that corresponds to an OK event. This field is absent for problem events, or if the OK event is the first event for the trigger.

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")