Create alerts

Use the POST v1/alerts/inventory web service to create alerts for your account.

URI

https://<hostname>/ws/v1/alerts/inventory

API Usage

There are no parameters for the POST ws/v1/alerts/inventory API.

Specify an HTTP header of Content-Type: application/json and post json payload describing the alert or alerts.

Request Payload

To create multiple alerts, use a list syntax. For a single alert, the list syntax is not required.

[
	{ ...alert1 },
	{ ...alert2 },
	...
	{ ...alertN }
]

Successful Response

Upon success, the alert is returned. The returned alert may differ from the input alert because default values are supplied in the returned alert. A list response is returned whether the POST created single or multiple alerts.

{
	"count": N,
	"list" : [
		{ ...alert1 },
		{ ...alert2 },
		...
		{ ...alertN },
	]
}

Error Response

When creating multiple alerts, if any alert is successfully created, a response of 207 and error information for the failed responses are returned.

In the following example response payload, the second alert failed. The HTTP response is 207 because one alert (alert1) was created successfully, and the second item in the list has error values indicating the problem with the second alert (alert2).

{
	"count": N,
	"list": [
		{ ...alert1 },
		{ 
		"error_context": { ...alert2 },
		"error_message": "The error message",
		"error_status": 400
		},
		{ ...alertN }
	]
}

Sample Alert Definitions

The following sample payloads represent the different alert types.

DataPoint condition

DataPoint On Change

Device Excessive Disconnects

Device Name On Change

Device Offline

Dia channel data point condition match

Missing DataPoint

Missing DiaChannel DataPoint

Missing Smart Energy DataPoint

Smart energy data point condition match

Subscription Usage

XBeeNode Excessive Deactivations

XBeeNode Offline

Datapoint Condition

The following payload creates a DataPoint condition alert. This alert type fires when a data stream value matches the condition criteria.

Values:

scope.type: Always Resource.
scope.value: The stream with wildcard (*) for device id or path components.
timeout: Fire or reset if the value matches for this amount of time.
timeUnit: One of seconds, minutes, hours.
operator: One of <, <=, >, >=, =, <>.
type: One of string or numeric.
thresholdValue: The target value for the condition.

{
	"type": "DataPoint condition",
	"name": "Voltage check",
	"description": "Watch for low voltage on fleet vehicles",
	"scope": {
		"type": "Resource",
		"value": "*/drivestats/voltage"
	},
	"fire": {
		"parameters": {
		"operator": "<",
		"thresholdValue": "10",
		"timeUnit": "minutes",
		"timeout": "60",
		"type": "numeric"
		}
	},
	"reset": {
		"parameters": {
		"operator": ">=",
		"thresholdValue": "10",
		"timeUnit": "minutes",
		"timeout": "60",
		"type": "numeric"
		}
	}
}

Datapoint on Change

The following payload creates a DataPoint On Change alert. This alert type fires when a data stream value changes. Repeated uploads of the same value do not cause the alert to fire. This alert automatically resets when the data point value remains unchanged for 60 minutes.

The target data stream matches any device with a drivestats/voltage stream name.

Values:

scope.type: Always Resource.
scope.value: The stream with wildcard (*) for device id or path components.
timeout: Reset automatically if the value does not change for this amount of time.
timeUnit: One of seconds, minutes, hours.

{
	"type":"DataPoint On Change",
	"reset": {
		"parameters": {
			"timeout": "60",
			"timeUnit": "minutes"
		}
	},
	"scope": {
		"type":"Resource",
		"value":"*/drivestats/voltage"
	}
}

Device Excessive Disconnects

The following payload creates a Device Excessive Disconnects alert. This alert type fires when a device goes offline many times during a time period.

Values:

scope.type: One of Group or Device.
scope.value: If type is Group, then value is the full group path (with no leading slash). If type is Device, then value is the full device ID. If type is XBeeNode, then the value is the XBee node extended src address.
disconnectCount: Fires if the device disconnects more than this many times in the disconnectWindow
disconnectWindow: The period of time in minutes for which to count disconnects.
reconnectWindow: Resets when the device connects and stays connect for this number of minutes.

