Operation

com.apama.cumulocity
Event Operation

Represents an operation executed on a Cumulocity device.

This event can be sent to Cumulocity to create/update an operation, and can also be received from Cumulocity as a notification.

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

 Operation("12345","deviceId",STATUS_PENDING,{"c8y_Message":{"text":"Hello Cumulocity device"}}) 
 Operation("12345","deviceId",STATUS_EXECUTING, {})

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

 // Create an operation:
 send Operation("","deviceId",STATUS_PENDING, {"c8y_Message":<any>{<any>"text":<any>"Hello Cumulocity device"}}) to Operation.SEND_CHANNEL; 
 // Update the status field:
 send Operation("12345","deviceId",STATUS_EXECUTING, new dictionary<string, any>) to Operation.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"` Channel to send the 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"` Channel for sending Operations.
`string`	`STATUS_EXECUTING := "EXECUTING"` Status value when an operation is EXECUTING.
`string`	`STATUS_FAILED := "FAILED"` Status value when an operation is FAILED.
`string`	`STATUS_PENDING := "PENDING"` Status value when an operation is PENDING.
`string`	`STATUS_SUCCESSFUL := "SUCCESSFUL"` Status value when an operation is SUCCESSFUL.
`string`	`SUBSCRIBE_CHANNEL := "cumulocity.measurements"` Channel for receiving Operation notifications.

Field summary
`string`	`id` Unique identifier for this Operation.
`string`	`source` Identifier of the ManagedObject to send the operation to.
`string`	`status` The status of the operation as defined by the STATUS_* constants: SUCCESSFUL, FAILED, EXECUTING or PENDING.
`dictionary<string, any>`	`params` Any extra parameters available on the `Operation`. Note: This dictionary cannot be manipulated to delete fragments in the `Operation`.

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

Channel to send the 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"

Channel for sending Operations.

Since:: 10.5.2.0

STATUS_EXECUTING

string STATUS_EXECUTING := "EXECUTING"

Status value when an operation is EXECUTING.

Since:: 10.15.4.0

STATUS_FAILED

string STATUS_FAILED := "FAILED"

Status value when an operation is FAILED.

Since:: 10.15.4.0

STATUS_PENDING

string STATUS_PENDING := "PENDING"

Status value when an operation is PENDING.

Since:: 10.15.4.0

STATUS_SUCCESSFUL

string STATUS_SUCCESSFUL := "SUCCESSFUL"

Status value when an operation is SUCCESSFUL.

Since:: 10.15.4.0

SUBSCRIBE_CHANNEL

string SUBSCRIBE_CHANNEL := "cumulocity.measurements"

Channel for receiving Operation notifications.

Since:: 10.5.2.0

Field detail

id

string id

Unique identifier for this Operation.

Supply as empty if creating a new Operation

params

dictionary<string, any> params

Any extra parameters available on the Operation. Note: This dictionary cannot be manipulated to delete fragments in the Operation.

However, the fragments in the Operation 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 ManagedObject to send the operation to.

status

string status

The status of the operation as defined by the STATUS_* constants: SUCCESSFUL, FAILED, EXECUTING or PENDING.

Action detail

isCreate

boolean isCreate()

Check if this Operation instance was as a result of an operation being created in Cumulocity.

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

isUpdate

boolean isUpdate()

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

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

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

Since:: 10.7.1.0

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

withChannelResponse

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

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

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

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

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

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

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

com.apama.cumulocityEvent Operation