Alarm
Use the Alarm web service to create, list, or update alarms within your Remote Manager account. The maximum number of alarms per account is 16. When creating an alarm, you must specify an alarm template on which to base the alarm. See also the AlarmTemplate web service and Alarm template types.
URI
http://<hostname>/ws/Alarm
HTTP method |
Format |
Description |
GET |
/ws/Alarm |
Get a list of all alarms. |
GET |
/ws/Alarm/{almId} |
Get details for a specific alarm. |
POST |
/ws/Alarm |
Create a new alarm |
PUT |
/ws/Alarm/{almId} |
Update an existing alarm. |
DELETE |
/ws/Alarm/{almId} |
Delete an alarm. |
Elements
almId
Remote Manager identifier for the alarm.
cstId
Remote Manager identifier for the customer.
almtID
System-generated identifier for an alarm template. To get a list of available alarm template, use the AlarmTemplate web service.
grpId
Remote Manager identifier for the customer group.
almName
Name of the alarm.
almDescription
Description of the alarm.
almEnabled
Boolean value that indicates whether the alarm is enabled.
Value |
Description |
true |
Alarm is enabled. |
false |
Alarm is disabled. |
almPriority
Keyword that indicates the user-defined alarm priority: high, medium, or low.
almScopeConfig
Specifies the resource scope for the alarm. Scope options include:
Scope |
Description |
Group |
Applies the alarm to the specified group indicated by the full group path. |
Device |
Applies the alarm to the specified device ID. For example, 00000000-00000000-00000000-00000000. |
XbeeNode |
Applies the alarm to the specified XbeeNode extended address. For example, 00:13:A2:00:00:00:00:00. |
Resource |
Applies the alarm to a data stream path or pattern. You can use the wildcard charater asterisk () to match any element in the data stream path. For example, dia/channel//lth/temp matches all the lth temperature reading for all devices. |
Global |
Applies the alarm at the customer level to monitor all instances of an entity. For example, you can create an alarm to monitor the total number of web services calls for your account. This option is available for subscription usage alarms only. |
See almScopeConfig for the required XML structure for almScopeConfig.
almRuleConfig
Specifies the rule configurations for an alarm:
Rule configuration |
Description |
FireRule |
A list of variables that specify the condition for firing the alarm. |
ResetRule |
A list of variables that specify the condition for resetting the alarm. |
By default, all alarms reset automatically. You can disable automatic reset by passing the enabled = false attribute for the ResetRule element. For example, <ResetRule enabled = "false">
.
See almRuleConfig for the required XML structure for almRuleConfig.
See Alarm template types for a list of available fire and reset variables for each alarm template type.
almRuleConfig
Use the following XML structure for almRuleConfig.
<almRuleConfig>
<Rules>
<FireRule name="fireRule1">
<Variable name="operator" value=">"/>
<Variable name="thresholdvalue" value="1"/>
<Variable name="timeUnit" value="seconds"/>
<Variable name="timeout" value="10"/>
<Variable name="type" value="double"/>
</FireRule>
<ResetRule name="resetRule1">
<Variable name="type" value="double"/>
<Variable name="thresholdvalue" value="1"/>
<Variable name="operator" value="<="/>
<Variable name="timeUnit" value="seconds"/>
<Variable name="timeout" value="10"/>
</ResetRule>
</Rules>
</almRuleConfig>
By default, all alarms reset automatically. You can disable automatic reset by passing the enabled = false attribute for ResetRule element; for example, <ResetRule enabled = "false">
.
almScopeConfig
Use the following XML structure for almScopeConfig.
<almScopeConfig>
<ScopingOptions>
<Scope name="Resource" value="Weather/USA/*/Minneapolis"/>
</ScopingOptions>
</almScopeConfig>
You can specify only one <ScopingOption>
per <almScopeConfig>
element; and you can specify only one <Scope>
per <ScopingOptions>
. To specified multiple <scopes>
for an alarm, use multiple <almScopeConfig>
statements.
List All Alarms
The following example shows how to list all alarms for your account.
Request
Response
The sample result shows the result header and three alarms.
<result>
<resultTotalRows>3</resultTotalRows>
<requestedStartRow>0</requestedStart/row>
<resultSize>3</resultSize>
<requestedSize>1000</requestedSize>
<remainingSize>0<remainingSize>
<Alarm>
<almId>142</almId> <!-- alarm #1 -->
<cstId>2</cstId>
<almtId>4</almtId>
<grpId>2</grpId>
<almName>Device Excessive Connections</almName>
<almDescription>Detects devices with an excessive number of
connection attempts</almEnabled>
<almPriority>0</almPriority>
<almEnabled>true</almName>
<almScopeConfig>
<ScopingOptions>
<Scope name="Group" value="/CUS0000001_Digi_International/" />
</ScopingOptions>
</almScopeConfig>
<almRuleConfig>
<Rules>
<FireRule name="fireRule1">
<Variable name="disconnectWindow" value="5" />
<Variable name="disconnectCount" value="5" />
</FireRule>
<ResetRule name="resetRule1">
<Variable name="reconnectWindow" value="5" />
</ResetRule>
</Rules>
</almRuleConfig>
</Alarm>
<Alarm>
<almId>151</almId> <!-- alarm #2 -->
<cstId>2</cstId>
<almtId>2</almtId>
<grpId>2</grpId>
<almName>Device Offline</almName>
<almDescription>Detects when a device disconnects from Remote Manager and fails
to reconnect within the specified time.</almEnabled>
<almPriority>1</almPriority>
<almEnabled>true</almName>
<almScopeConfig>
<ScopingOptions>
<Scope name="Group" value="/CUS0000001_Digi_International/" />
</ScopingOptions>
</almScopeConfig>
<almRuleConfig>
<Rules>
<FireRule name="fireRule1">
<Variable name="reconnectWindowDuration" value="10" />
</FireRule>
<ResetRule name="resetRule1"/>
</Rules>
</almRuleConfig>
</Alarm>
<Alarm>
<almId>152</almId> <!-- alarm #3 -->
<cstId>2</cstId>
<almtId>1</almtId>
<grpId>2</grpId>
<almName>System Alarm</almName>
<almDescription>Detects when system alarm condistions occur.</almEnabled>
<almPriority>0</almPriority>
<almEnabled>true</almName>
<almScopeConfig>
</almScopeConfig>
<almRuleConfig>
</almRuleConfig>
</Alarm>
</result>
Get Alarm Details
The following example shows how to get details for a sample alarm with an alarm ID of 3035.
Request
Response
<result>
<resultTotalRows>1</resultTotalRows>
<requestedStartRow>0</requestedStartRow>
<resultSize>1</resultSize>
<requestedSize>1000</requestedSize>
<remainingSize>0</remainingSize>
<Alarm>
<almId>3035</almId>
<cstId>2</cstId>
<almtId>2</almtId>
<grpId>11959</grpId>
<almName>Device Offline</almName>
<almDescription>Detects when a device disconnects from Remote Manager and fails to reconnected within the specified time</almDescription>
<almEnabled>true</almEnabled>
<almPriority>2</almPriority>
<almScopeConfig>
<ScopingOptions>
<Scope name="Group" value="/CUS000000_Digi_Test/PW_Test/"/>
</ScopingOptions>
</almScopeConfig>
<almRuleConfig>
<Rules>
<FireRule name="fireRule1">
<Variable name="reconnectWindowDuration" value="1"/>
</FireRule>
<ResetRule name="resetRule1"/>
</Rules>
</almRuleConfig>
</Alarm>
</result>
Create a Datapoint Condition Alarm
The following sample shows how to create a data point condition alarm that fires when the outside temperature data point is less than than 10 degrees Fahrenheit below zero.
In this example, the alarm template ID for the data point condition alarm is 9 (almtId=9). To find the almtId for an alarm type, send a GET ws/AlarmTemplate request to get a list of all available alarm templates.
Request
POST /ws/Alarm
Payload
<Alarm>
<almtId>9</almtId> <!-- Datapoint Condition Alarm -->
<almName>Minneapolis Temperature</almName>
<almDescription>Fire when it gets extremely cold.</almDescription>
<almScopeConfig>
<ScopingOptions>
<Scope name="Resource" value="temperature/MN/Minneapolis" />
</ScopingOptions>
</almScopeConfig>
<almRuleConfig>
<Rules>
<FireRule>
<Variable name="thresholdValue" value="-10" />
<Variable name="timeUnit" value="minutes" />
<Variable name="type" value="numeric" />
<Variable name="timeout" value="10" />
<Variable name="operator" value="<" />
</FireRule>
<ResetRule>
<Variable name="thresholdValue" value="-10" />
<Variable name="timeUnit" value="minutes" />
<Variable name="type" value="numeric" />
<Variable name="timeout" value="10" />
<Variable name="operator" value=">" />
</ResetRule>
</Rules>
</almRuleConfig>
</Alarm>
Create a Diachannel Datapoint Condition Alarm
The following sample shows how to create a DIA channel data point condition alarm that fires when the helium level in an MRI gets low.
In this example, the alarm template ID for the DIA channel data point condition alarm is 6 (almtId=6). To find the almtId for an alarm type, send a GET ws/AlarmTemplate request to get a list of all available alarm templates.
Request
POST /ws/Alarm
Payload
<Alarm>
<almtId>6</almtId> <!-- Dia Channel DataPoint Condition Alarm -->
<almName>Low Helium</almName>
<almDescription>Fires when the helium level in the MRI gets low</almDescription>
<almScopeConfig>
<ScopingOptions>
<Scope name="Group" value="CUS001_ABC/Test/" />
</ScopingOptions>
</almScopeConfig>
<almRuleConfig>
<Rules>
<FireRule>
<Variable name="thresholdValue" value="10" />
<Variable name="channelName" value="helium" />
<Variable name="instanceName" value="mri" />
<Variable name="timeUnit" value="seconds" />
<Variable name="type" value="numeric" />
<Variable name="timeout" value="5" />
<Variable name="operator" value="<" />
</FireRule>
<ResetRule>
<Variable name="thresholdValue" value="10" />
<Variable name="channelName" value="helium" />
<Variable name="instanceName" value="mri" />
<Variable name="timeUnit" value="seconds" />
<Variable name="type" value="numeric" />
<Variable name="timeout" value="5" />
<Variable name="operator" value=">" />
</ResetRule>
</Rules>
</almRuleConfig>
</Alarm>
Create a Smart Energy Missing Datapoint Alarm
The following sample shows how to create a smart energy missing data point alarm that fires when the devices do not report smart energy data.
In this example, the alarm template ID for the smart energy missing data point alarm is 12 (almtId=12). To find the almtId for an alarm type, send a GET ws/AlarmTemplate request to get a list of all available alarm templates.
Request
POST /ws/Alarm
Payload
<Alarm>
<almtId>12</almtId> <!-- Missing Smart Energy DataPoint alarm -->
<almName>Missing Smart Energy DataPoint</almName>
<almDescription>Fires when devices have not reported SmartEnergy data within the specified time</almDescription>
<almScopeConfig>
<ScopingOptions>
<Scope name="Group" value="/CUS001_ABC/" />
</ScopingOptions>
</almScopeConfig>
<almRuleConfig>
<Rules>
<FireRule>
<Variable name="uploadTimeUnit" value="hours" />
<Variable name="clusterType" value="*" />
<Variable name="readingTimeUnit" value="4" />
<Variable name="attributeId" value="4" />
<Variable name="uploadInterval" value="1" />
<Variable name="clusterId" value="*" />
<Variable name="endpointId" value="*" />
<Variable name="readingInterval" value="10" />
</FireRule>
<ResetRule />
</Rules>
</almRuleConfig>
</Alarm>
Create a Subscription Usage Alarm
The following sample shows how to create a subscription usage alarm that fires when Verizon cellular usage data exceeds 2 MB. The subscription usage alarm must specify the svcID along with a metric. Use the CustomerRatePlan web service to get a list of svcIDs.
In this example, the alarm template ID for the subscription usage alarm is 8 (almtId=8). To find the almtId for an alarm type, send a GET ws/AlarmTemplate request to get a list of all available alarm templates.
Request
POST /ws/Alarm
Payload
<Alarm>
<almtId>8</almtId> <!-- Subscription Usage alarm -->
<almName>Verizon Cellular Usage</almName>
<almDescription>Fires when verizon cellular usage data exceeds 2MB </almDescription>
<almScopeConfig>
<ScopingOptions>
<Scope name="Device" value="00000000-00000000-000000FF-FF000001" />
</ScopingOptions>
</almScopeConfig>
<almRuleConfig>
<Rules>
<FireRule>
<Variable name="unit" value="mb" />
<Variable name="thresholdValue" value="2" />
<Variable name="svcId" value="14" />
<Variable name="metric" value="transferred" />
</FireRule>
<ResetRule />
</Rules>
</almRuleConfig>
</Alarm>