Domorela's Blog: Virtual Lab with Domorela DMRL1: Testing with REST API: Alarms

Alarm Service of Domorela's REST API allows to handle all active alarms and is the only way to acknowledge an active alarm without modify its state. When an alarm is acknowledged, timestamp and user information are registered in the ack record. There are more operations available, but we'll just talk about querying and acknowledge alarms in this article.

To test alarms with REST API, first we will query the current active alarms by sending a POST with an obix:AlarmFilter record:

$ curl --request POST -b .cookies --data-binary "@filtro.xml" "https://$host:8083/admin/api/alarm?ref=query/"

were the file filtro.xml contains next oBIX record:

<obj is="obix:AlarmFilter">
 <abstime name="start" val="2021-04-19T12:42:00.001+02:00" tz="Europe/Madrid"/>
 <abstime name="end" val="2021-04-19T23:59:59.001+02:00" tz="Europe/Madrid"/>
</obj>

Then we receive all current active alarms referring to the Datapoint objects, i.e. the Group Objects, which are in alarm state:

<obj is="obix:AlarmQueryOut">
  <list name="data" of="obix:Alarm">
    <ref name="1" href="/obix/alarmService/alarmas/1/" is="obix:AckAlarm obix:StatefulAlarm obix:PointAlarm obix:Alarm">
      <ref name="source" href="/obix/knx/config/proyectos/P085D/direcciones/P085D0_GA72/datapoints/P085D0_GA72_oProbe0bProbeError/curVal/"/>
      <abstime name="timestamp" href="/obix/alarmService/alarmas/1/timestamp/" val="2021-04-19T17:28:09.856Z"/>
      <abstime name="normalTimestamp" href="/obix/alarmService/alarmas/1/normalTimestamp/" val="1970-01-01T00:00:00.000Z"/>
      <bool name="alarmValue" href="/obix/alarmService/alarmas/1/alarmValue/" val="true" display="alarm" range="knx/enums/dpt_alarm/"/>
      <op name="ack" href="/obix/alarmService/alarmas/1/ack/" in="obix:obj" out="obix:obj"/>
    </ref>
    <ref name="2" href="/obix/alarmService/alarmas/2/" is="obix:AckAlarm obix:StatefulAlarm obix:PointAlarm obix:Alarm">
      <ref name="source" href="/obix/knx/config/proyectos/P085D/direcciones/P085D0_GA85/datapoints/P085D0_GA85_oProbe0bOverheating/curVal/"/>
      <abstime name="timestamp" href="/obix/alarmService/alarmas/2/timestamp/" val="2021-04-19T17:31:20.291Z"/>
      <abstime name="normalTimestamp" href="/obix/alarmService/alarmas/2/normalTimestamp/" val="1970-01-01T00:00:00.000Z"/>
      <bool name="alarmValue" href="/obix/alarmService/alarmas/2/alarmValue/" val="true" display="alarm" range="knx/enums/dpt_alarm/"/>
      <op name="ack" href="/obix/alarmService/alarmas/2/ack/" in="obix:obj" out="obix:obj"/>
    </ref>
  </list>
</obj>

Now we can send a POST to the Alarm Service with parameter ref including the name (actually the number) of the alarm oBIX object, in this case it's 1:

$ curl --request POST -b .cookies --data-binary "@$ack.xml" "https://$host:8083/admin/api/alarm?ref=1/ack/"

were ack.xml is a file with an oBIX ack record that may or may not include a timestamp field:

<obj is="obix:AckAlarmIn">
 <str name="ackUser" val="admin" null="true"/>
 <abstime name="timestamp" href="/obix/alarmService/alarmas/2/timestamp/" val="2021-04-19T17:40:00.000Z"/>
</obj>

If timestamp isn't present in the ack record, then the ack will be marked with the current time of the Domorela unit, as you can see below in the response to a new query of the active alarms:

<obj is="obix:AlarmQueryOut">
  <list name="data" of="obix:Alarm">
    <ref name="1" href="/obix/alarmService/alarmas/1/" is="obix:AckAlarm obix:StatefulAlarm obix:PointAlarm obix:Alarm">
      <ref name="source" href="/obix/knx/config/proyectos/P085D/direcciones/P085D0_GA72/datapoints/P085D0_GA72_oProbe0bProbeError/curVal/"/>
      <abstime name="timestamp" href="/obix/alarmService/alarmas/1/timestamp/" val="2021-04-19T17:28:09.856Z"/>
      <abstime name="normalTimestamp" href="/obix/alarmService/alarmas/1/normalTimestamp/" val="1970-01-01T00:00:00.000Z"/>
      <bool name="alarmValue" href="/obix/alarmService/alarmas/1/alarmValue/" val="true" display="alarm" range="knx/enums/dpt_alarm/"/>
      <op name="ack" href="/obix/alarmService/alarmas/1/ack/" in="obix:obj" out="obix:obj"/>
      <abstime name="ackTimestamp" val="2021-04-19T18:26:23.574Z"/>
      <str name="ackUser" val="admin" null="true"/>
    </ref>
    <ref name="2" href="/obix/alarmService/alarmas/2/" is="obix:AckAlarm obix:StatefulAlarm obix:PointAlarm obix:Alarm">
      <ref name="source" href="/obix/knx/config/proyectos/P085D/direcciones/P085D0_GA85/datapoints/P085D0_GA85_oProbe0bOverheating/curVal/"/>
      <abstime name="timestamp" href="/obix/alarmService/alarmas/2/timestamp/" val="2021-04-19T17:31:20.291Z"/>
      <abstime name="normalTimestamp" href="/obix/alarmService/alarmas/2/normalTimestamp/" val="1970-01-01T00:00:00.000Z"/>
      <bool name="alarmValue" href="/obix/alarmService/alarmas/2/alarmValue/" val="true" display="alarm" range="knx/enums/dpt_alarm/"/>
      <op name="ack" href="/obix/alarmService/alarmas/2/ack/" in="obix:obj" out="obix:obj"/>
    </ref>
  </list>
</obj>

Next article will talk about querying historical data using REST API.