Alarms

Overview

The alarms interface consists of three parts:

• The alarm API resource returns URIs and URI templates to collections of alarms, so that all alarms or alarms of a specified source device and/or status can be retrieved.
• The alarm collection resource retrieves alarms and enables creating new alarms.
• The alarm resource represents individual alarms that can be queried, modified and progressed through an alarm workflow.

Note that for all PUT/POST requests accept header should be provided, otherwise an empty response body will be returned.

Alarm API

AlarmAPI [application/vnd.com.nsn.cumulocity.alarmApi+json]

Response body: application/vnd.com.nsn.cumulocity.alarmApi+json

Required role: ROLE_ALARM_READ

Example request:

GET /alarm
Host: ...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.alarmApi+json;ver=…
Content-Length: …
{
    "self" : "<<AlarmAPI URL>>",
    "alarms" : { "self" :"<<AlarmCollection URL>>" },
    "alarmsForStatus" : "<<AlarmCollection URL>>?status={status}",
    "alarmsForSource" : "<<AlarmCollection URL>>?source={source}",
    "alarmsForSourceAndStatus" : "<<AlarmCollection URL>>?source={source}&status={status}",
    "alarmsForTime" : "<<AlarmCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}",
    "alarmsForStatusAndTime" : "<<AlarmCollection URL>>?status={status}&dateFrom={dateFrom}&dateTo={dateTo}",
    "alarmsForSourceAndTime" : "<<AlarmCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}",
    "alarmsForSourceAndStatusAndTime" : "<<AlarmCollection URL>>?source={source}&status={status}&dateFrom={dateFrom}&dateTo={dateTo}",
    "alarmsForSourceWithAssetsAndWithDevices": "<<AlarmCollection URL>>?source={source}&withAssets={withAssets}&withDevices={withDevices}"
    "alarmsForResolved": "<<AlarmCollection URL>>?resolved={resolved}",
    "alarmsForSeverity": "<<AlarmCollection URL>>?severity={severity}",
}

Notifications

The alarm notification API permits the monitoring of alarms of specific devices. The basic protocol for receiving notifications is described in the Section “Real-time notifications”. The URL is

/cep/realtime

The subscription channel needs to contain the managed object ID of the device or a “*” as placeholder to receive notifications for the alarms of all devices

/alarms/<<deviceId>>

The response will additionally to the alarm object contain a “realtimeAction” to identify which action resulted in the given object (CREATE, UPDATE or DELETE). In case of a deletion the data will only contain the ID of the deleted alarm.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/alarms/12345",
    "successful": true,
    "error": "",
    "data": [{
      "realtimeAction": "UPDATE",
      "data": {
        "id": "1",
        "self": "...",
        "source": {
          "12345"
        },
        "type": "c8y_UnavailabilityAlarm",
        "text": "I am an alarm",
        "severity": "MINOR",
        "status": "CLEARED",
        "firstOccurrence": true,
        "count": 1
      }
    }],
    "clientId": "Un1q31d3nt1f13r"
  }
]

Required role: ROLE_ALARM_READ

Alarm collection

AlarmCollection [application/vnd.com.nsn.cumulocity.alarmCollection+json]

GET an alarm collection

Response body: AlarmCollection

Required role: ROLE_ALARM_READ

Example request:

GET /alarm/alarms
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.alarmCollection+json;ver=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.alarmCollection+json;ver=...
Content-Length: ...

{
  "self" : "...",
  "next" : "...",
  "prev" : "...",
  "alarms": [
    {
      "id" : "10",
      "self" : "...",
      "creationTime" : "2011-09-06T12:03:27.927Z",
      "type" : "com_cumulocity_events_TamperEvent",
      "time" : "2011-09-06T12:03:27.845Z",
      "text" : "Tamper sensor triggered",
      "status" : "ACTIVE",
      "severity" : "MAJOR",
      "source": { "id" : "12345", "self" : "..." },
      "count":1,
      "history": { ... }
    },
    {
      "id" : "11",
      "self" : "...",
      "creationTime" : "2011-09-06T12:03:27.927Z",
      "type" : "com_cumulocity_events_BatteryWarning",
      "time" : "2011-09-06T12:04:27.845Z",
      "text" : "Low battery level",
      "status" : "ACTIVE",
      "severity" : "MINOR",
      "source": { "id" : "1122", "self" : "..." },
      "count":1,
      "history": { ... }
    }
  ],
  "statistics" : {
    "totalPages" : 8,
    "pageSize" : 5,
    "currentPage : 1
  }
}

POST - Create a new Alarm

Request body: Alarm