{
	"type":"Device Excessive Disconnects",
	"scope":{
		"type":"Device",
		"value":"00000000-00000000-000000FF-FF000000"
	},
	"fire":{
		"parameters":{
			"disconnectCount":"10",
			"disconnectWindow":"60"
		}
	},
	"reset":{
		"parameters":{
			"reconnectWindow":"30"
		}
	},
}

Device Name on Change

The following payload creates a Device Name on Change alert. This alert type fires when a device name changes. The alert does not fire when a device name is set on a device that has no name. The alert can reset automatically.

Values:

scope.type: One of Group or Device.
scope.value: If type is Group, then value is the full group path (with no leading slash). If type is Device, then value is the full device ID. If type is XBeeNode, then the value is the XBee node extended src address.
timeout: Reset automatically if the value does not change for this amount of time.
timeUnit: One of seconds, minutes, hours.

{
	"type":"Device Name On Change",
	"reset":{
		"parameters":{
			"timeout":"12",
			"timeUnit":"hours"
		}
	},
	"scope":{
		"type":"Group",
		"value":"Deployments/Europe/UK"
	}
}

Device Offline

The following payload creates a Device Offline alert. This alert type fires when a device disconnects for a period of time.

Values:

scope.type: One of Group or Device.
scope.value: If type is Group, then value is the full group path (with no leading slash). If type is Device, then value is the full device ID. If type is XBeeNode, then the value is the XBee node extended src address.
reconnectWindowDuration: Fires if the device does not reconnect within this number of minutes.
reset.disabled: Is set to true to cause this alert to not auto-reset. The default is false.

{
	"name":"Network offline",
	"type":"Device Offline",
	"description":"Detect if any midwest office networks are offline",
	"priority":"high",
	"fire":{
		"parameters":{
		"reconnectWindowDuration":"12"
		}
	},
	"reset": {
		"disabled": true
	},
	"scope": {
		"type":"Group",
		"value":"Stores/North America/Midwest"
	}
}

Dia Channel Datapoint Condition Match

The following payload creates a Dia channel data point condition match alert. This alert type fires when the value reported in a DIA channel matches the condition criteria.

Values:

scope.type: One of Group or Device.
scope.value: If type is Group, then value is the full group path (with no leading slash). If type is Device, then value is the full device ID. If type is XBeeNode, then the value is the XBee node extended src address.
channelName: The dia channel name or wildcard (*) for all channels.
instanceName: The dia channel instance name or wildcard (*) for all instances.
timeout: Fire or reset if the value matches for this amount of time.
timeUnit: One of seconds, minutes, hours.
operator: One of <, <=, >, >=, =, !=.
type: One of string or numeric.
thresholdValue: The target value for the condition.

{
	"type": "Dia channel data point condition match",
	"scope": {
		"type": "Group",
		"value": "New York/Sensors"
	},
	"fire": {
		"disabled": false,
		"parameters": {
			"channelName": "chan1",
			"instanceName": "stream",
			"operator": ">=",
			"thresholdValue": "25",
			"timeUnit": "seconds",
			"timeout": "30",
			"type": "numeric"
		}
	},
	"reset": {
		"disabled": false,
		"parameters": {
			"channelName": "chan1",
			"instanceName": "stream",
			"operator": "<",
			"thresholdValue": "25",
			"timeUnit": "seconds",
			"timeout": "30",
			"type": "numeric"
		}
	}
}

Missing Datapoint

The following payload creates a Missing DataPoint alert. This alert type fires when the interval between data point uploads or data point measurements exceeds the requested time. Devices may cache data uploads, uploading infrequently (for example 24 hours), but uploading many measurements (for example, 24 total measurements if sampling every hour). This alert automatically resets when data is reported.

Values:

