Measurement

com.apama.cumulocity
Event Measurement

Represents a measurement associated with a managed object.

This event can be sent to Cumulocity to create new measurements for a device, and can also be received from Cumulocity to notify when a device has sent a new measurement.

Receiving Measurement notifications requires configuration property subscribeToAllMeasurements to be set to true, and the notifications go to Measurement.SUBSCRIBE_CHANNEL.

To create a Measurement, send a Measurement event object to Measurement.SEND_CHANNEL. For example:

 send Measurement("","c8y_DistanceMeasurement","123",1464359005.396,{"distance":{"distance":com.apama.cumulocity.MeasurementValue(3.44,"mm",new dictionary<string, any>)}},new dictionary<string, any>) to Measurement.SEND_CHANNEL; 
 send Measurement("","c8y_LightMeasurement","12346081",1464359004.89,{"c8y_LightMeasurement":{"e":com.apama.cumulocity.MeasurementValue(108.1,"lux",new dictionary<string, any>)}},new dictionary<string, any>) to Measurement.SEND_CHANNEL;

You cannot update a Measurement once it has been created.

See Also:: com.apama.cumulocity.MeasurementFragment - It is also possible to work directly with the fragments making up a measurement using the MeasurementFragment event.

Constant summary
`string`	`CHANNEL := "cumulocity.measurements"` The channel to which `Measurement` events are sent from the transport. Deprecated: [This channel constant has been deprecated. Use SUBSCRIBE_CHANNEL instead.]
`string`	`CREATE_CHANNEL := "CumulocityIoTGenericChain"` The channel to send a measurement event to create a new measurement object in Cumulocity. Deprecated: [This channel constant has been deprecated. Use SEND_CHANNEL instead.]
`string`	`SEND_CHANNEL := "CumulocityIoTGenericChain"` The channel to send a measurement event to create a new measurement object in Cumulocity.
`string`	`SUBSCRIBE_CHANNEL := "cumulocity.measurements"` The channel to which `Measurement` events are sent from the transport.

Field summary
`string`	`id` Unique identifier for this Measurement.
`string`	`type` The type of the measurement.
`string`	`source` The unique identifier of the managed object source for the measurement.
`float`	`time` The time the measurement was taken, represented as the number of seconds since the epoch (1st January 1970).
`dictionary<string, dictionary<string, com.apama.cumulocity.MeasurementValue>>`	`measurements` Measurement values mapped by fragment and series.
`dictionary<string, any>`	`params` This dictionary is available to hold any other data associated with the measurement.

Action summary
`com.apama.cumulocity.Measurement`	`static` `createFromFragments(sequence<com.apama.cumulocity.MeasurementFragment> fragments)` Create Measurement event from sequence of MeasurementFragments.
`sequence<com.apama.cumulocity.MeasurementFragment>`	`getFragments()` Split a measurement into a sequence of MeasurementFragments.
`com.apama.cumulocity.ResponseWrapper`	`withChannelResponse(integer reqId, dictionary<string, string> headers)` Create a Measurement in Cumulocity and receive a response event confirming the change on Measurement.SUBSCRIBE_CHANNEL.
`com.apama.cumulocity.ResponseWrapper`	`withResponse(integer reqId, dictionary<string, string> headers)` Create a Measurement 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 Measurement.SUBSCRIBE_CHANNEL channel.]

Constant detail

CHANNEL

string CHANNEL := "cumulocity.measurements"

Deprecated:: [This channel constant has been deprecated. Use SUBSCRIBE_CHANNEL instead.]

The channel to which Measurement events are sent from the transport.

CREATE_CHANNEL

string CREATE_CHANNEL := "CumulocityIoTGenericChain"

Deprecated:: [This channel constant has been deprecated. Use SEND_CHANNEL instead.]

The channel to send a measurement event to create a new measurement object in Cumulocity.

SEND_CHANNEL

string SEND_CHANNEL := "CumulocityIoTGenericChain"

The channel to send a measurement event to create a new measurement object in Cumulocity.

Since:: 10.5.2.0

SUBSCRIBE_CHANNEL

string SUBSCRIBE_CHANNEL := "cumulocity.measurements"

The channel to which Measurement events are sent from the transport.

Since:: 10.5.2.0

Field detail

id

string id

Unique identifier for this Measurement.

Cumulocity sets the id upon creation, and it will be visible in any Measurement that is received.

measurements

dictionary<string, dictionary<string, com.apama.cumulocity.MeasurementValue>> measurements

Measurement values mapped by fragment and series.

Dictionary mapping from fragment name to a dictionary mapping from series name to MeasurementValue objects.

params

dictionary<string, any> params

This dictionary is available to hold any other data associated with the measurement.

source

string source

The unique identifier of the managed object source for the measurement.

time

float time

The time the measurement was taken, represented as the number of seconds since the epoch (1st January 1970).

type

string type

The type of the measurement.

Action detail

createFromFragments

com.apama.cumulocity.Measurement static createFromFragments(sequence<com.apama.cumulocity.MeasurementFragment> fragments)

Create Measurement event from sequence of MeasurementFragments.

All the MeasurementFragment objects in sequence should have same id, type, source and time. Else a CorruptFragmentSeriesException exception is thrown.

Parameters:: fragments

getFragments

sequence<com.apama.cumulocity.MeasurementFragment> getFragments()

Split a measurement into a sequence of MeasurementFragments.

The sequence size is the same as the number of Fragments present in the Measurement. A Measurement with no Fragment will fetch an empty sequence.

withChannelResponse

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

Create a Measurement in Cumulocity and receive a response event confirming the change on Measurement.SUBSCRIBE_CHANNEL.

Just sending a Measurement is fire and forget. If your application requires an acknowledgement or the ID of the Measurement created on Measurement.SUBSCRIBE_CHANNEL channel, then use the withChannelResponse API. You will need to subscribe to Measurement.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 Measurement. 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(Measurement.SUBSCRIBE_CHANNEL);
Measurement m := new Measurement;
// set fields in m
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 m.withChannelResponse(reqId, { "X-Cumulocity-Processing-Mode": "TRANSIENT" }) to Measurement.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 request. This can be used to explicitly control the processing mode of the create request.

See Also:: com.apama.cumulocity.ObjectCommitted - Successfully created a Measurement.; com.apama.cumulocity.ObjectCommitFailed - Failed to create a Measurement.

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

Create a Measurement in Cumulocity and receive a response event on default channel, confirming the change.

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

Measurement m := new Measurement;
// set fields in m
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 m.withResponse(reqId, { "X-Cumulocity-Processing-Mode": "TRANSIENT" }) to Measurement.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 request. This can be used to explicitly control the processing mode of the create request.

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

com.apama.cumulocityEvent Measurement