Alarms and Exceptions

Exceptions allow to define some conditions which, when met, deactivate the alarm.

Types of exception

An exception related to an alarm can be either a period based exception or a variable based exception.

Period based exception

Allows to define a date range during which the alarm will not be evaluated and therefore, not triggered, even if the condition for a state change are met.

"exceptions": [
    {
      "from": "2020-03-31T00:00:00.000Z",
      "to": "2020-04-02T23:59:59.999Z",
      "reason": "string"
    }
  ]

The 'from' is the date from which the exception begins. The 'to' is the date at which it ends. Both are inclusive.

The 'reason' is a mandatory string which explains why the exception is set.

Note that period based exceptions will always cover entire day(s). They will then begin at 00:00:00.000Z and end at 23:59:59.999Z.

Variable based exception

The condition to deactivate the alarm is based on the value of a datapoint stored on another variable.

The behavior can be represented like this :

Given that a raw alarm is defined on the variable 456, I can define an exception for this alarm related to the value of the datapoints stored on the variable 123. For example, the condition could be value = 3.

VariableException-Definition

For each datapoint ingested on variable 456, the system will find the last datapoint on variable 123 with a timestamp lower than or equal to the timestamp of the ingested datapoint.

If the value of this datapoint meets the condition, the exception is raised and the alarm is not evaluated.

VariableException-Definition

In the previous example, the datapoints underlined in orange, will not trigger the evaluation of the raw alarm because the value of the latest datapoint on the variable 123 having a timestamp <= to theirs, is equal to 3.

Variable based exceptions and frequency types of the alarm

For raw and rolling alarms, the timestamp used to evaluate the exception is the one of the ingested datapoint (on the variable on which the alarm is defined).

For scheduled alarms, the timestamp of the automatic execution (defined by a cron) is used.

Condition

Available operators to define the condition of the variable based exception are:

  • Equal
  • GreaterThan
  • LowerThan

Model object

A variable based exception can be defined in an alarm by using the property named exceptions:

"exceptions": [
      {
        "from": "0001-01-01T00:00:00+00:00",
        "to": "0001-01-01T00:00:00+00:00",
        "siteId": 1234,
        "sourceId": 5678,
        "variableId": 91011,
        "operator": "Equal",
        "value": 1,
        "alarmExceptionType": "Variable"
      }
    ],

Several Exceptions

When several exceptions (with same or different types) are defined for a same alarm, the logic operator applied is 'OR'.

Therefore, as soon as the condition of one exception is fulfilled, the ingested datapoint is not evaluated.

Examples

Raw alarms

Use Case 1 : variable based exception

Given a raw alarm on the variable 456 with the following properties :

  • binary
  • high (Set = 1, Reset = 0)
  • variable based exception on the variable 123 : > 0

VariableException-RawAlarmExample

The alarm will change of state three time :

  • First datapoint with a value 1 : 'present'
  • Second datapoint with a value 0 : 'not present'
  • Fourth datapoint with a value 1 : 'present'

=> The third datapoint will not be evaluated : the latest datapoint on the variable 123 with a timestamp <= (to timestamp of the ingested datapoint on variable 456) has a value matching with the condition of the exception (> 0).

Use Case 2 : period based exception

Given a raw alarm on the variable 456 with the following properties :

  • binary
  • low (Set = 0, Reset = 1)
  • period based exception from A to B

PeriodException-RawAlarmExample

The alarm will change of state two time :

  • First datapoint with a value 1 : 'not present'
  • Last datapoint with a value 0 : 'present'

=> The second and third datapoints will not be evaluated : they are in the period based exception range.

=> The fourth datapoint will be evaluated but its value (1) won't trigger an alarm's change of state.

Rolling alarms

Use Case 1 : variable based exception

Given a rolling alarm on the variable 456 with the following configuration :

  • Threshold high
  • Granularity : 1 hour
  • Aggregation : Max
  • Set = 100
  • Reset = 50
  • variable based exception on the variable 123 : = 0

VariableException-RollingAlarmExample

The alarm will change of state two time :

  • At the insertion of the datapoint at 10:45, the alarm's state becomes 'Present' with value 110. The Max for this last hour is above the Set value (110 > 100).

  • At insertion of the datapoint at 12:00, the alarm's state becomes 'Not Present' with the value 40. The Max for this last hour is below the Reset value (40 < 50).