scope.type: Always Resource.
scope.value: The stream with wildcard (*) for device id or path components.
uploadInterval: Fire if the amount of time between uploads exceeds this interval.
uploadTimeUnit: The units of the uploadInterval value—seconds, minutes, hours.
readingInterval: Fire if the amount of time between individual samples/reading exceeds this interval. readingInterval}} value—seconds, minutes, hours.
reset.disabled: Resets automatically when data is reported, you can disable this by specifying true.

{
	"name":"Fleet sensor not reporting",
	"type":"Missing DataPoint",
	"scope":{
		"type":"Resource",
		"value":"*/drivestats/voltage"
	},
	"fire":{
		"parameters":{
			"readingTimeUnit":"seconds",
			"uploadTimeUnit":"minutes",
			"uploadInterval":"1",
			"readingInterval":"5"
		}
	},
	"reset": {
		"disabled": true
	}
}

Missing Dia Channel Datapoint

The following payload creates a Missing DiaChannel DataPoint alert. This alert type fires when the interval between data point uploads or data point measurements exceeds the requested time. Devices may cache data uploads, uploading infrequently (for example 24 hours), but uploading many measurements (for example, 24 total measurements if sampling every hour).

This alert automatically resets when data is reported.

Values:

scope.type: One of Group or Device.
scope.value: If type is Group, then value is the full group path (with no leading slash). If type is Device, then value is the full device ID. If type is XBeeNode, then the value is the XBee node extended src address.
uploadInterval: Fire if the amount of time between uploads exceeds this interval.
uploadTimeUnit: The units of the uploadInterval value—seconds, minutes, hours.
readingInterval: Fire if the amount of time between individual samples/reading exceeds this interval. readingInterval}} value—seconds, minutes, hours.
channelName: The dia channel name or wildcard (*) for all channels.
instanceName: The dia channel instance name or wildcard (*) for all instances.
reset.disabled: Resets automatically when data is reported, you can disable this by specifying true.

{
	"type": "Missing DiaChannel DataPoint",
	"scope": {
		"type": "Device",
		"value": "00000000-00000000-000000FF-FF000000"
	},
	"fire": {
		"parameters": {
			"channelName": "chan1",
			"instanceName": "*",
			"readingInterval": "10",
			"readingTimeUnit": "minutes",
			"uploadInterval": "1",
			"uploadTimeUnit": "hours"
		}
	}
}

Missing Smart Energy Datapoint

The following payload creates a Missing Smart Energy DataPoint alert. This alert type fires when the interval between data point uploads or data point measurements exceeds the requested time. Devices may cache data uploads, uploading infrequently (for example 24 hours), but uploading many measurements (for example, 24 total measurements if sampling every hour).

This alert automatically resets when data is reported.

Values:

scope.type: One of Group, Device, or XBeeNode.
scope.value: If type is Group, then value is the full group path (with no leading slash). If type is Device, then value is the full device ID. If type is XBeeNode, then the value is the XBee node extended src address.
uploadInterval: Fire if the amount of time between uploads exceeds this interval.
uploadTimeUnit: The units of the uploadInterval value—seconds, minutes, hours.
readingInterval: Fire if the amount of time between individual samples/reading exceeds this interval. readingInterval}} value—seconds, minutes, hours.
attributeId: The XBee attribute id.
clusterId: The XBee cluster id.
clusterType: The XBee cluster type.
endpointId: The XBee endpoint id.
reset.disabled: Resets automatically when data is reported, you can disable this by specifying true.

{
	"type": "Missing Smart Energy DataPoint",
	"scope": {
		"type": "Group",
		"value": "New York/Sensors"
	},
	"fire": {
		"parameters": {
			"attributeId": "1",
			"clusterId": "1794",
			"clusterType": "0",
			"endpointId": "1",
			"readingInterval": "1",
			"readingTimeUnit": "hours",
			"uploadInterval": "24",
			"uploadTimeUnit": "hours"
		}
	},
}

Smart Energy Datapoint Condition Match

The following payload creates a Smart energy data point condition match alert. This alert type fires when the value reported in a DIA channel matches the condition criteria.

