com.apama.cumulocity
Event ManagedObject


Represents a Cumulocity managed object (typically a device).

This event can be sent to Cumulocity to update an existing managed object, or can be received to notify of changes to a managed object.

Notifications are sent on the SUBSCRIBE_CHANNEL in various situations: on startup, in response to a RequestAllDevices event, or if a new ManagedObject is detected (and the configuration property subscribeToDevices is enabled). Here is an example of one of these notification events:
 com.apama.cumulocity.ManagedObject("49","","temp_sensor",["c8y_Restart"],["c8y_Temperature","c8y_Light"], ["childDevRefIds"],["childAstRefIds"],["devParentIds"],["assetParentIds"],{"lat":1.0},{"c8y_IsDevice":{}}) 


To create/update a ManagedObject, send a ManagedObject event object to ManagedObject.SEND_CHANNEL. For example:
// Create a ManagedObject:<br>
ManagedObject createManagedObject := new ManagedObject;
createManagedObject.name := "myDevice";
createManagedObject.params.add("c8y_IsDevice", new dictionary<any, any>);
send createManagedObject to ManagedObject.SEND_CHANNEL;

// Update the name:<br>
ManagedObject updateManagedObject := new ManagedObject;
updateManagedObject.id := "deviceId";
updateManagedObject.name := "myDevice_UpdatedName";
send updateManagedObject to ManagedObject.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.
See Also:
com.apama.cumulocity.RequestAllDevices

Constant summary
 stringCHANNEL := "cumulocity.devices"

The channel to which ManagedObject events are sent from the transport.
Deprecated:
[This channel constant has been deprecated. Use SUBSCRIBE_CHANNEL instead.]
 stringNOTIFICATION_CREATED := "CREATED"

Value of PARAM_NOTIFICATION that indicates this is a new object.
 stringNOTIFICATION_UPDATED := "UPDATED"

Value of PARAM_NOTIFICATION that indicates this is an update to an existing object.
 stringPARAM_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.
 stringSEND_CHANNEL := "CumulocityIoTGenericChain"

The channel to send a ManagedObject event to update an existing managed object in Cumulocity.
 stringSUBSCRIBE_CHANNEL := "cumulocity.devices"

The channel to which ManagedObject events are sent from the transport.
 stringUPDATE_CHANNEL := "CumulocityIoTGenericChain"

The channel to send a ManagedObject event to update an existing managed object in Cumulocity.
Deprecated:
[This channel constant has been deprecated. Use SEND_CHANNEL instead.]
 
Field summary
 stringid

The unique identifier for this specific managed object (device).
 stringtype

The type of the device.
 stringname

The name of this ManagedObject. Note: This does not have to be a unique value.
 sequence<string>supportedOperations

List of supported operations for this device.
 sequence<string>supportedMeasurements

List of supported measurements for this device.
 sequence<string>childDeviceIds

Ids of child devices. Note: This field cannot be set by sending ManagedObject events.
 sequence<string>childAssetIds

Ids of child assets. Note: This field cannot be set by sending ManagedObject events.
 sequence<string>deviceParentIds

Ids of parent devices. Note: This field cannot be set by sending ManagedObject events.
 sequence<string>assetParentIds

Ids of parent assets. Note: This field cannot be set by sending ManagedObject events.
 dictionary<stringfloat>position

Contains all numeric values within the 'c8y_Position' fragment. Typically these are latitude, longitude, altitude and accuracy. Note: This field cannot be used to delete the entire c8y_Position fragment.
 dictionary<stringany>params

Other fragments for this ManagedObject. Note: This dictionary cannot be manipulated to delete fragments in the ManagedObject.
 
Action summary
 dictionary<stringany>getC8yPosition()

Generates a c8y_Position object based on the relevant position and params within the ManagedObject.
 booleanisCreate()

Check if this ManagedObject instance was as a result of a managed object being created in Cumulocity.
 booleanisUpdate()

Check if this ManagedObject instance was as a result of a managed object being updated in Cumulocity.
 voidsetC8yPosition(any c8y_Position)

Sets the c8y_Position members of the ManagedObject directly from a dictionary.
 com.apama.cumulocity.ResponseWrapperwithChannelResponse(integer reqId, dictionary<stringstring> headers)

