History Format

Structure

A single history includes a key, a packet of subject data written when the history was created, and a series of events.

History Properties

{
  "id": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "labela": "Licence",
  "labelb": "1234-1234-1234-1234",
  "labelc": 1,
  "labeld": null,
  "labele": null,
  "created": 1432207945097,
  "lastupdated": 1486484182000,
  "subject": {...},
  "events": [
    {
      "timestamp": 1432207945163,
      "event": {...},
      "pos": [1,2],
      "fpos": [1,2]
    },
    {...}
  ],
  "fpos": [1,2]
  "sealed": false
}

id is a unique, internally-generated id for the history.

labela - labele are the unique user-generated key for the history.

created is the timestamp (in milliseconds) when the history was created.

lastupdated is the timestamp (in milliseconds) when the history last had an event added to it (this includes the event that sealed a history).

subject is the subject data packet that was supplied when the history was created.

events is an array of event objects in chronological order.

events[n].timestamp is the timestamp (in milliseconds) when the event was created.

events[n].event is the event data packet.

events[n].pos[0] is the event number in the whole history. 1 for the first event, 2 for the second event, and so on.

events[n].pos[1] is the total number of events in the history. In the example above there are two events in the history, and the event shown is number 1 of 2.

events[n].fpos[0] is the position of this event within the events that match the event filter.

events[n].fpos[1] is the total number of events in the history that match the filter.

fpos[0] is the position of this history within the histories that match the filter in a call to getHistories.

fpos[1] is the total number of histories that match the filter in a call to getHistories.

sealed is a boolean flag that indicates whether the history has been switched into read-only mode.

The result of a successful call to getHistory() has a very similar format to the object shown above except that the "label" keys are excluded.

Event Properties

The data stored in event objects is completely arbitrary. The conventions we use, and recommend, are discussed in the Conventions - Standardising History Data knowledge base article.