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]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URL linking 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}). |
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]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
alarms | Alarm | 0..n | List of alarms, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | string | 0..1 | A URI linking to a potential previous page of alarms. |
next | string | 0..1 | A URI linking 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 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:
Name | Type | Description |
---|---|---|
status | string | Comma separated alarm statuses, for example ACTIVE,CLEARED . |
source | string | Source device ID. |
withSourceAssets | boolean | When set to true also alarms for related source assets will be removed. When this parameter is provided also source must be defined. |
withSourceDevices | boolean | When set to true also alarms for related source devices will be removed. When this parameter is provided also source must be defined. |
resolved | boolean | When set to true only resolved alarms will be removed (the one with status CLEARED ), false means alarms with status ACTIVE or ACKNOWLEDGED . |
severity | string | Alarm severity, for example MINOR . |
dateFrom | datetime | Start date or date and time of alarm occurrence. |
dateTo | datetime | End date or date and time of alarm occurrence. |
type | string | Alarm type. |
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]
Name | Type | Occurs | Description | PUT/POST |
---|---|---|---|---|
id | string | 1 | Uniquely identifies an alarm. | No |
self | string | 1 | A URI linking to this resource. | No |
creationTime | datetime | 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 | datetime | 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 | datetime | 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" : { }
}