Software AG | Alarms

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]

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};).

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

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 Device Integration Platform event processing engine.

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. 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

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
firstOccurenceTime	String	1	The first time that this alarm occurred (i.e., where "count" was 1).	No
history	AuditRecordCollection	1	History of modifications tracing property changes.	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" : {
    "self" : "...",
    "auditRecords" : [ ... ],
  }
}

Update an Alarm

Changes to alarms will generate a new audit record which will be added to the "history" collection. The audit record will include the username and application that triggered the update, if applicable.

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.

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" : {
    "self" : "link to audit history",
    "auditRecords" : [
      {
        "id" : "123",
        "self" : "...",
        "type" : "com_cumulcity_model_alarm_AlarmRaised",
        "creationTime" : "2011-09-06T12:03:32.103Z",
        "time" : "2011-09-06T12:03:27.845Z",
        "text" : "Alarm raised",
        "user" : "Spock",
        "application" : "Omniscape",
        "activity" : "Alarm raised",
        "severity" : "MINOR",
        "source" : { ... }
      },
      {
        "id" : "1234",
        "self" : "...",
        "type" : "com_cumulcity_model_alarm_AlarmChanged",
        "creationTime" : "2011-09-07T12:04:29.031Z",
        "changes": [{
          "attribute": "severity",
          "newValue": {},
          "previousValue": {},
          "type": "com.cumulocity.model.event.CumulocitySeverities"
        }],
        "time" : "2011-09-07T12:04:27.845Z",
        "text" : "Alarm changed",
        "user" : "Spock",
        "application" : "Omniscape",
        "activity" : "Alarm changed.",
        "severity" : "Minor",
        "source" : { ... }
      }
    ]
  }
}

Notifications

The alarm notification API permits the monitoring of alarms of specific devices. 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