--- name: cumulocity-request-diagnostics description: "Check that a device supports diagnostics reports, request a report with a c8y_DiagnosticReport operation, download the report file, and delete it. Use when the user wants to get a diagnostics report from a device." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Request a diagnostics report from a device Source: https://cumulocity.com/docs/skills/device-management/request-diagnostics/ Sector: Skills, Device management & connectivity Release: Latest Description: Check that a device supports diagnostics reports, request a report with a c8y_DiagnosticReport operation, download the report file, and delete it. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) To get a diagnostics report from a device, you send the device a `c8y_DiagnosticReport` operation. The device generates the report and uploads it as a file to the inventory. It then sets the operation to SUCCESSFUL and writes the URL of the file into the operation. The operation goes through the same statuses as any other operation, see [Send an operation to a device](https://cumulocity.com/docs/skills/device-management/send-operation/). A device supports diagnostics reports if its `c8y_SupportedOperations` fragment contains `c8y_DiagnosticReport`. The Device Management application then shows the **Diagnostics** tab for the device. > **Requirements:** > ROLES & PERMISSIONS: > > * To read the device and download the report: ROLE_INVENTORY_READ > * To create the operation: ROLE_DEVICE_CONTROL_ADMIN > * To read the operation: ROLE_DEVICE_CONTROL_READ > * To delete the report: ROLE_INVENTORY_ADMIN The examples use `` for the ID of the device and `` for the ID of the operation. ### To check that the device supports diagnostics reports {#to-check-that-the-device-supports-diagnostics-reports} Send a [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request: ```http GET /inventory/managedObjects/ ``` The platform returns HTTP 200 and the managed object. Check the following: * The fragment `c8y_IsDevice` is present. * The array `c8y_SupportedOperations` contains `"c8y_DiagnosticReport"`. If `c8y_DiagnosticReport` is missing, do not request a report. No agent executes the operation. ### To request the report {#to-request-the-report} 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": "Diagnostic file request", "c8y_DiagnosticReport": {} } ``` The operation has no parameters, so the `c8y_DiagnosticReport` fragment is empty. 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 does not exist, or neither the device nor one of its parent devices is an agent. ### To get the URL of the report {#to-get-the-url-of-the-report} 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, for example for at most 2 minutes: * **SUCCESSFUL**: The property `c8y_DiagnosticReport.file` contains the URL of the report, in the form `https:///inventory/binaries/`. If the property is missing, the device completed the operation without uploading a report. * **FAILED**: The `failureReason` property describes why the device did not provide the report. If the operation is still PENDING after the timeout, no agent picked it up. Cancel it as described in [To cancel a pending operation](https://cumulocity.com/docs/skills/device-management/send-operation/#to-cancel-a-pending-operation). If it is still EXECUTING, do not cancel it, because the device can still complete it. See [To follow the status of the operation](https://cumulocity.com/docs/skills/device-management/send-operation/#to-follow-the-status-of-the-operation). ### To download the report {#to-download-the-report} `` is the last part of the URL in `c8y_DiagnosticReport.file`. Send a [Retrieve a stored file](https://cumulocity.com/api/core/#operation/getBinariesResource) request: ```http GET /inventory/binaries/ ``` The platform returns HTTP 200, and the response body is the content of the report. If it returns HTTP 404, the report was deleted after the device uploaded it. ### To delete the report {#to-delete-the-report} Send a [Remove a stored file](https://cumulocity.com/api/core/#operation/deleteBinariesResource) request: ```http DELETE /inventory/binaries/ ``` The platform returns HTTP 204 and deletes the file. The operation still contains the URL in `c8y_DiagnosticReport.file`. A download from this URL now returns HTTP 404. ## 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 /inventory/binaries/{id}](https://cumulocity.com/api/core/#operation/getBinariesResource): Retrieve a stored file - [DELETE /inventory/binaries/{id}](https://cumulocity.com/api/core/#operation/deleteBinariesResource): Remove a stored file ## Linked from the documentation - [Viewing device details](https://cumulocity.com/docs/device-management-application/viewing-device-details/)