--- name: cumulocity-apply-device-profile description: "Check that a device supports device profiles, read the profile, create a c8y_DeviceProfile operation, follow it, and check that the device reports the profile as executed. Use when the user wants to apply a device profile to a device and check that the device reports it as executed." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Apply a device profile to a device Source: https://cumulocity.com/docs/skills/device-management/apply-device-profile/ Sector: Skills, Device management & connectivity Release: Latest Description: Check that a device supports device profiles, read the profile, create a c8y_DeviceProfile operation, follow it, and check that the device reports the profile as executed. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) A device profile combines a firmware version, software packages, and configuration files that a device installs together. To apply a profile to a device, you create a `c8y_DeviceProfile` operation with the content of the profile. The device installs the firmware first, the software second, and the configuration third, exactly like the individual `c8y_Firmware`, `c8y_SoftwareUpdate`, and typed `c8y_DownloadConfigFile` operations. To create a profile, see [Manage device profiles](https://cumulocity.com/docs/skills/device-management/manage-device-profiles/). The profile operation follows the same lifecycle as every other operation, see [Send an operation to a device](https://cumulocity.com/docs/skills/device-management/send-operation/). > **Requirements:** > ROLES & PERMISSIONS: > > * To read the device and the profile: ROLE_INVENTORY_READ > * To create operations: ROLE_DEVICE_CONTROL_ADMIN > * To read operations: ROLE_DEVICE_CONTROL_READ The examples use `` for the ID of the device, `` for the ID of the device profile, and `` for the ID of the operation. Both IDs are the `id` that the platform assigned to the managed object, not its name. A request with the name instead of the ID returns HTTP 404. ### To check that the device supports device profiles {#to-check-that-the-device-supports-device-profiles} 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 `"c8y_DeviceProfile"`. If `c8y_DeviceProfile` is missing in `c8y_SupportedOperations`, do not create the operation. The device does not support device profiles. ### To read the device profile {#to-read-the-device-profile} Send a [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request for the profile: ```http GET /inventory/managedObjects/ ``` Check the following properties in the response: * The `type` is `c8y_Profile`. * The `name` is the name of the profile. Note it as ``. * The fragment `c8y_DeviceProfile` contains the firmware, software, and configuration of the profile. If the `type` is not `c8y_Profile` or the fragment `c8y_DeviceProfile` is missing, the object is not a device profile. If the platform returns HTTP 404, the profile does not exist. ### To create the operation {#to-create-the-operation} Send a [Create an operation](https://cumulocity.com/api/core/#operation/postOperationCollectionResource) request. Copy the `c8y_DeviceProfile` fragment from the profile unchanged: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "profileId": "", "profileName": "", "description": "Assign device profile to device ", "c8y_DeviceProfile": { "firmware": { "name": "device_fw", "version": "1.0.1", "url": "https://example.com/fw" }, "software": [ { "name": "curl", "action": "install", "version": "2.3.4", "url": "https://example.com/curl" } ], "configuration": [ { "name": "agent_conf", "type": "agent_conf", "url": "https://example.com/agent.conf" } ] } } ``` The properties `profileId`, `profileName`, and `c8y_DeviceProfile` are mandatory. Send the ID of the profile as `profileId`, never its name. The device copies `profileId` into its own managed object, so a wrong value ends up there. The platform returns HTTP 201 and the operation with its `id` and `"status": "PENDING"`. Note the `id` as ``. If the platform returns HTTP 422, the device is not an agent, and none of its parent devices is an agent. ### To follow the operation {#to-follow-the-operation} Send a [Retrieve a specific operation](https://cumulocity.com/api/core/#operation/getOperationResource) request every 5 seconds until the `status` is SUCCESSFUL or FAILED: ```http GET /devicecontrol/operations/ ``` The device installs all parts of the profile before it reports the result, so choose a timeout that fits the profile. If the operation is FAILED, the `failureReason` property describes why. For the meaning of each status and 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). ### To check that the device executed the profile {#to-check-that-the-device-executed-the-profile} While the device applies the profile, it sets the `c8y_Profile` fragment in its own managed object with `"profileExecuted": false`. After it has installed all parts, it sets `profileExecuted` to `true`. Send a [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request: ```http GET /inventory/managedObjects/ ``` After a SUCCESSFUL operation, the response contains the following fragment: ```json { "c8y_Profile": { "profileName": "", "profileId": "", "profileExecuted": true } } ``` * **`profileExecuted` is `false`**: The device still applies the profile, or it stopped in the middle. Check again after 30 seconds. * **`profileId` differs from ``**: The device reports another profile. * **`c8y_Profile` is missing**: The device agent does not report the profile. The result of the operation still applies. To apply a profile to many devices at once, schedule the operation for a group of devices, see [Run a bulk operation on a device group](https://cumulocity.com/docs/skills/device-management/run-bulk-operation/). ## 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 ## Linked from the documentation - [Managing device data > Managing device profiles](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-device-profiles)