Response body: Alarm

Required role: ROLE_ALARM_ADMIN or owner of source object.

Example request:

POST /alarm/alarms
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...

{
  "type" : "com_cumulocity_events_TamperEvent",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Tamper sensor triggered",
  "status" : "ACTIVE",
  "severity" : "MAJOR",
  "source" : { "id" : "12345", "self" : "..." },
  "com_mycorp_MyProp" : { ... }
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
Content-Length: ...
Location: <<URL of new alarm>>

{
  "id" : "10",
  "self" : "<<URL of new alarm>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_events_TamperEvent",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Tamper sensor triggered",
  "status" : "ACTIVE",
  "severity" : "MAJOR",
  "source" : { "id" : "12345", "self" : "..." },
  "count": 1,
  "com_mycorp_MyProp" : { ... }
  "history" : { ... }
}

For POST requests, the source parameter is required to have only an id.

The id and creationTime of the new alarm are generated by the server and returned in the response to the POST operation.

Alarm suppression If the source device is in maintenance mode, the alarm is not created and not reported to the Cumulocity IoT event processing engine. After sending a POST request to create a new alarm and the device is in maintenance mode the self link of the alarm will be:

{
    "self" : "<<URL of new alarm>>/null",
}

Alarm de-duplication If an active or acknowledged alarm (does not work for cleared) with the same source and type exists, no new alarm is created. Instead, the existing alarm is updated by incrementing the “count” property and the time-property is also updated. Any other changes are ignored, and the alarm history is not updated. The first occurrence of the alarm is recorded in “firstOccurenceTime”.

DELETE - delete an alarm collection

The DELETE method allows for deletion of alarm collections. Acceptable query parameters are:

Request body: N/A

Response body: N/A

Required role: ROLE_ALARM_ADMIN

Example request:

 DELETE: /alarm/alarms....
 Host: ...
 Authorization: Basic ...

Example response:

HTTP/1.1  204 NO CONTENT

Important: Note that it is possible to call this endpoint without providing any parameter - it will result in deleting all alarms and it is not recommended.

PUT - bulk update of alarm collection

The PUT method allows for updating alarms collections. Currently only the status of alarms can be changed.

Request body:

  { status: <new_status> }

Response body: N/A

Required role: ROLE_ALARM_ADMIN

Response status:

• 200 - if the process has completed, all alarms have been updated
• 202 - if process continues in background

Example request: clear all active alarms

 PUT: /alarm/alarms?status=ACTIVE
 Host: ...
 Authorization: Basic ...      
 {
    "status": "CLEARED"
 }

Example response:

 HTTP/1.1  202 Accepted    

The endpoint uses query parameters. At least one query parameter is required for processing to avoid accidentally updating all existing alarms.

Acceptable query parameters are:

• status
• source
• resolved
• severity
• dateFrom
• dateTo

Since this operations can take a lot of time, request returns after maximum 0.5 sec of processing, and updating is continued as a background process in the platform.

Alarms can be updated even if they are in maintenance mode.

Alarm

Alarm [application/vnd.com.nsn.cumulocity.alarm+json]

GET an Alarm

Response body: Alarm

Required role: ROLE_ALARM_READ

Example request:

GET /alarm/alarms/<<alarmId>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.alarm+json;ver=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
Content-Length: ...
{
  "id" : "10",
  "self" : "<<Alarm URL>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_events_TamperEvent",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Tamper sensor triggered",
  "status" : "ACTIVE",
  "severity" : "MAJOR",
  "source" : { "id" : "12345", "self" : "..." },
  "com_mycorp_MyProp" : { ... }
  "history" : { }
}

Update an Alarm

Changes to alarms will generate a new audit record. The audit record will include the username and application that triggered the update, if applicable. To get the list of audits for alarm, use the following request: GET /audit/auditRecords?source=

Please notice that if update actually doesn’t change anything (i.e. request body contains data that is identical to already present in database), there will be no audit record added and no notifications will be sent.

Only text, status, severity and custom properties can be modified. Non-modifiable fields will be ignored when provided in request.

Request body: Alarm

Response body: Alarm

Required : ROLE_ALARM_ADMIN or owner of source object

Example Request:

PUT /alarm/alarms/<<alarmId>>
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
{
  "severity" : "minor"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
Content-Length: ...
{
  "id" : "10",
  "self" : "<<Alarm URL>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_events_TamperEvent",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Tamper sensor triggered",
  "status" : "ACKNOWLEDGED",
  "severity" : "MINOR",
  "source" : { "id" : "12345", "self" : "..." },
  "history" : { }
}