--- name: cumulocity-apply-device-configuration description: "Install configuration text or a configuration file on a device, make the device report its current configuration, and read the configuration file that the device uploads. Use when the user wants to send a configuration to a device, make a device report its current configuration, or download the configuration file that a device uploaded." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Apply and retrieve device configuration Source: https://cumulocity.com/docs/skills/device-management/apply-device-configuration/ Sector: Skills, Device management & connectivity Release: Latest Description: Install configuration text or a configuration file on a device, make the device report its current configuration, and read the configuration file that the device uploads. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) Devices manage their configuration in one of the following formats: * **Text-based configuration**: The configuration is a text in the `c8y_Configuration` fragment of the device. Use it only for short configurations that people can read. * **Typed file-based configuration**: The device manages several configuration files, each with a configuration type such as `agent_conf`. The device lists its configuration types in the `c8y_SupportedConfigurations` fragment. * **Legacy file-based configuration**: The device manages a single configuration file. For each task, you create an operation. The device lists the operations that it supports in its `c8y_SupportedOperations` fragment: * `c8y_Configuration`: Install configuration text. * `c8y_SendConfiguration`: Report the current configuration text. * `c8y_DownloadConfigFile`: Install a configuration file. * `c8y_UploadConfigFile`: Upload the current configuration file. The fragment names describe the view of the device. With `c8y_DownloadConfigFile`, the device downloads a file that you send. With `c8y_UploadConfigFile`, the device uploads its file, and you receive it. For details on the formats, see [Configuration](https://cumulocity.com/docs/device-integration/fragment-library/#configuration). > **Requirements:** > ROLES & PERMISSIONS: > > * To read the device: ROLE_INVENTORY_READ > * To create operations: ROLE_DEVICE_CONTROL_ADMIN > * To read operations: ROLE_DEVICE_CONTROL_READ > * To read an uploaded configuration file: ROLE_EVENT_READ The examples use `` for the ID of the device, `` for the ID of the operation, and `` for a configuration type. The device ID is the `id` that the platform assigned to the device, not its name. Each procedure creates an operation, which follows the same lifecycle as every other operation. To follow it, send a [Retrieve a specific operation](https://cumulocity.com/api/core/#operation/getOperationResource) request to `GET /devicecontrol/operations/` every 5 seconds until the `status` is SUCCESSFUL or FAILED. For details and for how to cancel an operation that stays PENDING, see [Send an operation to a device](https://cumulocity.com/docs/skills/device-management/send-operation/#to-follow-the-status-of-the-operation). If the platform returns HTTP 422 when you create an operation, the device is not an agent, and none of its parent devices is an agent. ### To check which configuration operations the device supports {#to-check-which-configuration-operations-the-device-supports} Send a [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request: ```http GET /inventory/managedObjects/ ``` Check the following properties in the response: * The fragment `c8y_IsDevice` is present. * The array `c8y_SupportedOperations` contains the operation of your task, for example `"c8y_DownloadConfigFile"`. * The array `c8y_SupportedConfigurations`, if present, lists the configuration types of the device. A device with this fragment supports typed file-based configuration. A device without it that supports `c8y_UploadConfigFile` or `c8y_DownloadConfigFile` uses legacy file-based configuration. If the operation is missing in `c8y_SupportedOperations`, do not create it. No agent picks it up. ### To install configuration text {#to-install-configuration-text} Send a [Create an operation](https://cumulocity.com/api/core/#operation/postOperationCollectionResource) request with the complete configuration text in `config`: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "description": "Install configuration text", "c8y_Configuration": { "config": "c8y.url.http=https://management.cumulocity.com\nc8y.url.mqtt=mqtt.cumulocity.com\n" } } ``` Escape the line breaks and other control characters of the text according to the JSON specification. The platform returns HTTP 201 and the operation with its `id` and `"status": "PENDING"`. After the operation is SUCCESSFUL, the device shows the new text in the `c8y_Configuration` fragment of its managed object. ### To install a configuration file {#to-install-a-configuration-file} Take the configuration file from the configuration repository: the `url` of a configuration snapshot as `` and, for legacy file-based configuration, its `id` as ``. See [Manage the configuration repository](https://cumulocity.com/docs/skills/device-management/manage-configuration-repository/). Send a [Create an operation](https://cumulocity.com/api/core/#operation/postOperationCollectionResource) request. For a device with typed file-based configuration, send the URL and the configuration type: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "description": "Install configuration file", "c8y_DownloadConfigFile": { "url": "", "type": "" } } ``` For a device with legacy file-based configuration, send the URL and the ID of the configuration snapshot: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "description": "Install configuration file", "c8y_DownloadConfigFile": { "url": "", "c8y_ConfigurationDump": { "id": "" } } } ``` Send the ID of the snapshot in `c8y_ConfigurationDump`, never its name. The device copies the `c8y_ConfigurationDump` fragment unchanged into its own managed object. Legacy file-based configuration only works with files that are stored in Cumulocity, not with external URLs. The platform returns HTTP 201 and the operation with its `id` and `"status": "PENDING"`. After the operation is SUCCESSFUL, the device shows the installed file in its managed object: * **Typed file-based configuration**: In the fragment `c8y_Configuration_`, with the properties `name`, `time`, `type`, and `url`. * **Legacy file-based configuration**: In the fragment `c8y_ConfigurationDump`, with the ID of the snapshot. ### To request the current configuration text {#to-request-the-current-configuration-text} 1. Send a [Create an operation](https://cumulocity.com/api/core/#operation/postOperationCollectionResource) request: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "description": "Request configuration text", "c8y_SendConfiguration": {} } ``` The platform returns HTTP 201 and the operation with its `id` and `"status": "PENDING"`. 2. Wait until the operation is SUCCESSFUL. The device then writes its current configuration into the `c8y_Configuration` fragment of its managed object. 3. Send a [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request to `GET /inventory/managedObjects/` and read `c8y_Configuration.config`. ### To request the current configuration file {#to-request-the-current-configuration-file} Send a [Create an operation](https://cumulocity.com/api/core/#operation/postOperationCollectionResource) request. For a device with typed file-based configuration, send the configuration type of the file: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "description": "Request configuration file", "c8y_UploadConfigFile": { "type": "" } } ``` For a device with legacy file-based configuration, send an empty fragment: `"c8y_UploadConfigFile": {}`. The platform returns HTTP 201 and the operation with its `id`, `creationTime`, and `"status": "PENDING"`. Note the `creationTime` as ``. After the operation is SUCCESSFUL, the uploaded file is available: * **Typed file-based configuration**: The device creates an event of the type `` and attaches the file to it. Read the file as described in [To read the uploaded configuration file](https://cumulocity.com/docs/skills/device-management/apply-device-configuration/#to-read-the-uploaded-configuration-file). * **Legacy file-based configuration**: The device uploads the file and creates a new configuration snapshot in the configuration repository. See [Manage the configuration repository](https://cumulocity.com/docs/skills/device-management/manage-configuration-repository/#to-list-the-configuration-snapshots). Only a file that the device uploaded after your operation shows the current configuration. Earlier uploads and snapshots in the repository can be outdated. ### To read the uploaded configuration file {#to-read-the-uploaded-configuration-file} 1. Send a [Retrieve all events](https://cumulocity.com/api/core/#operation/getEventCollectionResource) request for the events of the device that the platform created after your operation: ```http GET /event/events?source=&type=&createdFrom=&pageSize=5 ``` If `` contains a `+`, encode it as `%2B`. The `events` array of the response contains the upload event. Note the `id` of the event with the newest `creationTime` as ``. If the `events` array is empty, the device reported SUCCESSFUL without uploading a file. 2. Send a [Retrieve the attached file of a specific event](https://cumulocity.com/api/core/#operation/getEventBinaryResource) request: ```http GET /event/events//binaries ``` The platform returns HTTP 200 and the content of the configuration file. If the platform returns HTTP 404, no file is attached to the event. ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [GET /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/getManagedObjectResource): Retrieve a specific managed object - [POST /devicecontrol/operations](https://cumulocity.com/api/core/#operation/postOperationCollectionResource): Create an operation - [GET /devicecontrol/operations/{id}](https://cumulocity.com/api/core/#operation/getOperationResource): Retrieve a specific operation - [GET /event/events](https://cumulocity.com/api/core/#operation/getEventCollectionResource): Retrieve all events - [GET /event/events/{id}/binaries](https://cumulocity.com/api/core/#operation/getEventBinaryResource): Retrieve the attached file of a specific event ## Linked from the documentation - [Fragment library > Configuration](https://cumulocity.com/docs/device-integration/fragment-library/#configuration) - [Managing device data > Managing configurations](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-configurations)