create alarm

*Since TB Version 2.0*

This Node tries to load the latest Alarm with configured Alarm Type for Message Originator. If Uncleared Alarm exist, then this Alarm will be updated, otherwise a new Alarm will be created.

Node Configuration:

Alarm Details Builder script
Alarm Type - any string that represents Alarm Type
Alarm Severity - {CRITICAL | MAJOR | MINOR | WARNING | INDETERMINATE}
is Propagate - whether Alarm should be propagated to all parent related entities.

Note: Since TB Version 2.3.0 the rule node has the ability to:

read alarm config from message:
get alarm type using pattern with fields from message metadata:

Note: Since TB Version 2.4.3 the rule node has the ability to:

filter propagation to parent entities by relation types:

Alarm Details Builder script used for generating Alarm Details JsonNode. It is useful for storing additional parameters inside Alarm. For example you can save attribute name/value pair from Original Message payload or Metadata.

Alarm Details Builder script should return details object.

Message payload can be accessed via msg property. For example msg.temperature
Message metadata can be accessed via metadata property. For example metadata.customerName
Message type can be accessed via msgType property. For example msgType

Optional: previous Alarm Details can be accessed via metadata.prevAlarmDetails. If previous Alarm does not exist, this field will not be present in Metadata. Note that metadata.prevAlarmDetails is a raw String field and it needs to be converted into object using this construction:

var details = {};
if (metadata.prevAlarmDetails) {
details = JSON.parse(metadata.prevAlarmDetails);
}

Alarm Details Builder script function can be verified using Test JavaScript function.

Example of Details Builder Function

This function takes count property from previous Alarm and increment it. Also put temperature attribute from inbound Message payload into Alarm details.

var details = {temperature: msg.temperature, count: 1};

if (metadata.prevAlarmDetails) {
var prevDetails = JSON.parse(metadata.prevAlarmDetails);
if(prevDetails.count) {
details.count = prevDetails.count + 1;
}
}

return details;

Alarm created/updated with those properties:

Alarm details - object returned from Alarm Details Builder script
Alarm status - if new alarm -> ACTIVE_UNACK. If existing Alarm -> does not changed
Severity - value from Node Configuration
Propagation - value from Node Configuration
Alarm type - value from Node Configuration
Alarm start time - if new alarm -> current system time. If existing Alarm -> does not changed
Alarm end time - current system time

Outbound message will have the following structure:

Message Type - ALARM
Originator - the same originator from inbound Message
Payload - JSON representation of new Alarm that was created/updated
Metadata - all fields from original Message Metadata

After new Alarm created, Outbound message will contain additional property inside Metadata - isNewAlarm with true value. Message will be passed via Created chain.

After existing Alarm updated, Outbound message will contain additional property inside Metadata - isExistingAlarm with true value. Message will be passed via Updated chain.

Here is an example of Outbound Message payload

{
"tenantId": {
"entityType": "TENANT",
"id": "22cd8888-5dac-11e8-bbab-ad47060c9bbb"
},
"type": "High Temperature Alarm",
"originator": {
"entityType": "DEVICE",
"id": "11cd8777-5dac-11e8-bbab-ad55560c9ccc"
},
"severity": "CRITICAL",
"status": "ACTIVE_UNACK",
"startTs": 1526985698000,
"endTs": 1526985698000,
"ackTs": 0,
"clearTs": 0,
"details": {
"temperature": 70,
"ts": 1526985696000
},
"propagate": true,
"id": "33cd8999-5dac-11e8-bbab-ad47060c9431",
"createdTime": 1526985698000,
"name": "High Temperature Alarm"
}

More details about Alarms in the Thingsboard can be found in this tutorial

You can see the real life example, where this node is used, in the next tutorial:

Create and Clear Alarms