Alarm

com.apama.cumulocity
Event Alarm

Represents an alarm, used to indicate a warning or error associated with a specific source managed object such as when the temperature of a fridge increases above a particular threshold.

This event can be sent to Cumulocity to create an alarm, and can also be received from Cumulocity as a notification when a device or other application creates an Alarm, or updates an Alarm.

Receiving Alarm notifications requires configuration property subscribeToAllMeasurements to be set to true, and the notifications go to Alarm.SUBSCRIBE_CHANNEL. For example:

 Alarm("22","c8y_UnavailabilityAlarm","12669915",1464365565.661,"No communication with device since 2016-05-27T18:11:23.886+02:00",STATUS_ACKNOWLEDGED,SEVERITY_MAJOR,1,{}) 
 Alarm("11","com_cumulocity_events_BatteryWarning","1122",1464365565.661,"Low battery level",STATUS_ACTIVE,SEVERITY_MINOR,1,{"history":{}})

To create/update an Alarm, send an Alarm event object to Alarm.SEND_CHANNEL. For example:

 // Create an Alarm:
 send Alarm("","c8y_UnavailabilityAlarm","12669915",1464365565.661,"No communication with device since 2016-05-27T18:11:23.886+02:00",STATUS_ACKNOWLEDGED,SEVERITY_MAJOR,1,new dictionary<string,any>) to Alarm.SEND_CHANNEL; 
 // Update the text, status and severity fields:
 send Alarm("11","c8y_UnavailabilityAlarm","12669915",1464365565.661,"Low battery level",STATUS_ACTIVE,SEVERITY_MINOR,1,new dictionary<string,any>) to Alarm.SEND_CHANNEL;

When listening for events of this type from Cumulocity, use the isCreate() and/or isUpdate() actions within the listener to distinguish between create and update events.

Constant summary
`string`	`CHANNEL := "CumulocityIoTGenericChain"` The channel for sending updates/ new Alarms to. Deprecated: [This channel constant has been deprecated. Use SEND_CHANNEL for sending and SUBSCRIBE_CHANNEL for receiving events.]
`string`	`NOTIFICATION_CREATED := "CREATED"` Value of PARAM_NOTIFICATION that indicates this is a new object.
`string`	`NOTIFICATION_UPDATED := "UPDATED"` Value of PARAM_NOTIFICATION that indicates this is an update to an existing object.
`string`	`PARAM_NOTIFICATION := ".apama_notificationType"` Entry in params that identifies if this is a new object or an update to an existing object. Entry will have a value matching either NOTIFICATION_CREATED or NOTIFICATION_UPDATED.
`string`	`SEND_CHANNEL := "CumulocityIoTGenericChain"` The channel for sending Alarms.
`string`	`SEVERITY_CRITICAL := "CRITICAL"` Value when alarm severity is CRITICAL.
`string`	`SEVERITY_MAJOR := "MAJOR"` Value when alarm severity is MAJOR.
`string`	`SEVERITY_MINOR := "MINOR"` Value when alarm severity is MINOR.
`string`	`SEVERITY_WARNING := "WARNING"` Value when alarm severity is WARNING.
`string`	`STATUS_ACKNOWLEDGED := "ACKNOWLEDGED"` Status value when an alarm is ACKNOWLEDGED.
`string`	`STATUS_ACTIVE := "ACTIVE"` Status value when an alarm is ACTIVE.
`string`	`STATUS_CLEARED := "CLEARED"` Status value when an alarm is CLEARED.
`string`	`SUBSCRIBE_CHANNEL := "cumulocity.measurements"` The channel for receiving Alarm notifications.

Field summary
`string`	`id` Unique identifier for this Alarm.
`string`	`type` The type of the Cumulocity event.
`string`	`source` Identifier of the managed object associated with the event.
`float`	`time` Timestamp of the event.
`string`	`text` Text or message of the Alarm.
`string`	`status` The status of the alarm as defined by the STATUS_* constants: ACTIVE, ACKNOWLEDGED or CLEARED.
`string`	`severity` The severity of the alarm as defined by the SEVERITY_* constants: CRITICAL, MAJOR, MINOR or WARNING.
`integer`	`count` The number of times this alarm has been sent.
`dictionary<string, any>`	`params` Any other properties available on the `Alarm`. Note: This dictionary cannot be manipulated to delete fragments in the `Alarm`.

