Manage the settings

The Knox Asset Intelligence APIs provide functionalities to manage tenant settings, offering greater visibility into device status and health. This tutorial shows you how to configure the threshold value for triggering a battery-level event using the settings endpoint. It sets up an alert for a device when its battery becomes low. Additionally, you can also use the settings endpoint to configure a device for Knox Configure enrollment.

Ensure that you have the necessary permissions to set or update the Knox Asset Intelligence settings, including obtaining an authentication token. For more information, see Get started.

Set or update threshold and enrollment settings

To set or update Knox Asset Intelligence settings:

1. Make a PUT request to the /settings endpoint.

2. In the request body, use the batteryLevelThresholds property of battery object to set the threshold value for triggering a battery level event.

   For example, the following request body sets the battery level threshold alert at 50 percent. This means when a device’s battery level hits 50 percent, a battery level event is uploaded which notifies you through Knox Webhook Notification, if subscribed.

   {
   "battery": {
       "batteryLevelThresholds": [
       50
       ]
   }
   }
   

   You can adjust the threshold value based on your low battery alert requirements. The possible values for the battery level threshold range from 1-99, and a maximum of three threshold values can be set.

   For example, the following request body sets three battery level alerts at threshold values of 50, 30, and 10 percent. When a device’s battery level hits the specified percentage value, a battery level event is uploaded.

   {
   "battery": {
       "batteryLevelThresholds": [
       50, 30, 10
       ]
   }
   }
   

   If you are subscribed to Knox Webhook Notification for these events, you will receive notifications for them.

3. Similarly, in the request body, use the allowEnrolledToKnoxConfigure property of the enrollment object to permit enrollment of devices in Knox Configure.

   For example, the following request body sets the enrollment permission to True. By default, it is set to false, and setting it to true means the devices now have permission to enroll in Knox Configure. In this example, the battery level threshold alert is also set to 50 percent.

   {
   "battery": {
       "batteryLevelThresholds": [
       50
       ]
   "enrollment" : {
       "allowEnrolledToKnoxConfigure" : true}
   }
   }
   

For detailed response schema, see Knox Asset Intelligence API.

Get threshold and enrollment settings

To retrieve Knox Asset Intelligence settings, make a GET request to the /settings endpoint. It allows you to check the values set for triggering low battery level events and whether or not the devices are allowed to enroll in Knox Configure.

Ensure that you handle errors appropriately in your application by checking the code and the message in the response. For detailed specification, see Knox Asset Intelligence API reference.

Create a subscription in Knox Webhook Notification

To receive asynchronous notifications when a low battery event is triggered:

1. Subscribe the Knox Webhook Notification API using POST POST /kwn/v1/subscriptions operation.

2. In the request body, provide a subscription URL to receive callbacks and the KAI_BATTERY_LEVEL_TRIGGERED event to subscribe to notifications for device battery level events.

For example, the following request body allows you to be notified on the subscription URL, when the battery level falls below the set threshold.

{
  "url": "https://some.domain/kwn-results",
  "events": [
    "KAI_BATTERY_LEVEL_TRIGGERED"
  ]
}

The response message containing information about the triggered battery level event is sent to the subscription URL.

For more information, see Knox Webhook Notification for Knox Asset Intelligence.