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

Formats

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.

© 2023 Digi International Inc. All rights reserved.

almRuleConfig

Use the following XML structure for almRuleConfig.

<almRuleConfig>
    <Rules>
        <FireRule name="fireRule1">
            <Variable name="operator" value="&gt;"/>
            <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="&lt;="/>
            <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">.

© 2023 Digi International Inc. All rights reserved.

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.

© 2023 Digi International Inc. All rights reserved.

List All Alarms

The following example shows how to list all alarms for your account.

Request

GET ws/Alarm

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>

© 2023 Digi International Inc. All rights reserved.

Get Alarm Details

The following example shows how to get details for a sample alarm with an alarm ID of 3035.

Request

GET ws/Alarm/3035

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>

© 2023 Digi International Inc. All rights reserved.

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="&lt;" />
         </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="&gt;" />
         </ResetRule>
      </Rules>
   </almRuleConfig>
</Alarm>

© 2023 Digi International Inc. All rights reserved.

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="&lt;" />
         </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="&gt;" />
         </ResetRule>
      </Rules>
   </almRuleConfig>
</Alarm>

© 2023 Digi International Inc. All rights reserved.

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>

© 2023 Digi International Inc. All rights reserved.

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>