=> The datapoint at 13:00 will not be evaluated : the latest datapoint on the variable 123, with a timestamp <= to timestamp of the ingested datapoint on variable 456, has a value matching with the condition of the exception (= 0).

Use Case 2 : period based exception

Given a rolling alarm on the variable 456 with the following configuration :

  • Threshold low
  • Granularity : 1 hour
  • Aggregation : Max
  • Set = 50
  • Reset = 100
  • period based exception from A to B

PeriodException-RollingAlarmExample

The alarm will change of state two times :

  • At the insertion of the datapoint at 12:00, the alarm's state becomes 'Present' with the value 40. The Max for this last hour is below the Set value (40 < 50).

  • At insertion of the datapoint at 12:30, the alarm's state becomes 'Not Present' with the value 130. The Max for this last hour is above the Reset value (130 > 100).

The second (10:45) and third (11:15) datapoints will not be evaluated : they are in the period based exception range.

However, they are taken into account when the system calculates the aggregated value at the insertion of a datapoint which is evaluated (E.G : the datapoint at 12:00).

Scheduled alarms

Use Case 1 : variable based exception

Given a scheduled alarm on the variable 456 with the following configuration:

  • Threshold high
  • Granularity : 1 hour
  • Aggregation : Max
  • Set = 100
  • Reset = 50
  • Cron : every hour at 00:00
  • variable based exception on the variable 123 : ' = 0'

VariableException-ScheduledAlarmExample

The alarm will change of state two times :

  • At the evaluation triggered at 11:00. The alarm's state becomes 'Present'. The Max for this last hour is above the Set value (110 > 100).

  • At the evaluation triggered at 13:00. The alarm's state becomes 'Not Present'. The Max for this last hour is below the Reset value (20 < 50).

There is no evaluation triggered at 12:00 : the latest datapoint on the variable 123 with a timestamp <= 12:00 has a value matching with the condition of the exception (= 0).

Use Case 2 : period based exception

Given a scheduled alarm on the variable 456 with the following configuration:

  • Threshold low
  • Granularity : 1 hour
  • Aggregation : Max
  • Set = 50
  • Reset = 100
  • Cron : at every hour at 00:00
  • period based exception from A to B

PeriodException-ScheduledAlarmExample

The alarm will change of state two times :

  • At the evaluation triggered at 12:00. The alarm's state becomes 'Present'. The Max for this last hour is below the Set value (40 < 50).

  • At the evaluation triggered at 13:00. The alarm's state becomes 'Not Present'. The Max for this last hour is above the Reset value (130 > 100).

There is no evaluation triggered at 11:00 : this is in the period based exception range.

However, the datapoints having a timestamp included in this period exception range are taken into account when the system calculates the aggregated value for an evaluation triggered at another time (E.G : the evaluation at 12:00).

Several variable based Exceptions

Given a raw alarm on the variable 456 with the following properties :

  • binary
  • high (Set = 1, Reset = 0)
  • variable based exception on the variable 123 : > 0
  • variable based exception on the variable 789 : = 0

SeveralVariableBasedExceptions-Example

The alarm will change of state only once: at the ingestion of the third datapoint with a value 1 : 'present'.

The others datapoints are in an exception either because of the variable 123, or the variable 789 or both.

Several Exceptions of different types

Given a raw alarm on the variable 456 with the following properties :

  • binary
  • high (Set = 1, Reset = 0)
  • variable based exception on the variable 123 : = 0
  • period based exception from A to B

SeveralDifferentTypesExceptions-Example

The alarm will change of state twice:

  • at the ingestion of the first datapoint with a value 0 : 'not present'
  • at the ingestion of the last datapoint with a value 1 : 'present'.

The others datapoints are in an exception either because of the variable 123, or the period exception or both.

Variable based Exception and Schedule

Given a schedule with the ID '789' with the levels '45', '46' and '47' exists on the current account.

Given a raw alarm on the variable 456 with the following properties :

  • binary
  • high (Set = 1, Reset = 0)
  • variable based exception on the variable 123 : = 0
  • schedule '789', level 45 and 47 selected (alarm not triggered when in the level 46)

AlarmWithScheduleAndException-Example

The alarm will change of state twice :

  • at the ingestion of the first datapoint with a value 1 : 'present'
  • at the ingestion of the last datapoint with a value 0 : 'not present'

The other datapoints won't be evaluated :

  • the second is on the level 46 of the schedule and in the exception regarding the variable 123
  • the third datapoint is in the exception regarding the variable 123
  • the fourth is in the level 46