Values:

scope.type: One of Group, Device, or XBeeNode.
scope.value: If type is Group, then value is the full group path (with no leading slash). If type is Device, then value is the full device ID. If type is XBeeNode, then the value is the XBee node extended src address.
timeout: Fire or reset if the value matches for this amount of time.
timeUnit: One of seconds, minutes, hours.
operator: One of <, <=, >, >=, =, !=.
type: One of string or numeric.
thresholdValue: The target value for the condition.
attributeId: The XBee attribute id.
clusterId: The XBee cluster id.
clusterType: The XBee cluster type.
endpointId: The XBee endpoint id.

{
	"type": "Smart energy data point condition match",
	"scope": {
		"type": "Group",
		"value": ""
	},
	"fire": {
		"disabled": false,
		"parameters": {
			"attributeId": "1",
			"clusterId": "1794",
			"clusterType": "0",
			"endpointId": "1",
			"thresholdValue": "50",
			"timeUnit": "seconds",
			"timeout": "1",
			"type": "numeric"
		}
	},
	"reset": {
		"disabled": false,
		"parameters": {
			"attributeId": "1",
			"clusterId": "1794",
			"clusterType": "0",
			"endpointId": "1",
			"thresholdValue": "49",
			"timeUnit": "seconds",
			"timeout": "1",
			"type": "numeric"
		}
	}
}

Subscription Usage

The following payload creates a Subscription Usage alert. This alert type fires when the account uses 95 percent of the devices available for use based on the Remote Manager subscription.

There are a wide variety of values for the parameters of this alert. It is recommended that an alert is created with the Remote Manager Web UI, and you determine the acceptable values from a call to GET ws/v1/alerts/inventory.

Values:

scope.type: Always Global.
scope.value: Always empty string.
svcId: The service identifier.
unit: The unit being checked.
metric: The metric for the subscription data.
thresholdValue: The target value for the condition.

{
	"name":"Too many devices",
	"type":"Subscription Usage",
	"scope":{
		"type":"Global",
		"value":""
	},
	"fire":{
		"parameters":{
			"svcId":"3",
			"unit":"%",
			"metric":"devices",
			"thresholdValue":"90"
		}
	}
}

XbeeNode Excessive Deactivations

The following payload creates an XBeeNode Excessive Deactivations alert. This alert type fires when a device goes offline many times during a time period.

Values:

scope.type: One of Group, Device, or XBeeNode.
scope.value: If type is Group, then value is the full group path (with no leading slash). If type is Device, then value is the full device ID. If type is XBeeNode, then the value is the XBee node extended src address.
deactivationCount: Fires if the device deactivates more than this many times in the deactivationWindow
deactivationWindow: The period of time in minutes for which to count deactivations.
activationWindow: Resets when the Xbee node activates and stays activated for this number of minutes.

{
	"type":"XBeeNode Excessive Deactivations",
	"scope":{
		"type":"XbeeNode",
		"value":"00:00:00:00:00:00:00:00"
	},
	"fire":{
		"parameters":{
			"deactivationWindow":"5",
			"deactivationCount":"1"
		}
	},
	"reset":{
		"parameters":{
			"activationWindow":"1"
		}
	}
}

Xbeenode Offline

The following payload creates an XBeeNode Offline alert. This alert type fires when an XBee node is offline for a period of time.

Values:

scope.type: One of Group, Device, or XBeeNode.
scope.value: If type is Group, then value is the full group path (with no leading slash). If type is Device, then value is the full device ID. If type is XBeeNode, then the value is the XBee node extended src address.
reconnectWindowDuration: Fires if the device does not reconnect within this number of minutes.
reset.disabled: Is set to true to cause this alert to not auto-reset. The default is false.

{
	"type":"XBeeNode Offline",
	"scope":{
		"type":"Group",
		"value":"New York/Manhattan/Sensors"
	},
	"fire":{
		"parameters":{
			"reconnectWindowDuration":"1"
		}
	}
}