Create or update a ManagedObject in Cumulocity and receive a response event confirming the change on ManagedObject.SUBSCRIBE_CHANNEL channel.
 com.apama.cumulocity.ResponseWrapperwithResponse(integer reqId, dictionary<stringstring> headers)

Create or update a ManagedObject in Cumulocity IoT and receive a response event on the default channel, confirming the change.
Deprecated:
[This API has been deprecated. Use withChannelResponse API to receive confirmation on ManagedObject.SUBSCRIBE_CHANNEL channel.]
 
Constant detail

CHANNEL

string CHANNEL := "cumulocity.devices"
Deprecated:
[This channel constant has been deprecated. Use SUBSCRIBE_CHANNEL instead.]
The channel to which ManagedObject events are sent from the transport.

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 to send a ManagedObject event to update an existing managed object in Cumulocity.
Since:
10.5.2.0

SUBSCRIBE_CHANNEL

string SUBSCRIBE_CHANNEL := "cumulocity.devices"
The channel to which ManagedObject events are sent from the transport.
Since:
10.5.2.0

UPDATE_CHANNEL

string UPDATE_CHANNEL := "CumulocityIoTGenericChain"
Deprecated:
[This channel constant has been deprecated. Use SEND_CHANNEL instead.]
The channel to send a ManagedObject event to update an existing managed object in Cumulocity.
Field detail

assetParentIds

sequence<stringassetParentIds
Ids of parent assets. Note: This field cannot be set by sending ManagedObject events.

A ManagedObject can only have a single parent. This sequence is a hierarchical list of the ManagedObject's parents. Thus, the first entry is the ManagedObject's direct parent. The second entry is the ManagedObject's grandparent, ie. the parent of its parent. Each member of the sequence ascends the hierarchy to the next parent. This means that the entire hierarchy is available without having to query each parent in turn.

Note that this sequence is not populated on ManagedObject notifications sent to the ManagedObject.SUBSCRIBE_CHANNEL. If you wish to access the parent hierarchy of a ManagedObject received this way, you must send a FindManagedObject request for the ManagedObject in question.

childAssetIds

sequence<stringchildAssetIds
Ids of child assets. Note: This field cannot be set by sending ManagedObject events.

A ManagedObject can have more than one child. This sequence is a list of all the children for the ManagedObject. The list does not descend beyond the immediate children within the hierarchy.

This sequence is populated on ManagedObject notifications sent to the ManagedObject.SUBSCRIBE_CHANNEL.

childDeviceIds

sequence<stringchildDeviceIds
Ids of child devices. Note: This field cannot be set by sending ManagedObject events.

A ManagedObject can have more than one child. This sequence is a list of all the children for the ManagedObject. The list does not descend beyond the immediate children within the hierarchy.

This sequence is populated on ManagedObject notifications sent to the ManagedObject.SUBSCRIBE_CHANNEL.

deviceParentIds

sequence<stringdeviceParentIds
Ids of parent devices. Note: This field cannot be set by sending ManagedObject events.

A ManagedObject can only have a single parent. This sequence is a hierarchical list of the ManagedObject's parents. Thus, the first entry is the ManagedObject's direct parent. The second entry is the ManagedObject's grandparent, ie. the parent of its parent. Each member of the sequence ascends the hierarchy to the next parent. This means that the entire hierarchy is available without having to query each parent in turn.

Note that this sequence is not populated on ManagedObject notifications sent to the ManagedObject.SUBSCRIBE_CHANNEL. If you wish to access the parent hierarchy of a ManagedObject received this way, you must send a FindManagedObject request for the ManagedObject in question.

id

string id
The unique identifier for this specific managed object (device).

Supply as an empty string when creating a new managed object.

name

string name
The name of this ManagedObject. Note: This does not have to be a unique value.

params

dictionary<stringanyparams
Other fragments for this ManagedObject. Note: This dictionary cannot be manipulated to delete fragments in the ManagedObject.

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

position

dictionary<stringfloatposition
Contains all numeric values within the 'c8y_Position' fragment. Typically these are latitude, longitude, altitude and accuracy. Note: This field cannot be used to delete the entire c8y_Position fragment.

Non-numeric values within the 'c8y_Position' fragment are added to the params dictionary as individual elements, rather than as a dictionary. Eg. "c8y_Position.string_value".

