alarm.history

The alarm.history command is used to obtain historical alarm states for a thing.

Alarm history can be requested by specifying:

  • A last number of records
  • A time period defined by the "last period of time" style query (last "24h", etc.)
  • A definite time period using a start and end date

If more than one type of request is passed as a parameter, "records" will have priority over "last", and "last" will have priority over "start" & "end".

TR50 Request 
// Last number of records request
{
  "cmd": {
    "command": "alarm.history",
    "params": {
      "thingKey": "mything",
      "key": "myalarm",
      "records": 100
    }
  }
}
// Last period of time request
{
  "cmd": {
    "command": "alarm.history",
    "params": {
      "thingKey": "mything",
      "key": "myalarm",
      "last": "24h"
    }
  }
}
// Definite time period request
{
  "cmd": {
    "command": "alarm.history",
    "params": {
      "thingKey": "mything",
      "key": "myalarm",
      "start": "2014-01-01T00:00:00Z",
      "end": "2014-01-31T23:59:59Z"
    }
  }
}

Request Parameters

Name Type Required Description
thingKey String Yes* Key of the thing.
thingId Idof the thing.
esn String ESN of the thing.
iccid String ICCID of the thing.
imei String IMEI of the thing.
imsi String IMSI of the thing.
meid String MEID of the thing.
msisdn String MSISDN of the thing.
*One of the above parameters is required to identify the thing. The parameter identifies the thing to which the alarm data is associated. If omitted, the thingKey associated with your session will be used.
key String Yes The key for the alarm that you wish to retrieve.
split Bool Set to true if you want the timestamp and value fields to be split into two arrays
start String When doing a definite time period request this is the timestamp for the start of the specified time window.
end String When doing a definite time period request this is the timestamp for the end of the specified time window. If start is specified, but end is not specified, end will use the current time as the default value.
last String When doing a last period of time request this specifies the last X amount of time in seconds (s), minutes (m), hours (h), or days (d).
records Integer When doing a last number of records request this specifies the number of records to return. A value of zero returns 5000 records.
returnIds Bool Returns the id of the alarm

In a definite time period request: If the start time is after the end time, the system will swap the values.

The number of records returned is limited to 5000 by the deviceWISE Cloud. If your query returns more results than the limit of the deviceWISE Cloud, you should shorten your time window or lower the number of records you are requesting.

If the command is sent successfully a success message and the property value are returned. Otherwise, an error and error message will be returned.

TR50 Response 
{
  "cmd": {
    "success": true,
    "params": {
      "values": [
        {
          "state": 1,
          "duration": 500,
          "msg": "Message.",
          "ts": "2006-01-02T15:04:05Z07:00"
        }
      ]
    }
  }
}
// "split" response example
{
  "cmd": {
    "success": true,
    "params": {
      "timestamps": [
        "2006-01-02T15:04:05Z07:00"
      ],
      "states": [
        1
      ],
      "messages": [
        "Message."
      ],
      "corrIds": [
        ""
      ]
    }
  }
}

The response parameters from alarm.history depends on the request parameter split.

  • If split is false, the response parameters are:
Name Type Description
id String Id of the alarm (if returnIds set to true)
ts String Timestamp for the given value.
msg String The message associated with the alarm state value.
corrId String The correlation identifier associated with the alarm.
state Integer The state associated with the alarm state value.
duration Integer The duration associated with the alarm state value.
lat Float Latitude coordinate associated with the alarm state value.
lng Float Longitude coordinate associated with the alarm state value.

Duration is calculated as the difference between an alarm state's time stamp and the next state's time stamp. This means that the most recent state will have a duration of 0; it will have a value when the next alarm state gets published.

  • If split is true, the response parameters are:
Name Type Description
ids Array Array of ids (if returnIds set to true)
timestamps Array Array of timestamps
states Array Array of integer states
messages Array Array of messages.
corrIds Array Array of correlation IDs.

The alarm.history response can also contain the following key:

Name Type Description
truncated Boolean If this value is in the response, it will be true. It is defined if the number of possible records is equal to or greater than the maximum configured.