An alarm is what OpenGate raises when a rule detects something worth a human’s attention: a device that stopped reporting, a value out of range, an identification conflict. This API is how a back-office application finds them, counts them, and records that somebody dealt with them.

The alarm life cycle

stateDiagram-v2
    direction LR
    [*] --> OPEN: a rule raises the alarm
    OPEN --> ATTENDED: action ATTEND
    OPEN --> CLOSED: action CLOSE
    ATTENDED --> CLOSED: action CLOSE
    CLOSED --> [*]
Status Meaning
OPEN The alarm is active
ATTENDED An operator is dealing with it
CLOSED The alarm is closed

Two more attributes tell you how much it matters:

Attribute Values
severity INFORMATIVE (only informative) · URGENT (needs attention soon) · CRITICAL (critical for service operation)
priority LOW · MEDIUM · HIGH

Endpoints

To POST to
Search alarms on any entity /north/v80/search/entities/alarms
Search alarms on devices /north/v80/search/entities/devices/alarms
Search alarms on subscriptions /north/v80/search/entities/subscriptions/alarms
Count instead of list The same three URLs with /summary
Attend or close alarms /north/v80/alarms

Searches follow the standard query language: filter, select, sort, group and limit, with results in JSON by default or CSV through header options.

Finding alarms

curl --request POST \
     --header "X-ApiKey: <your-api-key>" \
     --header "Content-Type: application/json" \
     --data '{"filter": {"like": {"alarm.channel": "default_channel"}}}' \
     https://api.opengate.es/north/v80/search/entities/alarms
{
  "alarms": [
    {
      "identifier": "6c6c3bcb-633e-4418-ae6d-ed69a1db7e96",
      "name": "alarmForDevice",
      "severity": "CRITICAL",
      "priority": "HIGH",
      "status": "CLOSED",
      "entityIdentifier": "device_ogmapiXXX9",
      "organization": "org_ogmapiXXX9",
      "channel": "chn_ogmapiXXX9",
      "openingDate": "2020-08-21T10:42:35.507Z",
      "closureDate": "2020-08-21T10:42:54.186Z"
    }
  ],
  "page": { "number": 1 }
}

Fields you can filter and sort on

Group Fields
Identity alarm.identifier · alarm.name · alarm.rule · alarm.description
Classification alarm.severity · alarm.priority · alarm.status
Where alarm.organization · alarm.channel · alarm.entityIdentifier · alarm.subEntityIdentifier · alarm.resourceType
Opening alarm.openingDate
Attention alarm.attentionDate · alarm.attentionUser · alarm.attentionNote
Closure alarm.closureDate · alarm.ClosureUser · alarm.closureNote

Everyday queries follow from those: everything still open and critical, everything a given operator attended, everything raised on one device last week.

{
  "filter": {
    "and": [
      { "eq": { "alarm.status": "OPEN" } },
      { "eq": { "alarm.severity": "CRITICAL" } }
    ]
  },
  "sort": { "parameters": [ { "name": "alarm.openingDate", "type": "DESCENDING" } ] }
}

Counting alarms

The /summary endpoints answer how many, which is what a dashboard needs. An empty filter summarizes everything:

{ "filter": {} }

The response counts alarms and breaks them down by group:

{
  "summary": {
    "date": "2020-08-14T11:06:26.04Z",
    "count": 6,
    "summaryGroup": [
      { "severity": { "count": 6, "list": [
        { "count": 1, "name": "URGENT" },
        { "count": 3, "name": "CRITICAL" },
        { "count": 2, "name": "INFORMATIVE" }
      ] } },
      { "rule": { "count": 3, "list": [
        { "count": 1, "name": "alarmForSubsInDevice" },
        { "count": 1, "name": "alarmForDevice" },
        { "count": 1, "name": "alarmForSubscription" }
      ] } },
      { "status": { "count": 3, "list": [ { "count": 3, "name": "OPEN" } ] } },
      { "name": { "count": 3, "list": [ { "count": 3, "name": "identificationConflict" } ] } }
    ]
  }
}
Only four fields can group a summary

Summaries group by alarm.name, alarm.rule, alarm.status and alarm.severity. Any other field returns 400 Bad Request.

Attending and closing

Alarms are not deleted, they are moved along their life cycle. One request handles a batch, and the notes field records why — which is what makes the alarm history auditable afterwards:

curl --request POST \
     --header "X-ApiKey: <your-api-key>" \
     --header "Content-Type: application/json" \
     --data '{"action": "CLOSE", "alarms": ["50dca9ab-f552-4805-9cff-019090d5b92b"], "notes": "notes of the reason"}' \
     https://api.opengate.es/north/v80/alarms
Field Holds
action ATTEND or CLOSE
alarms The identifiers to act on, one or many
notes The reason, stored as attentionNote or closureNote

The user performing the action is recorded in attentionUser or ClosureUser, with its timestamp, so you can query later who handled what.

API specification