Action summary
`boolean`	`isCreate()` Check if this Alarm instance was as a result of an alarm being created in Cumulocity.
`boolean`	`isUpdate()` Check if this Alarm instance was as a result of an alarm being updated in Cumulocity.
`com.apama.cumulocity.ResponseWrapper`	`withChannelResponse(integer reqId, dictionary<string, string> headers)` Create or update an Alarm in Cumulocity and receive a response event confirming the change on Alarm.SUBSCRIBE_CHANNEL channel.
`com.apama.cumulocity.ResponseWrapper`	`withResponse(integer reqId, dictionary<string, string> headers)` Create or update an Alarm in Cumulocity and receive a response event on default channel, confirming the change. Deprecated: [This API has been deprecated. Use withChannelResponse API to receive confirmation on Alarm.SUBSCRIBE_CHANNEL channel.]

Constant detail

CHANNEL

string CHANNEL := "CumulocityIoTGenericChain"

Deprecated:: [This channel constant has been deprecated. Use SEND_CHANNEL for sending and SUBSCRIBE_CHANNEL for receiving events.]

The channel for sending updates/ new Alarms to.

NOTIFICATION_CREATED

string NOTIFICATION_CREATED := "CREATED"

Value of PARAM_NOTIFICATION that indicates this is a new object.

Since:: 10.5.4.0

NOTIFICATION_UPDATED

string NOTIFICATION_UPDATED := "UPDATED"

Value of PARAM_NOTIFICATION that indicates this is an update to an existing object.

Since:: 10.5.4.0

PARAM_NOTIFICATION

string PARAM_NOTIFICATION := ".apama_notificationType"

Entry in params that identifies if this is a new object or an update to an existing object. Entry will have a value matching either NOTIFICATION_CREATED or NOTIFICATION_UPDATED.

Since:: 10.5.4.0

SEND_CHANNEL

string SEND_CHANNEL := "CumulocityIoTGenericChain"

The channel for sending Alarms.

Since:: 10.5.2.0

SEVERITY_CRITICAL

string SEVERITY_CRITICAL := "CRITICAL"

Value when alarm severity is CRITICAL.

Since:: 10.15.4.0

SEVERITY_MAJOR

string SEVERITY_MAJOR := "MAJOR"

Value when alarm severity is MAJOR.

Since:: 10.15.4.0

SEVERITY_MINOR

string SEVERITY_MINOR := "MINOR"

Value when alarm severity is MINOR.

Since:: 10.15.4.0

SEVERITY_WARNING

string SEVERITY_WARNING := "WARNING"

Value when alarm severity is WARNING.

Since:: 10.15.4.0

STATUS_ACKNOWLEDGED

string STATUS_ACKNOWLEDGED := "ACKNOWLEDGED"

Status value when an alarm is ACKNOWLEDGED.

Since:: 10.15.4.0

STATUS_ACTIVE

string STATUS_ACTIVE := "ACTIVE"

Status value when an alarm is ACTIVE.

Since:: 10.15.4.0

STATUS_CLEARED

string STATUS_CLEARED := "CLEARED"

Status value when an alarm is CLEARED.

Since:: 10.15.4.0

SUBSCRIBE_CHANNEL

string SUBSCRIBE_CHANNEL := "cumulocity.measurements"

The channel for receiving Alarm notifications.

Since:: 10.5.2.0

Field detail

count

integer count

The number of times this alarm has been sent.

id

string id

Unique identifier for this Alarm.

Supply as empty if creating a new Alarm.

params

dictionary<string, any> params

Any other properties available on the Alarm. Note: This dictionary cannot be manipulated to delete fragments in the Alarm.

However, the fragments in the Alarm can be deleted using the Cumulocity IoT REST API, which can be invoked in EPL by using GenericRequest events.

See Also:: com.apama.cumulocity.GenericRequest

severity

string severity

The severity of the alarm as defined by the SEVERITY_* constants: CRITICAL, MAJOR, MINOR or WARNING.

source

string source

Identifier of the managed object associated with the event.

status

string status

The status of the alarm as defined by the STATUS_* constants: ACTIVE, ACKNOWLEDGED or CLEARED.

text

string text

Text or message of the Alarm.

time

float time

Timestamp of the event.

type

string type

The type of the Cumulocity event.

Action detail

isCreate

boolean isCreate()

Check if this Alarm instance was as a result of an alarm being created in Cumulocity.

