Create Alarms

Prerequisites

To create your first alarm, you need at least one source and one variable in Opinum.

Tip

Learn more about sources and variables.

Create an alarm

Managing alarms is currently only possible through the REST API.

Tip

Learn more about our API and how to connect to it.

Create the model

Some properties are mandatory, others are optional or will be automatically filled by the system.

Click to see the Alarm model

{
  "sourceId": 0,
  "id": "string",
  "siteId": 0,
  "variableId": 0,
  "friendlyName": "string",
  "thresholdType": "Low",
  "createdBy": "string",
  "createdDate": "2020-03-31T12:32:28.339Z",
  "granularity": 0,
  "granularityTimeBase": "Second",
  "updatedBy": "string",
  "updatedDate": "2020-03-31T12:32:28.339Z",
  "type": "Threshold",
  "setValue": 0,
  "resetValue": 0,
  "priority": 0,
  "frequencyType": "Raw",
  "aggregationType": "SUM",
  "scheduleNextExecutionDate": "2020-03-31T12:32:28.339Z",
  "notifications": [
    {
      "type": "Email",
      "target": "User",
      "value": "string",
      "notifyOnTriggers": [
        "Set"
      ]
    }
  ],
  "exceptions": [
    {
      "from": "2020-03-31T12:32:28.339Z",
      "to": "2020-03-31T12:32:28.339Z",
      "reason": "string"
    }
  ],
  "scheduleConfig": {
    "scheduleId": 0,
    "scheduleLevelIds": [
      0
    ]
  },
  "cron": "string",
  "isAdvancedCron": true,
  "cronGap": "string",
  "rawDataAgeFilter": {
    "type": "NoFilter",
    "relativePeriod": "string",
    "numberOfPeriods": 0
  },
  "latestStateChange": {
    "id": "string",
    "alarmId": "string",
    "updatedBy": "string",
    "notifications": [
      {
        "alarmNotification": {
          "type": "Email",
          "target": "User",
          "value": "string",
          "notifyOnTriggers": [
            "Set"
          ]
        },
        "alarmNotificationMetadata": {
          "emailTrackingId": "string"
        }
      }
    ],
    "state": {
      "present": true,
      "acknowledged": true,
      "inhibited": true,
      "uncertain": true
    },
    "value": 0,
    "date": "2020-03-31T12:32:28.339Z"
  },
  "enabled": true
}

Mandatory properties

Site, source and variable Id

The variable Id identifies the variable that will be monitored by the alarm.

The source and site Ids respectively identify the source and site to which this variable is linked.

Alarm Id

The user has to define an Id for the alarm. We strongly recommend choosing only alphanumeric characters and eventually dashes and/or underscores.

E.G. : My-Alarm-54RT7

Warning

Please note that each Alarm Id must be unique in the current account. We also strongly recommend not the reuse the Id of a deleted alarm.

Alarm Name

We strongly recommend choosing only alphanumeric characters and eventually dashes and/or underscores. E.G.: My-Alarm-42-Brussel

Using unique names will make the usage of the system easier, but this is not mandatory.

Threshold Type

There are two types of thresholds:

Low: the alarm will switch to 'present' state when the datapoints evaluation is equal or goes below than the Set value.
High: the alarm will switch to 'present' state when the datapoints evaluation is equal or goes above than the Set value.

Type

There are two types of alarms:

Threshold: to use when the data received are not of binary type. The Set and the Reset values will be a double.
Binary: to use when the data received are of 'binary' type (1 and 0). The Set and Reset value will be 1 and 0. This type is useful only for raw alarms.

Set and Reset Value The Set and Reset values are the thresholds against which the incoming data points will be evaluated.

In case of a threshold type alarm, the value for Set and Reset should be a double which respects the following conditions:

Binary_Set_Reset

In case of a threshold type alarm, the value for :

Threshold_Set_Reset

Frequency type

There are three frequency types:

Raw: in this mode, Opinum will validate the value of every datapoint against the Set and Reset values.
Rolling: in this mode, for each datapoint, Opinum will validate the aggregated value of a specified period preceding and including the datapoint.
Scheduled: in this mode, Opinum will validate the aggregated value of a specified period at a specified time.

Tip

Learn more about Frequency types.

Note

At this time, only raw alarms are supported

Enabled

This property is a Boolean: true or false.

When 'true', the alarm is enabled, and the system will check the data against the thresholds as regard to the configuration defined. When 'false', the alarm is disabled and will never be evaluated.

Example

A raw alarm with only mandatory fields will look like this:

{
  "sourceId": 123,
  "id": "myAlarm123",
  "siteId": 1234,
  "variableId": 456,
  "friendlyName": "myAlarmName",
  "thresholdType": "Low",
  "type": "Threshold",
  "setValue": 50,
  "resetValue": 100,
  "frequencyType": "Raw",
  "enabled": true
}

This model is a raw low threshold type alarm with a Set value equals to 50 and a Reset value equals to 100. This alarm is related to the incoming data of the variable with the ID '456' (linked to the source with the ID '123', site with the ID '1234').

Mandatory properties for rolling and scheduled alarms

Note

At this time, only raw alarms are supported.

Granularity and Granularity time base

These two properties are mandatory but only for rolling and scheduled alarms. These can't be filled for raw alarm.

The granularity is the time period for which data will be verified.

E.G.: a '1 day' granularity will gathered all the data points during the last 24h (from the incoming datapoint for a rolling alarm and from the trigger moment for a scheduled alarm) and apply the aggregation selected.

Aggregation type

This property is mandatory for rolling and scheduled alarms.

The existing aggregation types are the following:

SUM: Sum of the datapoints included in the granularity chosen
MIN: Minimum value of the datapoints included in the granularity chosen
MAX: Maximum value of the datapoints included in the granularity chosen
AVG: Average of the datapoints included in the granularity chosen
COUNT: Count of the datapoints included in the granularity chosen
VAR: Variance of the datapoints included in the granularity chosen
STDEV: Standard deviation of the datapoints included in the granularity chosen

This property can't be filled for raw alarm.

cron, isAdvancedCron, cronGap

These properties are mandatory if the alarm is a scheduled alarm and allow to define at which recurrent time the assessment of the alarm will be done.

Optional properties

Priority

This property is not used in DataHub but allows to set a priority (integer32) to the alarm in order to use this information in another application.

Notifications

This property allows to create some notifications related to the alarms.

Learn more about notifications.

Exceptions

Exceptions allow to define some conditions which, when met, the alarm is "deactivated".

Tip

Learn more about Exceptions

Schedules

The integration of schedules in the alarm is a way to exclude datapoints based on a time factor.

Tip

Learn more about Schedules in the alarms.

Properties automatically set

The other properties such as 'createdDate', 'createdBy', … will be automatically set by the system.

Send the model to the API

Once the alarm model is ready, use following request to create the alarm in DataHub:

POST https://api.opinum.com/Alarms

Great, your alarm is now in the system!

Tip

Learn how to manage it.

Documentation Center

Create Alarms

Prerequisites

Tip

Create an alarm

Tip

Create the model

Mandatory properties

Warning

Tip

Note

Mandatory properties for rolling and scheduled alarms

Note

Optional properties

Tip

Tip

Properties automatically set

Send the model to the API

Tip

Developer Center

Follow us