Event

com.apama.cumulocity
Event Event

Cumulocity events (not to be confused with Apama events) are used to pass real-time information through Cumulocity IoT, for example when something happens in the sensor network, or when a security audit event is logged.

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

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

 Event("21","c8y_EntranceEvent","12346082",1464364483.396,"Entrance event triggered.",{"distance":any(float,317.0)}) 
 Event("22","com_cumulocity_events_TamperEvent","12345",1464364483.396,"Tamper sensor triggered",{"history":{}})

To create a new Cumulocity event or update an existing event for a device, send an Event to Event.SEND_CHANNEL. For example:

 // Create an Event:
 send Event("","c8y_EntranceEvent","12346082",1464364483.396,"Entrance event triggered.",{"distance":any(float,317.0)}) to Event.SEND_CHANNEL; 
 // Update the text field:
 send Event("22","c8y_EntranceEvent","12346082",1492676483.396,"Tamper sensor triggered",new dictionary<string, any>) to Event.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. If the event was created outside of Cumulocity, then both isCreate() and isUpdate() will return false.

Constant summary
`string`	`CHANNEL := "CumulocityIoTGenericChain"` The channel for sending updates/ new Events 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 Events.
`string`	`SUBSCRIBE_CHANNEL := "cumulocity.measurements"` The channel for receiving Event notifications.

Field summary
`string`	`id` Unique identifier for this Event.
`string`	`type` The type of the Cumulocity event.
`string`	`source` Identifier of the managed object which is the source of the event.
`float`	`time` Timestamp of the event.
`string`	`text` Text or message of the Event.
`dictionary<string, any>`	`params` Any other properties available on the `Event`. Note: This dictionary cannot be manipulated to delete fragments in the `Event`.

Action summary
`boolean`	`isCreate()` Check if this Event instance was as a result of an event being created in Cumulocity.
`boolean`	`isUpdate()` Check if this Event instance was as a result of an Event being updated in Cumulocity.
`com.apama.cumulocity.ResponseWrapper`	`withChannelResponse(integer reqId, dictionary<string, string> headers)` Create or update an Event in Cumulocity and receive a response event confirming the change on Event.SUBSCRIBE_CHANNEL.
`com.apama.cumulocity.ResponseWrapper`	`withResponse(integer reqId, dictionary<string, string> headers)` Create or update an Event 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 Event.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 Events 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 Events.

Since:: 10.5.2.0

SUBSCRIBE_CHANNEL

string SUBSCRIBE_CHANNEL := "cumulocity.measurements"

The channel for receiving Event notifications.

Since:: 10.5.2.0

Field detail

id

string id

Unique identifier for this Event.

Supply as empty if creating a new Event.

params

dictionary<string, any> params

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

However, the fragments in the Event 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

source

string source

Identifier of the managed object which is the source of the event.

text

string text

Text or message of the Event.

time

float time

Timestamp of the event.

type

string type

The type of the Cumulocity event.

Action detail

isCreate

boolean isCreate()

Check if this Event instance was as a result of an event being created in Cumulocity.

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

Since:: 10.7.1.0

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

isUpdate

boolean isUpdate()

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

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

Since:: 10.7.1.0

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

withChannelResponse

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

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

Just sending an Event is fire and forget. If your application requires an acknowledgement or the ID of the Event created or updated on Event.SUBSCRIBE_CHANNEL channel, then use the withChannelResponse API. You will need to subscribe to Event.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 Event. 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(Event.SUBSCRIBE_CHANNEL);
Event e := new Event;
// set fields in e
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 e.withChannelResponse(reqId, { "X-Cumulocity-Processing-Mode": "TRANSIENT" }) to Event.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 an Event.; com.apama.cumulocity.ObjectCommitFailed - Failed to create or update an Event.

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 Event.SUBSCRIBE_CHANNEL channel.]

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

Just sending an Event is fire and forget. If your application requires an acknowledgement or the ID of the Event 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 Event. 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:

Event e := new Event;
// set fields in e
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 e.withResponse(reqId, { "X-Cumulocity-Processing-Mode": "TRANSIENT" }) to Event.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 an Event.; com.apama.cumulocity.ObjectCommitFailed - Failed to create or update an Event.; com.apama.cumulocity.Event.withChannelResponse() - to receive confirmation on Event.SUBSCRIBE_CHANNEL channel.

com.apama.cumulocityEvent Event