This field can be used to clear individual position elements but not the entire c8y_Position fragment. However, the entire c8y_Position fragment can be cleared using the Cumulocity IoT REST API, which can be invoked in EPL by using GenericRequest events.
See Also:
com.apama.cumulocity.GenericRequest

supportedMeasurements

sequence<stringsupportedMeasurements
List of supported measurements for this device.

supportedOperations

sequence<stringsupportedOperations
List of supported operations for this device.

type

string type
The type of the device.
Action detail

getC8yPosition

dictionary<stringanygetC8yPosition()
Generates a c8y_Position object based on the relevant position and params within the ManagedObject.

The generated object can be directly assigned as a c8y_Position fragment within the params of other event types.

The use of this action is only necessary in cases where there are non-numeric properties in the c8y_Position fragment. If all the values are numeric, it is more efficient just to use the position member of the ManagedObject
Returns:
The position data and any c9y_Position data in the params as a single c8y_Position object that can be added as a fragment to other events.
Since:
10.15.5.0

isCreate

boolean isCreate()
Check if this ManagedObject instance was as a result of a managed object being created in Cumulocity.

For ManagedObject 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.ManagedObject.isUpdate()

isUpdate

boolean isUpdate()
Check if this ManagedObject instance was as a result of a managed object being updated in Cumulocity.

For ManagedObject 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.ManagedObject.isCreate()

setC8yPosition

void setC8yPosition(any c8y_Position)
Sets the c8y_Position members of the ManagedObject directly from a dictionary.

This allows the direct use of c8y_Position objects derived from other events where it is generally stored as a fragment in the params dictionary, and will be obtained as an object of the any type. The any typed object must contain a dictionary with string typed keys, unless it is an empty any, which will be treated the same way as an empty dictionary. This allows the pattern in the example below.

on all Event(type="locationUpdate") as evt {
ManagedObject mo := new ManagedObject;
mo.id := evt.source;
mo.setC8yPosition(evt.params.getOrDefault("c8y_Position"));
send mo to ManagedObject.SEND_CHANNEL;
}
Parameters:
c8y_Position - The c8y_Position fragment to be set on the ManagedObject. This will completely overwrite any previous c8y_Position data. This must be a dictionary with string keys.
Since:
10.15.5.0

withChannelResponse

com.apama.cumulocity.ResponseWrapper withChannelResponse(integer reqId, dictionary<stringstring> headers)
Create or update a ManagedObject in Cumulocity and receive a response event confirming the change on ManagedObject.SUBSCRIBE_CHANNEL channel.

Just sending a ManagedObject is fire and forget. If your application requires an acknowledgement or the ID of the ManagedObject created or updated on ManagedObject.SUBSCRIBE_CHANNEL channel, then use the withChannelResponse API. You will need to subscribe to ManagedObject.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 ManagedObject. 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(ManagedObject.SUBSCRIBE_CHANNEL);
ManagedObject m := new ManagedObject;
// set fields in m
integer reqId := com.apama.cumulocity.Util.generateReqId();
// myapp is the user application key
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 m.withChannelResponse(reqId, {"X-Cumulocity-Application-Key": "myapp"}) to ManagedObject.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 ManagedObject.
com.apama.cumulocity.ObjectCommitFailed - Failed to create or update a ManagedObject.

withResponse

com.apama.cumulocity.ResponseWrapper withResponse(integer reqId, dictionary<stringstring> headers)
Deprecated:
[This API has been deprecated. Use withChannelResponse API to receive confirmation on ManagedObject.SUBSCRIBE_CHANNEL channel.]
Create or update a ManagedObject in Cumulocity IoT and receive a response event on the default channel, confirming the change.

Just sending a ManagedObject is fire and forget. If your application requires an acknowledgement or the ID of the ManagedObject 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 ManagedObject. 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:
ManagedObject m := new ManagedObject;
// set fields in m
integer reqId := com.apama.cumulocity.Util.generateReqId();
// myapp is the user application key
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 m.withResponse(reqId, {"X-Cumulocity-Application-Key": "myapp"}) to ManagedObject.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 ManagedObject.
com.apama.cumulocity.ObjectCommitFailed - Failed to create or update a ManagedObject.
com.apama.cumulocity.ManagedObject.withChannelResponse() - to receive confirmation on ManagedObject.SUBSCRIBE_CHANNEL channel.