MeasurementFragment

com.apama.cumulocity
Event MeasurementFragment

Represents a measurement fragment. This event can be sent to Cumulocity to create a measurement fragment, and can also be received from Cumulocity as a notification.

MeasurementFragment can be used when we require filtering based on the fragments or series making up each measurement. Instead of listening for all measurements and looking inside a dictionary we can listen for measurement fragments directly. This will improve listener performance. We can also use measurement fragments when we have just single fragment and series. This makes code simpler.

To receive measurement fragments you should subscribe to MeasurementFragment.SUBSCRIBE_CHANNEL. For example:

 MeasurementFragment("1001","c8y_LightMeasurement","12346081",1464359004.89,"c8y_LightMeasurement","e", 108.1, "lux",{}) 
 MeasurementFragment("1002","c8y_DistanceMeasurement","12346082",1464359005.396,"c8y_DistanceMeasurement","distance",344.0,"mm",{})

To create a new measurement for a Cumulocity device you should either send a single fragment to MeasurementFragment.SEND_CHANNEL, or combine several into a measurement and send that to Measurement.SEND_CHANNEL. For example:

 send MeasurementFragment("","c8y_DistanceMeasurement","123",1464359005.396,"distance","distance",3.44,"mm",new dictionary<string, any>) to MeasurementFragment.SEND_CHANNEL;

You cannot update a Measurement or MeasurementFragment once it has been created.

Since:: 10.5.2.0

See Also:: com.apama.cumulocity.Measurement

Constant summary
`string`	`SEND_CHANNEL := "CumulocityIoTGenericChain"` The channel to send a measurement fragment event to create a new measurement fragment object in Cumulocity.
`string`	`SUBSCRIBE_CHANNEL := "cumulocity.measurement.fragments"` The channel to which `MeasurementFragment` events are sent from the transport.

Field summary
`string`	`id` Unique identifier for the measurement.
`string`	`type` The type of the measurement.
`string`	`source` The unique identifier of the source of the measurement. This should correspond to a managed object.
`float`	`time` The time the measurement was taken, represented as the number of seconds since the epoch (1st January 1970).
`string`	`valueFragment` Name of the fragment of the measurement fragment.
`string`	`valueSeries` Name of the series of the measurement fragment.
`float`	`value` Value from the sensor.
`string`	`unit` Units the reading is in, for example mm, lux.
`dictionary<string, any>`	`params` Any per-value extra fields.

Action summary
`com.apama.cumulocity.ResponseWrapper`	`withChannelResponse(integer reqId, dictionary<string, string> headers)` Create a MeasurementFragment in Cumulocity and receive a response event confirming the change on MeasurementFragment.SUBSCRIBE_CHANNEL channel.
`com.apama.cumulocity.ResponseWrapper`	`withResponse(integer reqId, dictionary<string, string> headers)` Create a MeasurementFragment 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 MeasurementFragment.SUBSCRIBE_CHANNEL channel.]

Constant detail

SEND_CHANNEL

string SEND_CHANNEL := "CumulocityIoTGenericChain"

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

Since:: 10.5.2.0

SUBSCRIBE_CHANNEL

string SUBSCRIBE_CHANNEL := "cumulocity.measurement.fragments"

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

Since:: 10.5.2.0

Field detail

id

string id

Unique identifier for the measurement.

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

params

dictionary<string, any> params

Any per-value extra fields.

source

string source

The unique identifier of the source of the measurement. This should correspond to a managed object.

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.

unit

string unit

Units the reading is in, for example mm, lux.

value

float value

Value from the sensor.

valueFragment

string valueFragment

Name of the fragment of the measurement fragment.

valueSeries

string valueSeries

Name of the series of the measurement fragment.

Action detail

withChannelResponse

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

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

Just sending a MeasurementFragment is fire and forget. If your application requires an acknowledgement or the ID of the MeasurementFragment created on MeasurementFragment.SUBSCRIBE_CHANNEL channel, then use the withChannelResponse API. You will need to subscribe to MeasurementFragment.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 MeasurementFragment. 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(MeasurementFragment.SUBSCRIBE_CHANNEL);
MeasurementFragment m := new MeasurementFragment;
// 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 MeasurementFragment.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 MeasurementFragment.; com.apama.cumulocity.ObjectCommitFailed - Failed to create a MeasurementFragment

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

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

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

MeasurementFragment m := new MeasurementFragment;
// 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 MeasurementFragment.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 MeasurementFragment.; com.apama.cumulocity.ObjectCommitFailed - Failed to create a MeasurementFragment.; com.apama.cumulocity.MeasurementFragment.withChannelResponse() - to receive confirmation on MeasurementFragment.SUBSCRIBE_CHANNEL channel.

com.apama.cumulocityEvent MeasurementFragment