--- name: cumulocity-send-operation description: "Check that a device supports an operation, create the operation, follow it until the device reports SUCCESSFUL or FAILED, and cancel an operation that stays PENDING. Use when the user wants to send an operation to a device, follow its status, or cancel a pending operation." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Send an operation to a device Source: https://cumulocity.com/docs/skills/device-management/send-operation/ Sector: Skills, Device management & connectivity Release: Latest Description: Check that a device supports an operation, create the operation, follow it until the device reports SUCCESSFUL or FAILED, and cancel an operation that stays PENDING. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) Operations control devices remotely, for example to restart a device, to install software, or to run a shell command. You create an operation in the platform, and the device picks it up, executes it, and reports the result. ### How an operation moves through its statuses {#how-an-operation-moves-through-its-statuses} Every operation has one of the following statuses: * **PENDING**: The platform created the operation. No device has picked it up yet. * **EXECUTING**: The device picked up the operation and runs it. * **SUCCESSFUL**: The device completed the operation. * **FAILED**: The operation did not complete. The `failureReason` property describes why. The platform sets PENDING when you create the operation. The device sets all other statuses. SUCCESSFUL and FAILED are final. A device only executes an operation if both of the following conditions apply: * The device, or one of its parent devices, is an agent. That means its managed object has the fragment `com_cumulocity_model_Agent`. Otherwise, the platform rejects the operation with HTTP 422. * The device lists the operation in its `c8y_SupportedOperations` fragment. Otherwise, no agent picks up the operation, and it stays PENDING. > **Requirements:** > ROLES & PERMISSIONS: > > * To create and cancel operations: ROLE_DEVICE_CONTROL_ADMIN > * To read operations: ROLE_DEVICE_CONTROL_READ The examples use `` for the ID of the device and `` for the ID of the operation. They restart the device with the `c8y_Restart` operation. ### To check that the device supports the operation {#to-check-that-the-device-supports-the-operation} 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, for example `"c8y_Restart"`. If the operation is missing in `c8y_SupportedOperations`, do not create it. The device does not execute it. ### To create the operation {#to-create-the-operation} 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": "Restart device", "c8y_Restart": {} } ``` The operation fragment, here `c8y_Restart`, contains the parameters of the operation. A restart has no parameters, so the fragment is empty. Do not send a `status`. The platform sets it. 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 status of the operation {#to-follow-the-status-of-the-operation} Send a [Retrieve a specific operation](https://cumulocity.com/api/core/#operation/getOperationResource) request: ```http GET /devicecontrol/operations/ ``` Repeat the request every 5 seconds until the `status` is SUCCESSFUL or FAILED. Stop after a timeout that fits the operation, for example 2 minutes for a restart: * **SUCCESSFUL**: The device completed the operation. * **FAILED**: The response contains a `failureReason`. * **Still PENDING after the timeout**: No agent picked up the operation. The device is offline, or it does not listen for this operation. Cancel the operation, see [To cancel a pending operation](https://cumulocity.com/docs/skills/device-management/send-operation/#to-cancel-a-pending-operation). * **Still EXECUTING after the timeout**: The device started the operation but did not report a result. Do not cancel the operation, because the device can still complete it. ### To list the operations of a device {#to-list-the-operations-of-a-device} Send a [Retrieve a list of operations](https://cumulocity.com/api/core/#operation/getOperationCollectionResource) request: ```http GET /devicecontrol/operations?deviceId=&status=PENDING ``` You can filter by `deviceId`, `status`, `fragmentType`, `agentId`, `bulkOperationId`, `dateFrom`, and `dateTo`. The platform returns the operations in the order of their IDs. To find a pending restart of a device, combine the filters, for example `deviceId=&status=PENDING&fragmentType=c8y_Restart`. ### To cancel a pending operation {#to-cancel-a-pending-operation} The platform has no separate cancel request. To cancel an operation, set its status to FAILED. Send an [Update a specific operation status](https://cumulocity.com/api/core/#operation/putOperationResource) request: ```http PUT /devicecontrol/operations/ Content-Type: application/json Accept: application/json { "status": "FAILED", "failureReason": "Canceled by operator" } ``` The platform returns HTTP 200 and the operation with `"status": "FAILED"`. If the platform returns HTTP 422, the operation already completed with SUCCESSFUL and you cannot change it. In the Device Management application, you can cancel pending operations in the **Control** tab of the device, see [Working with operations](https://cumulocity.com/docs/device-management-application/monitoring-and-controlling-devices/#to-cancel-pending-single-operations). ## 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 /devicecontrol/operations](https://cumulocity.com/api/core/#operation/getOperationCollectionResource): Retrieve a list of operations - [PUT /devicecontrol/operations/{id}](https://cumulocity.com/api/core/#operation/putOperationResource): Update a specific operation status ## Linked from the documentation - [Monitoring and controlling devices > Working with operations](https://cumulocity.com/docs/device-management-application/monitoring-and-controlling-devices/#working-with-operations)