Apama Connectivity For Cumulocity IoT  10.1 | Apama Connectivity For Cumulocity IoT Documentation 10.1 | Installing Apama Connectivity with Cumulocity IoT | Migration from earlier versions to 10.1
 
Migration from earlier versions to 10.1
If you are migrating from a previous version of Apama Connectivity with Cumulocity IoT (previously, Apama Connectivity with Device Integration Platform), you must update the filenames and configurations to work with the existing applications. Follow these steps to migrate from previous versions:
1. Backup the properties DIP_TENANT, DIP_USERNAME, DIP_PASSWORD, DIP_APPKEY in the the file DeviceIntegrationPlatform-credentials.properties.
2. Remove any dependency on the Apama Connectivity With Device Integration Platform bundle along with any bundle instance files. This is no longer available and must be removed completely from the project.
3. Add the new Connectivity adapter bundle Apama Connectivity with Cumulocity IoT to your project.
4. Copy the values of the properties DIP_TENANT, DIP_USERNAME, DIP_PASSWORD, DIP_APPKEY to C8Y_TENANT, C8Y_USERNAME, C8Y_PASSWORD, C8Y_APPKEY respectively in the Cumulocity-credentials.properties file.
5. Rename instances of the com.apama.dip package to com.apama.cumulocity package. This would impact the following events:
Old name
New name
com.apama.dip.Error
com.apama.cumulocity.Error
com.apama.dip.DeviceOperation
com.apama.cumulocity.DeviceOperation
com.apama.dip.
DeviceOperationStringArray
com.apama.cumulocity.DeviceOperation
com.apama.dip.DeviceOperationJson
com.apama.cumulocity.DeviceOperation
com.apama.dip.RequestAllDevices
com.apama.cumulocity.RequestAllDevices
com.apama.dip.
RequestAllDevicesComplete
com.apama.cumulocity.
RequestAllDevicesComplete
com.apama.dip.
SubscribeMeasurements
com.apama.cumulocity.
SubscribeMeasurements
com.apama.dip.
UnsubscribeMeasurements
com.apama.cumulocity.
UnsubscribeMeasurements
com.apama.dip.MeasurementValue
com.apama.cumulocity.MeasurementValue
com.apama.dip.Measurement
com.apama.cumulocity.Measurement
com.apama.dip.Event
com.apama.cumulocity.Event
com.apama.dip.Device
com.apama.cumulocity.Device
com.apama.dip.FindAlarm
com.apama.cumulocity.FindAlarm
com.apama.dip.FindAlarmResponse
com.apama.cumulocity.FindAlarmResponse
com.apama.dip.
FindAlarmResponseAck
com.apama.cumulocity.
FindAlarmResponseAck
com.apama.dip.FindManagedObject
com.apama.cumulocity.FindManagedObject
com.apama.dip.
FindManagedObjectResponse
com.apama.cumulocity.
FindManagedObjectResponse
com.apama.dip.SendEmail
com.apama.cumulocity.SendEmail
com.apama.dip.SendSMS
com.apama.cumulocity.SendSMS
com.apama.dip.
SMSResourceReference
com.apama.cumulocity.
SMSResourceReference
com.apama.dip.SMSResponse
com.apama.cumulocity.SMSResponse
com.apama.dip.SendSpeech
com.apama.cumulocity.SendSpeech
6. Rename the channel name DeviceIntegrationPlatform to CumulocityIoT.
With the adoption of correlator any type support to Apama Connectivity with Cumulocity IoT, the following event definitions have been updated:
Event
The application code must be updated accordingly for extracting values from params dictionary. For more information on any type, see Apama documentation. In the following event definition, the code phrase dictionary <string, string> params has been updated to dictionary <string, any> params.
@ExtraFieldsDict("params")

event Event {

/** Only used for internal purposes. Should not be used
by application developer. */

constant string CHANNEL :="CumulocityIoT";

/** Type of the Event or Alarm. */

string eventType;

/** assetId of the source of the event. */

string assetId;

/** Timestamp of the event. */

float timestamp;

/** Text or message of the Event or Alarm */

string text;

/** Any extra parameters available on the Event or Alarm. */

dictionary<string, any> params;

}
Device
The application code must be updated accordingly for extracting values from params dictionary. For more information on any type, see Apama documentation. In the following event definition, the code phrase dictionary <string, string> params has been updated to dictionary <string, any> params.
@ExtraFieldsDict("params")

