Cumulocity environment
Forward your IoT data to a Cumulocity environment.
The following parameters are available to configure the Destination to your Cumulocity environment
- Name (required) - the administrative name of your Destination.
- Technical name:
name
- Example value: Tenant X
- Description - an administrative description of your Destination.
- Technical name:
description
- Example value: Tenant with Materieelbeheer application
- Tenant (required) - base URL of your Cumulocity environment.
- Technical name:
tenant
- Example value: https://x.kpnthings.com
- Username (required, secret) - Username of the functional user that KPN Things should use to access your tenant.
- Technical name:
username
- Example value: kpnthings
- Password (required, secret) - Password of the functional user that KPN Things should use to acces your tenant.
- Technical name:
password
- KPN Applications in tenant - List of applications the device should be associated with in the Cumulocity tenant.
- Technical name:
applications
- Example value: ["ASSET_TRACKING"]
- Custom fragments - List of additional custom fragments to add to the device object when it is created in Cumulocity.
- Technical name:
customFragments
- Example value: c8y_CustomApplication
- Technical name:
sendMeasurements
- Boolean value
- Send location update events? - Whether the location should be updated and location update event should be sent.
- Technical name:
sendLocationUpdateEvents
- Boolean value
- Bidirectional behavior - Choose whether the destination should process uplink data (data from Device to Application), downlink data (data from Application to Device) or both.
- Technical name:
bidirectionalBehaviour
- Default value:
ONLY_UPLINK
- Available values:
ONLY_UPLINK
- Only forward uplink data to Cumulocity.ONLY_DOWNLINK
- Only synchronize Cumulocity operations with Things downlinks.BIDIRECTIONAL
- Process both uplink and downlink data.BIDIRECTIONAL_WITH_RETRY
- Process both uplink and downlink data, and make sure downlinks are retried by KPN Things.
- Managed Cumulocity credentials - Credentials of Cumulocity accounts expire after some time. Enabling this option will renew the password in time to prevent expiry.
- Technical name:
credentialManagementEnabled
- Boolean value
A secret value is treated as a secret in our database and is therefor not returned in the API object response.
You can configure the Cumulocity Destination with one or more KPN Things Applications that can be installed in the Cumulocity tenant. The options are listed in the table below.
Name | Fragment | sendLocationUpdateEvents | sendMeasurements | Operations handling |
ASSET_TRACKING | c8y_IsForAssetTracking | false | true | true |
WASTE_CONTROL | kpn_IsWasteObject | false | true | false |
ASSET_INSURANCE | c8y_IsForInsurance | true | false | true |
If at least one configured application or the Destination configuration itself enables
sendMeasurements
or sendLocationUpdateEvents
, the measurement or location update is send respectively.When you connect a Cumulocity Tenant to Data Management, you should enter a username and password for authentication to your Cumulocity Tenant. It is best practice to create a separate user account for this connection. This user should have the role business.

Screenshot of the most important settings when creating the user in Cumulocity
This section describes the functionality of the connection to Cumulocity.
When IoT dat is about to be forwarded to Cumulocity, it will first try to find the device Managed Object using the base name from the SenML message. For this it looks for an external identifier of type
DEVEUI
and the base name as value. For instance:GET /identity/externalIds/DEVEUI/urn:dev:DEVEUI:0123456789012345:
If such an external identifier does not exist, a new device Managed Object and the required external identifiers is created. This is called provisioning in runtime.
KPN Things will create a device Managed Object if it did not exist. The device Managed Object will be created with the following information, using the device record that is known in the Data Management platform.
Additionally, the configured custom fragments (and fragments used for application association) are added to the object. In the example below, a device is created that had customFragment exampleFragment configured and application ASSET_TRACKING was configured as well.
createdDeviceRecord
{
"name": "<device.name>",
"c8y_IsDevice": {},
"c8y_Metadata": {
"barcode": "<device.barcode>" /* If barcode is known */
"activatedNetworks": [ /* For each network the device is registered */
{
"networkStatus": "ACTIVE",
"networkType": "<device.network.networkType>",
"uuid": "<device.network.uuid>",
"devEUI": "<device.network.networkId>"
}
]
},
"c8y_Hardware": {
"serialNumber": "<device.networkId>", /* SenML base name of primary network */
"model": "<device.deviceSpecification.model>"
},
"exampleFragment": {}, /* Configured custom fragment */
"c8y_IsForAssetTracking": {} /* Asset Tracking fragment */
}
Using the main network id an external identifier is created for the newly created device Managed Object.
Additionally, if a barcode is known present in the device object, another external identifier of type
BARCODE
is created as well.The following configurations are required to enable sending measurements:
- 1.Bidirectional behavior set to Only uplink or Bidirectional.
- 2.One of the following:
- 1.
sendMeasurements
should be enabled to enable this feature, or - 2.
After the device Managed Object is found or created, a measurement is added to this device of the type
kpn_SenMLMeasurement
. A full example can be found below.{
"time": "<from SenML bt>",
"type": "kpn_SenMLMeasurement",
"kpn_SenMLMeasurement": {
"<senml[0].n>": { (For all number and boolean measurements)
"unit": "<senml[0].u>",
"value": <senml[0].v>
},
"<senml[1].n>": {
"unit": "<senml[1].u>",
"value": <senml[1].v>
},
...
},
"kpn_SenMLMeasurement_data": { (for all string measurements)
"<senml[2].n>": "<senml[2].v>"
}
}
The following configurations are required to send location update events:
- 1.Bidirectional behavior set to Only uplink or Bidirectional.
- 2.One of the following:
- 1.
sendLocationUpdateEvents
should be enabled to enable this feature, or - 2.
If the measurement contains both latitude and longitude, the device Managed Object's
c8y_Position
value is updated with the newly calculated location. Also, it will create a
c8y_LocationUpdate
event on the device, according to the Cumulocity sensor library.{
"time": "2019-07-02T11:20:34.000Z",
"source": {
"id": "<device id>"
},
"text": "LocUpdate",
"type": "c8y_LocationUpdate",
"c8y_Position": {
"lat": 51.9072126,
"lng": 4.4893038,
"alt": 0.0,
"radius": 140.2
}
}
The following configurations are required to send location update events:
- 1.Bidirectional behavior set to Only downlink or Bidirectional.
- 2.
The Cumulocity destination will poll your Cumulocity environment for operations. When the destination finds a new operation, recognizable because its status is PENDING, a Downlink is created for the corresponding Device.
To create the Downlink, the Cumulocity external ID is used to map to the correct Device in KPN Things. Additionally, the Cumulocity operation value deviceStatus is fetched, and put in a string value for the SenML downlink command mode.
When the operation has been picked up by KPN Things, we change the status to EXECUTING. When the downlink has finished, we will update the Cumulocity operation status to SUCCESSFUL or FAILED depending on whether the downlink was successful or not.
Last modified 1yr ago