Device monitoring and troubleshooting

We recommend providing your customer with the means to monitor the state of their Knox E-FOTA device fleet. This way, they can identify if there are any problem devices, or issues with firmware rollout, and take steps to troubleshoot them. The Knox E-FOTA API provides tools to track device fleet status, and identify issues with devices.

Reporting device status in the device list

The list of devices returned from POST /devices/getDevices includes detailed information about each device, including the status of the device, which can indicate whether a device requires extra attention.

There are 3 types of device statuses provided by Knox E-FOTA:

• Operation status
• Client status
• Update status

Operation status

This status indicates whether the device is awaiting upload or campaign syncs, and also indicates the state of the license. Here are the possible operation statuses, categorized by their importance:

Attention

• InvalidLicense
• CampaignSyncExpected

No action needed

• Pending
• CampaignSynced
• NoLicenseAssigned
• LicenseAssigned

Client status

This status indicates whether the Knox E-FOTA client on the device is running properly, and what operations it is performing, including firmware downloads and installation. If a device’s Knox E-FOTA client is in an error state, POST /devices/getDevices also returns the Knox E-FOTA client error code in the agentError response field. We provide documentation on these Knox E-FOTA client error codes, which also include troubleshooting steps your customer can try to resolve the client error they are facing.

Here are the possible client statuses, categorized by status:

Error

• FailedToDownload
• FailedToEnroll
• FailedToInstall
• CampaignError
• InvalidFirmware

In-progress of an operation

• AwaitingForDownload
• AwaitingForInstall
• InprogressDownloading
• InprogressInstalling
• Reverting

Operation completed

• HigherFirmware
• LockedFirmware
• Updated

No action needed

• Enrolled
• Not enrolled

Update status

This status gives your customers a heads-up overview of what actions they may need to take. The Update status is determined using the operation status and client status.

Here are the update statuses:

• Completed: No operations are pending.
• Inprogress: Preparing for, or in the process of a firmware download or installation.
• Attention: Your customer needs to take action.
• Error: Encountered an error with firmware downloads or installation, or there is a campaign or enrollment error.

Here is an example of how the Knox E-FOTA portal shows the device update status, along with the operation and client status counts in each update status.

Knox Webhook Notification for device status changes

Instead of having to call the Knox E-FOTA API to get device status changes, you can subscribe to the KE_DEVICE_STATUS_CHANGE event on Knox Webhook Notification. With this set up, Knox Webhook Notification will send your UEM app a notification whenever one of your customer’s devices change statuses, and you can use this to update your UI to show your customers the latest status of their devices without having to call the Knox E-FOTA API.

For more information, see the Knox Webhook Notification tutorial for Knox E-FOTA.

Here is a Java code sample that subscribes to this event on Knox Webhook Notification:

private HttpResponse<String> createDeviceStatusChangeSubscription(String callbackUrl) throws URISyntaxException, IOException, InterruptedException {
    String subscriptionUrl = WEBHOOK_URI + "subscriptions";
    String body = "{\n" +
            "\"url\": " + callbackUrl + ",\n" +
            "\"events\": [\n" +
            "\"KE_DEVICE_STATUS_CHANGE\"\n" +
            "]\n" +
            "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(subscriptionUrl))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .headers("Content-Type", "application/json;charset=UTF-8",
                    "Authorization", "Bearer " + accessToken)
            .build();
    return client.send(request, HttpResponse.BodyHandlers.ofString());
}

Response sample:
{ "payload": { "id": "636c1a692d0f427ee1f07470", "url": "https://some.domain/kwn-results", "events": [ "KE_DEVICE_STATUS_CHANGE" ] } }

Device and activity log

To further improve your customer’s user experience, we recommend implementing an activity log and a device log.

An activity log can show all actions performed on your UEM portal by your customer that affected the status of Knox E-FOTA campaigns or devices. The log can show each action, the timestamp of the action, and which user made that action on your UEM portal.

A device log can show all events which have occurred on a device. For each event, the log can show the resulting device state, along with a timestamp. This log should be available for all devices in your customer’s Knox E-FOTA device pool.

Force client refresh

Knox E-FOTA provides a feature to refresh the client app on your customer’s fleet of devices.

Firmware updates are complicated processes. Often times, devices may be stuck in an unexpected state, preventing them from properly performing firmware updates. If this problem occurs, your customer can force the Knox E-FOTA client app on their devices to refresh, which pushes the latest campaign to the devices, and deletes any firmware that has been downloaded but not yet installed.

Use POST /devices/bulkRefresh to allow your customer to refresh the client app on a list of devices.

Here is a Java code sample that refreshes the client app on a list of specified devices.

private HttpResponse<String> bulkRefresh(String accessToken) throws URISyntaxException, IOException, InterruptedException {
    String bulkRefreshUrl = API_URI + "devices/bulkRefresh";
    String body = "{\n" +
            "\"deviceIds\": [\"imei\",\"sn\"]\n" +
            "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(bulkRefreshUrl))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .headers("Content-Type", "application/json;charset=UTF-8",
                    "Authorization", "Bearer " + accessToken)
            .build();
    return client.send(request, HttpResponse.BodyHandlers.ofString());
}

Response sample:
{  "transactionId": "T882582188b10", "code": "KFMBE0N00000", "message": "SUCCESS", "data": { "operationId":  "64f91045d4f2de17e3923590", "devicesToProcessCount": 2 } }

Subscribe to the KE_DEVICE_BULK_REFRESH event with Knox Webhook Notification to receive result notifications when the refresh is complete.

For more information, see the Knox Webhook Notification API reference.

private HttpResponse<String> createBulkRefreshSubscription(String callbackUrl) throws URISyntaxException, IOException, InterruptedException {
    String subscriptionUrl = WEBHOOK_URI + "subscriptions";
    String body = "{\n" +
            "\"url\": " + callbackUrl + ",\n" +
            "\"events\": [\n" +
            "\"KE_DEVICE_BULK_REFRESH\"\n" +
            "]\n" +
            "}";
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(subscriptionUrl))
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .headers("Content-Type", "application/json;charset=UTF-8",
                    "Authorization", "Bearer " + accessToken)
            .build();
    return client.send(request, HttpResponse.BodyHandlers.ofString());
}

Response sample:
{ "payload": { "id": "636c1a692d0f427ee1f07470", "url": "https://some.domain/kwn-results", "events": ["KE_DEVICE_BULK_REFRESH"] } }