event Device {

/** The channel to which measurements are sent from the transport.*/

constant string CHANNEL:= "cumulocity.devices";

/** The unique identifier for this specific Device. */

string assetId;

/** The name of this Device. <b>Note:</b> This does not
have to be a unique value. */

string name;

/** The device integration platform type of the device */

string type;

/** The description for this Asset. */

string description;

/** List of supported operations for this device. */

sequence<string> supportedOperations;

/** List of supported measurements for this device */

sequence<string> supportedMeasurements;

/** Child assetIds of child devices */

sequence<string> childAssetIds;

/** If knonwn, contains lat, lng, altitude and accuracy */

dictionary<string, decimal> position;

/** A set of stringified extra configuration information
for this Device. */

dictionary<string, any> params;

}
Measurement or MeasurementValue
The application code must be updated accordingly for extracting values from extraParams/params dictionary. For more information on any type, see Apama documentation. In the following event definition, the code phrase dictionary <string, string> extraParams has been updated to dictionary <string, any> extraParams.
@ExtraFieldsDict("extraParams")

event MeasurementValue {

/** Value from the sensor */

decimal value;

/** Units the reading is in, e.g. mm, lux */

string unit;

/** Type of the measurement - COUNTER, BOOLEAN, GUAGE or RATE */

string type;

/** Quantity */

string quantity;

/** State of the measurement - ORIGINAL, INTERPOLATED, VALIDATED */

string state;

/** Any per-value extra parameters */

dictionary<string, any> extraParams;

}
In the following event definition, the code phrase dictionary <string, string> params has been updated to dictionary <string, any> params.
@ExtraFieldsDict("params")

event Measurement {

/** The channel to which measurements are sent from the transport.

*/

constant string CHANNEL:= "cumulocity.measurements";

/** The channel to send a measurements to create a new measurement

*/

constant string CREATE_CHANNEL:= "CumulocityIoT";

/** The type of the measurement. */

string measurementType;

/** The unique identifier of the source of the measurement.

* This should correspond to an Device sent in previously. */

string assetId;

/** The timestamp the measurement was taken, represented as the number of

* seconds since the epoch (1st January 1970). */

float timestamp;

/** Value name to MeasurementValue map of measurements. */

dictionary<string, MeasurementValue> measurements;

/** This stringified dictionary is available to hold any other data

* associated with the measurement. */

dictionary<string, any> params;

}
Device operation
The previous versions of DeviceOperationStringArray and DeviceOperationJson are now supported using the base DeviceOperation event object. See Sending device operations section.
@ExtraFieldsDict("params")

event DeviceOperation {

/** Channel to send the events to. */

constant string CHANNEL := "CumulocityIoT";

/** assetId of the Device to send the operation to. */

string assetId;

/** Operation-specific data. */

dictionary<string, any> operations;

/** Any extra parameters available on the Device Operation. */

dictionary<string, any> params;

}
Sending device operations
You can send device operations using the DeviceOperation event.

DeviceOperation do := new DeviceOperation;
do.assetId := "<DEVICE_ID>"; // This needs to be populated with
the appropriate device/asset Id
//Display a sample message if the device supports a display
//This makes supporting the usecases similar to the earlier versions
of both DeviceOperation and DeviceOperationJson far more simpler
do.operations.add("c8y_Meassage", {"text":"Hello Cumulocity device"});
//Set the states of multiple Relay Devices attached to a device
//This makes supporting the usecases similar to the earlier versions of
both DeviceOperationStringArray far more simpler
do.operations.add("c8y_RelayArray", ["CLOSED", "OPEN", "OPEN", "CLOSED"]);
send do to DeviceOperation.CHANNEL;
Examples
*DeviceOperation
Previous: DeviceOperation("12345","c8y_Meassage",{"text":"Hello Cumulocity device"})
New: DeviceOperation("12345",{"c8y_Meassage":<any>{<any>"text":<any>"Hello Cumulocity device"}},new dictionary<string, any>)
*DeviceOperationStringArray
Previous: DeviceOperationStringArray("12345","c8y_RelayArray",["CLOSED","OPEN","CLOSED","OPEN"])
New: DeviceOperation("12345",{"c8y_RelayArray":<any>["CLOSED","OPEN","CLOSED","OPEN"]},new dictionary<string, any>)
*DeviceOperationJson
Previous: DeviceOperationJson("12345",{"c8y_Meassage":"{\"text\":\"Hello cumulocity\"}","c8y_Relay":"{\"relayState\":\"CLOSED\"}"})
New: DeviceOperation("12345",{"c8y_Meassage":<any>{<any>"text":<any>"Hello cumulocity"},"c8y_Relay":<any>{<any>"relayState":<any>"CLOSED"}},new dictionary<string, any>)

Copyright © 2013-2017 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.
Innovation Release