For Alarm events that have come from Cumulocity, only one of isCreate() or isUpdate() will return true.

Throws:: Throws IllegalStateException if called on an instance that did not come from Cumulocity.

Since:: 10.7.1.0

See Also:: com.apama.cumulocity.Alarm.isUpdate()

isUpdate

boolean isUpdate()

Check if this Alarm instance was as a result of an alarm being updated in Cumulocity.

For Alarm events that have come from Cumulocity, only one of isCreate() or isUpdate() will return true.

Throws:: Throws IllegalStateException if called on Alarm events that did not come from Cumulocity

Since:: 10.7.1.0

See Also:: com.apama.cumulocity.Alarm.isCreate()

withChannelResponse

com.apama.cumulocity.ResponseWrapper withChannelResponse(integer reqId, dictionary<string, string> headers)

Create or update an Alarm in Cumulocity and receive a response event confirming the change on Alarm.SUBSCRIBE_CHANNEL channel.

Just sending an Alarm is fire and forget. If your application requires an acknowledgement or the ID of the Alarm created or updated on Event.SUBSCRIBE_CHANNEL, then use the withChannelResponse API. You will need to subscribe to Alarm.SUBSCRIBE_CHANNEL channel. This API will create an event that can be sent as normal and get a response from Cumulocity for the newly created or updated Alarm. The responses are either an ObjectCommitted event or an ObjectCommitFailed event. The withChannelResponse API also allows you to provide headers to the create or update request. For example:

monitor.subscribe(Alarm.SUBSCRIBE_CHANNEL);
Alarm a := new Alarm;
// set fields in a
integer reqId := com.apama.cumulocity.Util.generateReqId();
on ObjectCommitted(reqId=reqId) as commit and not ObjectCommitFailed(reqId=reqId) {
    // do something
}
on ObjectCommitFailed(reqId=reqId) as failure and not ObjectCommitted(reqId=reqId) {
    // do something
}
send a.withChannelResponse(reqId, { "X-Cumulocity-Processing-Mode": "TRANSIENT" }) to Alarm.SEND_CHANNEL;

Parameters:: reqId - A request identifier generated from Util.generateReqId(). The response from Cumulocity will have the matching request identifier.; headers - Set headers of the create/update request. This can be used to explicitly control the processing mode of the create/update request.

See Also:: com.apama.cumulocity.ObjectCommitted - Successfully created or updated a Alarm.; com.apama.cumulocity.ObjectCommitFailed - Failed to create or update a Alarm.

withResponse

com.apama.cumulocity.ResponseWrapper withResponse(integer reqId, dictionary<string, string> headers)

Deprecated:: [This API has been deprecated. Use withChannelResponse API to receive confirmation on Alarm.SUBSCRIBE_CHANNEL channel.]

Create or update an Alarm in Cumulocity and receive a response event on default channel, confirming the change.

Just sending an Alarm is fire and forget. If your application requires an acknowledgement or the ID of the Alarm created or updated, then use the withResponse API. This API will create an event that can be sent as normal and get a response from Cumulocity for the newly created or updated Alarm. The responses are sent to default channel and hence can be listened for only in the main context. The responses are either an ObjectCommitted event or an ObjectCommitFailed event. The withResponse API also allows you to provide headers to the create or update request. For example:

Alarm a := new Alarm;
// set fields in a
integer reqId := com.apama.cumulocity.Util.generateReqId();
on ObjectCommitted(reqId=reqId) as commit and not ObjectCommitFailed(reqId=reqId) {
    // do something
}
on ObjectCommitFailed(reqId=reqId) as failure and not ObjectCommitted(reqId=reqId) {
    // do something
}
send a.withResponse(reqId, { "X-Cumulocity-Processing-Mode": "TRANSIENT" }) to Alarm.SEND_CHANNEL;

Parameters:: reqId - A request identifier generated from Util.generateReqId(). The response from Cumulocity will have the matching request identifier.; headers - Set headers of the create/update request. This can be used to explicitly control the processing mode of the create/update request.

See Also:: com.apama.cumulocity.ObjectCommitted - Successfully created or updated a Alarm.; com.apama.cumulocity.ObjectCommitFailed - Failed to create or update a Alarm.; com.apama.cumulocity.Alarm.withChannelResponse() - to receive confirmation on Alarm.SUBSCRIBE_CHANNEL channel.

com.apama.cumulocityEvent Alarm