# Use case: Remediating disk issues with a chatbot

This use case details the steps to configure and integrate a chatbot solution with Nexthink API features to fix, in this case, a disk-related issues.

This document provides **NQL** examples for common chatbot tasks essential for issue resolution, including:

* Providing employees with basic troubleshooting related to their device issues.
* Leveraging Nexthink data about employee devices to retrieve basic device information.
* Launching a remediation to fix a disk issue.

## Step 1 - Design the user-chatbot interaction for disk-issue resolution using API technologies

Design standardized steps for the employees-chatbot interaction and define the API technologies to use in each step.

Refer to the [](https://docs.nexthink.com/platform/solutions/chatbots/integrating-chatbots-with-nexthink "mention") documentation to understand the chatbot flow.

The following table illustrates the designed interaction steps for this use case.

<table><thead><tr><th width="220">Interaction stage</th><th>API technology</th></tr></thead><tbody><tr><td><ol><li>Authenticating communication</li></ol></td><td>Configure <strong>API credentials</strong> and Collect a token via the API.</td></tr><tr><td><ol start="2"><li>Identifying the device</li></ol></td><td>Use <strong>NQL API</strong> to allow the chatbot to identify the devices based on the <code>username</code>. Alternatively, use the Data Exporter.</td></tr><tr><td><ol start="3"><li>Diagnosing the user device</li></ol></td><td>Use <strong>NQL API</strong> (or Data Exporter) to retrieve device performance data and outputs of the <strong>Get Startup Impact</strong> and <strong>Get Battery Status</strong> remote actions.</td></tr><tr><td><ol start="4"><li>Remediating the issue</li></ol></td><td>Use <strong>Remote Action API</strong> to trigger the <strong>Disk Cleanup</strong> remote action on a user's device.</td></tr><tr><td><ol start="5"><li>Following up on the fix</li></ol></td><td>Use <strong>NQL API</strong> to get the remediation status and details and inform the user about the remediation results.</td></tr></tbody></table>

{% hint style="info" %}
The selection of technology will hinge on how you currently utilize Nexthink features and the limits available in your license. Refer to [Nexthink Infinity thresholds and limits overview](https://edocs.nexthink.com/nexthink-infinity/infinity-specifications/nexthink-infinity-default-thresholds-overview) documentation page for more information, including API limits.
{% endhint %}

***

## Step 2 - Configure Nexthink content to support the chatbot integration via API

Configure API features in the Nexthink web interface. Nexthink recommends following the sequence in which the features are listed, as some are interdependent. Nonetheless, you have the flexibility to navigate between different solutions according to your preference.

### Configure data-collection remote actions

Install the following remote actions from Nexthink Library:

* **Get Startup Impact**
* **Get Battery Status**

Schedule the executions to occur daily. Refer to [Managing remote actions](https://docs.nexthink.com/platform/user-guide/remote-actions/managing-remote-actions) for more information

{% hint style="success" %}
When you complete this step, save the NQL ID of both remote actions to use in the next steps.

NQL ID's:

* `get_startup_impact_windows`
* `get_battery_status`
  {% endhint %}

### Configure remediation remote actions

Install the **Disk Cleanup** remote action from Nexthink Library. If already Installed, copy it and configure it as follows:

* Select **API** for the remote action trigger.
* Set default input parameter values that are in line with your chatbot needs. See the [Input parameters for Disk Cleanup remote action](#input-parameters-for-disk-cleanup-remote-action) table below.

#### Input parameters for Disk Cleanup remote action

<table><thead><tr><th width="337">Input</th><th>Recommended value</th></tr></thead><tbody><tr><td><code>DiskCleanupCampaignId</code></td><td><p>If you want to display a campaign, use the library campaign <code>disk_cleanup_invoke</code>.</p><p>If you don’t want a campaign confirmation pop-up to appear, enter value 00000000-0000-0000-0000-000000000000</p></td></tr><tr><td><code>CleanupCompletedCampaignId</code></td><td><p>If you want to display a campaign, use the library campaign <code>disk_cleanup_completed</code>.</p><p>If you don’t want a campaign notification pop-up to appear, enter value 00000000-0000-0000-0000-000000000000</p></td></tr><tr><td><code>RemoveFilesNotModifiedInDays</code></td><td>Default value from Library (7)</td></tr><tr><td><code>MaximumDelayInSeconds</code></td><td>Default value from Library (30)</td></tr><tr><td><code>CleanupLevel</code></td><td><p>Choose the cleanup level, Light or Deep.</p><p>This field works only if you decide not to use a campaign and involve the employee in choosing the cleanup level. Otherwise, an employee’s choice takes precedence.</p></td></tr></tbody></table>

{% hint style="success" %}
When you complete this step, save the remote action's NQL ID for use in the next steps.

NQL ID: `disk_cleanup`
{% endhint %}

### Create NQL API queries

According to the designed scenario, you need to create three NQL API queries:

* Get user devices based on the `username` of the user (Stage 1: Identifying device).
* Get device data to perform diagnostics for the current topic (Stage 2: Diagnosing device).
* Get the remote action status and results (Stage 4: Following up on the fix).

See details of each NQL API query.

<details>

<summary>Get user devices based on the username of the user</summary>

**Query ID**: #get\_device\_basic\_infos

**NQL query**:

```
devices during past 7d
| with session.events past 7d
| where user.name == $username
| list collector.uid, device.name, operating_system.platform, operating_system.name,
       hardware.type, hardware.manufacturer, last_seen
| sort last_seen desc
```

* The `collector.uid` field is the key that the system uses in the subsequent interactions to trigger a remote action.
* Matching is based on the `username`. Alternative approaches are also available, see the [Pre-built](#chatbotusecases-pre-builtcontentprebuilt) section.

</details>

<details>

<summary>Get device data to perform diagnostics for the current topic</summary>

**Query ID**: #diagnose\_device\_bad\_health

**NQL query**:

```
devices
| where device.name == $device_name
| include device_performance.events during past 24h
| compute free_space = system_drive_free_space.avg() / 1000000000
| list collector.uid, device.name, free_space,
       remote_action.get_startup_impact_windows.execution.outputs.HighImpactCount,
       remote_action.get_battery_status.execution.outputs.BatteryHealth
```

The query includes the `$device_name` parameter, which the chatbot will retrieve in a previous stage of interaction.

In this example, you collect 3 data points:

* The `free_space` is an out-of-the-box metric.
* Checking applications with high startup impact (`HighImpactCount`) requires a remote action called **Get Startup Impact** from Nexthink Library.
* Checking battery health (`BatteryHealth`) requires a remote action called **Get Battery Status** from Nexthink Library.

Refer to [Configuring data collection remote actions](#configuring-data-collection-remote-actions) section on this page.

If the remote actions are not scheduled or have not run yet on the device, then the corresponding columns appear empty.

</details>

<details>

<summary>Get the remote action status and results</summary>

**Query ID**: #get\_remote\_action\_result

**NQL Query:**

```
remote_action.executions past 24h
| where request_id == $request_id
| list request_id, device.name, remote_action.name, status, status_details, outputs
```

The query includes the `$request_id` parameter, which the chatbot retrieves in a previous stage of interaction from the remote action API call.

You can use the same generic query for any configured remote action.

{% hint style="info" %}
Nexthink recommends making a call to get the remote action results no earlier than 1 minute after triggering the remote action with the API.
{% endhint %}

</details>

{% hint style="success" %}
When you complete this step, save the NQL ID's of all NQL API queries to use them in the next steps.

NQL ID's:

* \#get\_device\_basic\_infos
* \#diagnose\_device\_bad\_health
* \#get\_remote\_action\_result
  {% endhint %}

### **Configure API credentials** <a href="#chatbotusecases-authentication" id="chatbotusecases-authentication"></a>

Create API credentials in the Nexthink web interface to establish secure communication between Nexthink and the chatbot. Select **Remote Actions API** and **NQL API** in the **Permissions** section. Refer to [API credentials](https://docs.nexthink.com/api) for more information.

{% hint style="success" %}
When you complete this step, save the Client ID and Client Secret obtained during the credential creation in the Nexthink web interface.
{% endhint %}

***

## **Step 3 - Implement API calls within the chatbot's service layer**

{% hint style="info" %}
Refer to the [#using-pre-built-content-to-configure-chatbot-integrations](#using-pre-built-content-to-configure-chatbot-integrations "mention") documentation to adapt available pre-built content and accelerate the configuration of your chatbot integration logic.
{% endhint %}

Once you configured all necessary API features within Nexthink, move on to implementing the Nexthink REST API calls within the chatbot's service layer.

The following stages reflect the [user-chatbot interaction design](#designing-user-chatbot-interaction-with-api-technologies).

### Chatbot first stage: Authenticating communication

Prior to executing the following API calls, you first need to retrieve a valid authentication token. Refer to the Nexthink [Nexthink Developer](https://developer.nexthink.com/docs/api/getting-an-authentication-token) documentation on how to obtain a valid OAuth token using your generated [API credentials](https://docs.nexthink.com/api).

### Chatbot second stage: Identifying the device

> Employee (user)\
> \&#xNAN;*I have an issue with my device*

To identify the device, use the `#get_device_basic_infos` **NQL API** query that you created previously (See: [Get user devices based on the username of the user](#get-user-devices-based-on-the-username-of-the-user)).

{% hint style="warning" %}
Your chatbot platform should be able to maintain session context across API calls. For example, the device identifier retrieved in this step needs to be stored and reused in later stages: diagnose, remediate, confirm fix.
{% endhint %}

<details>

<summary><strong>API Request</strong></summary>

`POST /api/v1/nql/execute`

```
{
 "queryId": "#get_device_basic_infos",
 "parameters": {
 "username": "[username identified by the chatbot]"
  }
}
```

</details>

<details>

<summary><strong>Example API Response</strong></summary>

Status 200

```
{
 "queryId": "#get_device_basic_infos",
 "executedQuery": "...",
 "rows": 2,
 "executionDateTime": { ... },
 "headers": [
 "device.collector.uid",
 "device.name",
 "device.operating_system.platform",
 "device.operating_system.name",
 "device.hardware.type",
 "device.hardware.manufacturer",
 "device.last_seen"
    ],
 "data": [
        [
 "e0aa796d-e3af-47b5-88d8-228cf5551fb6",
 "XN1231242-2142",
 "Windows",
 "Windows 11 Pro 22H2 (64 bits)",
 "laptop",
 "Lenovo",
 "2023-07-17 17:53:49"
        ],
        [
 "9866a43b-caab-4948-86d2-5567b3ac1d24",
 "XCX124231-1231",
 "macOS",
 "macOS Ventura 13.4.1 (ARM 64 bits)",
 "laptop",
 "Apple",
 "2023-07-17 17:53:03"
        ]
    ]
}
```

**Notice:**

* If the status code is anything other than 200, then the request failed or the rate limiting was hit. Refer to the [Nexthink Developer](https://developer.nexthink.com/docs/api/nql-api-overview) documentation for details.
* If the returned list is empty, then the user has not been active on a device in the specified timeframe, `past 7d` in this example. Note that there is also a small delay between the time the employee starts using a device and the time the data is available in the Nexthink data platform.

</details>

### Chatbot third stage: Diagnosing the device

> (Chatbot)\
> \&#xNAN;*I have found the following devices for you, which one are you having issues with?*
>
> *(1) Laptop XN1231242-2142 (Lenovo)*
>
> *(2) Laptop XCX124231-1231 (Apple)*

> Employee (user)\
> \&#xNAN;*1*

To get device information, use the `#diagnose_device_bad_health` **NQL API** query that you created previously (See: [Get device data to perform diagnostics for the current topic](#get-device-data-to-perform-diagnostics-for-the-current-topic)).

{% hint style="info" %}
**Input from the previous step**

You retrieved the device name in [Second stage: Identifying the device](#chatbot-second-stage-identifying-the-device).
{% endhint %}

<details>

<summary><strong>API Request</strong></summary>

`POST /api/v1/nql/execute`

```
{
 "queryId": "#diagnose_device_bad_health",
 "parameters": {
 "device_name": "[device name identified by the chatbot]"
  }
}
```

</details>

<details>

<summary><strong>Example API Response</strong></summary>

Status 200

```
{
 "queryId": "#diagnose_device_bad_health",
 "executedQuery": "...",
 "rows": 1,
 "executionDateTime": { ... },
 "headers": [
 "device.collector.uid",
 "device.name",
 "free_space_GB",
 "remote_action.get_startup_impact_windows.execution.outputs.HighImpactApplications",
 "remote_action.get_startup_impact_windows.execution.outputs.HighImpactCount",
 "remote_action.get_battery_status.execution.outputs.BatteryHealth"
    ],
 "data": [
        [
 "e0aa796d-e3af-47b5-88d8-228cf5551fb6",
 "XN1231242-2142",
 2.2316807136971,
 "",
 null,
 0.9
        ]
   ]
}
```

* Note that the `collector.uid` field is the key that the system uses in subsequent interactions to trigger a remote action.
* The chatbot uses three columns as decision branches in a conversation:
  * **IF** `free_space_GB <= 6`\
    **THEN** trigger library remote action for remediation **Disk Cleanup**.
  * **IF** `remote_action.get_startup_impact_windows.execution.outputs.HighImpactCount > 0`\
    **THEN** trigger library remote action for remediation **Disable Application from Startup menu** using the value of `remote_action.get_startup_impact_windows.execution.outputs.HighImpactApplications` to disable high-impact applications.
  * **IF** `remote_action.get_battery_status.execution.outputs.BatteryHealth <= 0.85`\
    **THEN** a replacement battery would be required: create an ITSM ticket from the chatbot to follow up.

**Notice:**

* If the status code is anything other than 200, then the request failed or the rate limiting was hit. Refer to the [Nexthink developer platform](https://developer.nexthink.com/docs/api/nql-api-overview) documentation for more information.
* If the list returned by the system is empty, then the device was not found.
* If any of the diagnostic fields are null or empty, then no information is available. Possible reasons for empty values are:
  * For data platform fields, the field is not supported by the platform. Please refer to the [NQL data model](https://docs.nexthink.com/platform/understanding-key-data-platform-concepts/nql-data-model) documentation for more information.
  * For remote action fields, the system has not yet executed the remote action successfully. Check the remote action schedule and targeting NQL query, and the remote action dashboard for possible execution errors.

</details>

### Chatbot fourth stage: Remediating the issue

> (Chatbot)\
> \&#xNAN;*Thanks, I see that your device has only about 2 GB of free disk space left.*
>
> *I can clean up unneeded files to prevent slowdowns.*
>
> *Do you want me to proceed?*

> Employee (user)\
> \&#xNAN;*Yes*

Use **Remote Action API** to execute **Disk Cleanup** remote action that you configured in the previous step and remedy the problem (See: [Configuring remediation remote actions](#configure-remediation-remote-actions)).

The Remote Action API response includes the execution status (success/failure) and any defined outputs. Your chatbot can use this information to confirm that the fix was applied successfully or to continue troubleshooting if needed.

{% hint style="info" %}
**Input from the previous step**

You retrieved the `collector.uid` in [Third stage: Diagnosing the device](#chatbot-third-stage-diagnosing-the-device) via the `#diagnose_device_bad_health` [NQL API](#get-device-data-to-perform-diagnostics-for-the-current-topic) (or a data export).
{% endhint %}

<details>

<summary><strong>API Request</strong></summary>

`POST /api/v1/act/execute`

```
{
 "remoteActionId": "disk_cleanup",
 "devices": ["e0aa796d-e3af-47b5-88d8-228cf5551fb6"]
}
```

</details>

<details>

<summary><strong>Example API Response</strong></summary>

Status 200

```
{
 "requestId":"f27efd0c-8cb2-4d00-aae0-261aa06729c7",
 "expiresInMinutes":10080
}
```

* A successful API call indicates that the remote action is scheduled for execution as soon as the endpoint is ready.
* The returned request ID allows you to follow up on the execution status.
* The call is asynchronous, which means that a successful API call does not indicate that a remote action has started executing nor that it was completed.

**Notice:**

* If the status code is anything other than 200, then the request failed or the rate limiting was reached. Refer to the [Nexthink developer portal](https://developer.nexthink.com/) documentation for more information.

</details>

### Chatbot fifth stage: Following up on the fix

> (Chatbot)\
> \&#xNAN;*I have launched the fix. It should only take a short while.*

Use the `#get_remote_action_result` **NQL API** query that you created previously to get the remote action status and results.

(See: [Get the remote action status and results](#get-the-remote-action-status-and-results)).

{% hint style="warning" %}
Nexthink recommends making a call to get the remote action results no earlier than 1 minute after triggering the remote action with the API.
{% endhint %}

{% hint style="info" %}
**Input from the previous step**

You retrieved the `request_id` in [Fourth stage: Remediating the issue](#chatbot-fourth-stage-remediating-the-issue) via the **Remote action API** call.
{% endhint %}

<details>

<summary><strong>API Request</strong></summary>

`POST /api/v1/nql/execute`

```
{
 "queryId": "#get_remote_action_result",
 "parameters": {
 "request_id": "f27efd0c-8cb2-4d00-aae0-261aa06729c7"
  }
}
```

</details>

<details>

<summary><strong>Example API Response</strong></summary>

Status 200

```
{
 "queryId": "#get_remote_action_result",
 "executedQuery": "...",
 "rows": 1,
 "executionDateTime": { ... },
 "headers": [
 "remote_action.execution.request_id",
 "device.name",
 "remote_action.name",
 "remote_action.execution.status",
 "remote_action.execution.status_details",
 "remote_action.execution.outputs"
    ],
 "data": [
        [
 "XN1231242-2142",
 "f27efd0c-8cb2-4d00-aae0-261aa06729c7",
 "Disk Cleanup",
 "success",
 "Disk cleanup successfully performed. \r\nPowerShell exited with code 0\n",
 "{\"CleanupSpace\":1324470272.0}"
        ]
    ]
}
```

* `remote_action.execution.status` indicates the current execution status. Key statuses include:
  * `success` when the remote action has been successfully executed.
  * `in_progress` if the system has not yet completed the execution. Refer to the [Remote Action](https://docs.nexthink.com/platform/user-guide/remote-actions/getting-started-with-remote-actions) documentation for more information about the various states of remote actions.
* `remote_action.execution.status_details` contains remote action execution details that can help you in troubleshooting. By design, it is not exposed directly to employees.
* `remote_action.execution.outputs` is a JSON map that includes the output values of the remote action. For the **Disk Cleanup** remote action, the returned value is the amount of space that has been freed (in bytes).

**Notice:**

* If the status code is anything other than 200, then the request failed or the rate limiting was reached. Refer to the [Nexthink developer portal](https://developer.nexthink.com/) documentation for more information.
* If the system returned an empty list, then the system has not yet created the remote action execution. This happens if you call the API too soon after the time you triggered the API, or if the execution is older than 24 hours, which is the timeframe specified in the query.

</details>

#### Ending the conversation <a href="#chatbotusecases-conversation-stage5" id="chatbotusecases-conversation-stage5"></a>

{% hint style="info" %}
Display the remote action `status` and `output` retrieved in this step.
{% endhint %}

> (Chatbot)\
> \&#xNAN;*I am all done - I freed up 1.3 GB. Is there anything else I can do to help you*?

***

RELATED TOPIC

* [](https://docs.nexthink.com/platform/solutions/chatbots/integrating-chatbots-with-nexthink "mention")
* [#optionally-make-the-workflow-available-in-nexthink-spark](https://docs.nexthink.com/platform/user-guide/workflows/creating-workflows#optionally-make-the-workflow-available-in-nexthink-spark "mention")