alarm.history.multi

The alarm.history.multi command is used to obtain historical alarm states for multiple alarms for a thing. It is possible to request Alarm history by specifying:

A last number of records
A time period defined by the "last period of time" style query (For example, last "24h")
A definite time period using a start and an 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

{ 
    "1": { 
        "command": "alarm.history.multi", 
        "params": { 
            "thingKey": "mything", 
            "keys": ["myalarm1", "myalarm2"], 
            "records": 2 
        } 
    }

TR50 Request - Last period of time request

{ 
    "1": { 
        "command": "alarm.history.multi", 
        "params": { 
            "thingKey": "mything", 
            "keys": ["myalarm1", "myalarm2"], 
            "last": "24h"
        } 
    }

TR50 Request - Definite time period request

{ 
    "1": { 
        "command": "alarm.history.multi", 
        "params": { 
            "thingKey": "mything", 
            "keys": ["myalarm1", "myalarm2"], 
            "last": "24h"
        } 
    }

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

Request Parameters

Name	Type	Required	Description
thingKey	String	Yes*	The thing key.
thingid	String		Id of the thing
esn	String		ESN of the connection.
iccid	String		ICCID of the connection.
imei	String		IMEI of the connection.
imsi	String		IMSI of the connection.
meid	String		MEID of the connection.
msisdn	String		MSISDN of the connection.
One of the above parameters is required to identify the thing. If omitted, the thingKey associated with your session will be used.*
keys	String Array	Yes	The keys for the alarms to be queried.
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 the last period of time request this specifies the last X amount of time in nanoseconds (ns), microseconds (us), milliseconds (ms), seconds (s), minutes (m) or hours (h).
records	Integer		When doing the last number of records request this specifies the number of records to return.A value of zero returns 5000 records.

If the command is sent successfully a success message and the alarm state values found are returned. Otherwise, an error and error message will be returned.

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.

TR50 Response

{ 
    "1": { 
        "success": true, 
        "params": { 
            "values": [ 
                { 
                    "key": "myalarm1", 
                    "state": 1, 
                    "duration": 274, 
                    "msg": "TEST", 
                    "ts": "2018-04-02T23:13:46Z" 
                }, 
                { 
                    "key": "myalarm2", 
                    "state": 2, 
                    "duration": 0, 
                    "msg": "1", 
                    "ts": "2018-04-02T23:18:20Z" 
                } 
       ] 
    } 
  } 
}

Response Parameters

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

If split is false, the response parameters are:

Name	Type	Description
key	String	The key associated with the alarm record.
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
keys	Array	Array of alarm keys
timestamps	Array	Array of timestamps
corrId	String	The correlation identifier associated with the alarm.
states	Array	Array of integer states
messages	Array	Array of messages.

The alarm.history.multi 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.