# Cumulocity IoT Platform ## Configure a Cumulocity destination ### Name Give your Cumulocity destination name and optionally a description. * **Destination 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* ### Connection details Create a Cumulocity environment at [https://signup.softwareag.cloud](https://signup.softwareag.cloud/#/?product=cumulocity). * **URL** (required) - base URL of your Cumulocity environment. * Technical name: `tenant` * Example value: ** ### Create KPN Things user in Cumulocity Create an additional user in de Administration of your Cumulocity environment. To do so use the Application Switcher to switch to the Administration application and click on Users. Create a new user with the role *admin*.
* **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` * **Generate a dedicated Things user & renew password automatically** - 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 ### Advanced configuration * **Bidirectional behavior** - Choose whether the destination should process [uplink](#uplink-send-measurement) [data](#uplink-update-location-and-send-location-update-event) (data from Device to Application), [downlink data](#downlink-synchronize-cumulocity-operations-with-things-downlinks) (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. * **Which messages should be sent to this Destination?** * Technical name: `sendMeasurements`(Boolean value) * Technical name: `sendLocationUpdateEvents`(Boolean value) * **Extra label for new devices** - List of additional custom fragments to add to the device object when it is [created in Cumulocity](#find-or-create-device-record). * Technical name: `customFragments` * Example value: *c8y\_CustomApplication* {% hint style="info" %} A **secret** value is treated as a secret in our database and is therefor not returned in the API object response. {% endhint %} ## What does the connection do? This section describes the functionality of the connection to Cumulocity. ### Find or create device record 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**. #### Create device record 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. {% code title="createdDeviceRecord" %} ```javascript { "name": "", "c8y_IsDevice": {}, "c8y_Metadata": { "barcode": "" /* If barcode is known */ "activatedNetworks": [ /* For each network the device is registered */ { "networkStatus": "ACTIVE", "networkType": "", "uuid": "", "devEUI": "" } ] }, "c8y_Hardware": { "serialNumber": "", /* SenML base name of primary network */ "model": "" }, "exampleFragment": {}, /* Configured custom fragment */ "c8y_IsForAssetTracking": {} /* Asset Tracking fragment */ } ``` {% endcode %} #### Create external identifiers 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. ### Uplink: Send measurement {% hint style="warning" %} 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. An [application ](https://docs.kpnthings.com/kpn-things/building-blocks/applications)should be selected that enables sending measurements. {% endhint %} 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. ```javascript { "time": "", "type": "kpn_SenMLMeasurement", "kpn_SenMLMeasurement": { "": { (For all number and boolean measurements) "unit": "", "value": }, "": { "unit": "", "value": }, ... }, "kpn_SenMLMeasurement_data": { (for all string measurements) "": "" } } ``` More information on SenML can be found on [this page](https://docs.kpnthings.com/kpn-things/building-blocks/data-processing/thingsml-and-senml/senml). ### Uplink: Update location and send location update event {% hint style="warning" %} 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. An [application ](https://docs.kpnthings.com/kpn-things/building-blocks/applications)should be selected that enables sending measurements. {% endhint %} 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. #### Example location update event ```javascript { "time": "2019-07-02T11:20:34.000Z", "source": { "id": "" }, "text": "LocUpdate", "type": "c8y_LocationUpdate", "c8y_Position": { "lat": 51.9072126, "lng": 4.4893038, "alt": 0.0, "radius": 140.2 } } ``` ### Downlink: Synchronize Cumulocity operations with Things downlinks {% hint style="warning" %} The following configurations are required to send location update events: 1. Bidirectional behavior set to *Only downlink* or *Bidirectional.* 2. An [application ](https://docs.kpnthings.com/kpn-things/building-blocks/applications)should be selected that enables operations handling. {% endhint %} 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.kpnthings.com/kpn-things/building-blocks/destinations/cumulocity-iot-platform.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.