Alarms

Overview

The alarms interface consists of three parts:

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]

Name Type Occurs Description
self URL 1 Link to this resource.
alarms AlarmCollection 1 Collection of all alarms.
alarmsForStatus AlarmCollection URI template 1 Read-only collection of all alarms in a particular status (placeholder {status}, see “Alarm” resource below for permitted values).
alarmsForSource AlarmCollection URI template 1 Read-only collection of all alarms for a particular source object (placeholder {source}, unique ID of an object in the inventory).
alarmsForSourceAndStatus AlarmCollection URI template 1 Read-only collection of all alarms for a particular source object in a particular status (placeholder {source} and {status}).
alarmsForTime AlarmCollection URI template 1 Read-only collection of all alarms for a particular time range (placeholder {dateFrom} and {dateTo}).
alarmsForStatusAndTime AlarmCollection URI template 1 Read-only collection of all alarms for a particular status and time range (placeholder {status}, {dateFrom} and {dateTo}).
alarmsForSourceAndTime AlarmCollection URI template 1 Read-only collection of all alarms for a particular source and time range (placeholder {source}, {dateFrom} and {dateTo};).
alarmsForSourceAndStatusAndTime AlarmCollection URI template 1 Read-only collection of all alarms for a particular source, status and time range (placeholder {source}, {status}, {dateFrom} and {dateTo};).
alarmsForSourceWithAssetsAndWithDevices AlarmCollection URI template 1 Read-only collection of all alarms for a particular source with its children (placeholder {source}, {withSourceAssets} and {withSourceDevices}).
alarmsForSeverity AlarmCollection URI template 1 Read-only collection of all alarms for a particular severity (placeholder {severity}).
alarmsForResolved AlarmCollection URI template 1 Read-only collection of all alarms which are resolved (placeholder {resolved}).

GET the AlarmAPI resource

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_ALARMS_READ

Alarm collection

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

Name Type Occurs Description
self URI 1 Link to this resource.
alarms Alarm 0..n List of alarms, see below.
statistics PagingStatistics 1 Information about paging statistics.
prev URI 0..1 Link to a potential previous page of alarms.
next URI 0..1 Link to a potential next page of alarms.

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 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. Applicable query parameters are equivalent to GET method.

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

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:

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:

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]

Name Type Occurs Description PUT/POST
id String 1 Uniquely identifies an alarm. No
self URI 1 Link to this resource. No
creationTime String 1 Time when alarm was created in the database. No
type String 1 Identifies the type of this alarm, e.g., “com_cumulocity_events_TamperEvent”. POST: Mandatory PUT: No
time String 1 Time of the alarm. POST: Mandatory PUT: No
text String 1 Text description of the alarm. POST: Mandatory PUT: No
source ManagedObject 1 The ManagedObject that the alarm originated from, as object containing the “id” property. POST: Mandatory PUT: No
status String 0..1 The status of the alarm: ACTIVE, ACKNOWLEDGED or CLEARED. If status was not appeared, new alarm will have status ACTIVE. Must be upper-case. POST: Optional PUT: Optional
severity String 1 The severity of the alarm: CRITICAL, MAJOR, MINOR or WARNING. Must be upper-case. POST: Mandatory PUT: Optional
count Long 1 The number of times this alarm has been sent. No
firstOccurrenceTime String 1 The first time that this alarm occurred (i.e., where “count” was 1). No
history AuditRecordCollection 1 Legacy. Should not be used. No
* Object 0..n Additional properties of the event.

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" : { }
}