Learn
Documentation
Support
Community

Remediating device issues with self-service portals

To help you get started, review the NQL examples for typical self-service use cases.

To provide employees with basic information and troubleshooting options related to their devices, leverage Nexthink data to retrieve device information and launch specific remediations to:

  • Fix disk space issues using Remote actions.

  • Troubleshoot Microsoft Teams using Workflows.

  • Order a new battery to remediate low battery health.

Prerequisites

Before you start integrating your self-service portal with Nexthink, ensure that you have the following in place:

  • Nexthink license

  • Administrator permissions

Designing self-service portal interaction

Interaction stage
API technology

Step 1: Authenticate communication

Configure API credentials and collect a token via the API.

Step 2: Identify the device

Use NQL API to allow the self-service portal widget to identify devices based on username. Alternatively, for larger organizations, Nexthink strongly recommends using Data Exporter to cache this information.

Step 3: Diagnose the device

Use NQL API (or Data Exporter) to retrieve device performance data and outputs of the Get Startup Impact and Get Battery Status remote actions.

Step 4: Remediate the issue

Use Remote Actions API to trigger the Disk Cleanup remote action on a user device.

Step 5: Follow up on the fix

Use NQL API to get the remediation status and details and inform the user about the remediation results.

In Nexthink

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 needs.

Configuring 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 for more information

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

Configuring remediation remote actions

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

Input parameters for Disk Cleanup remote action

Input
Recommended value

DiskCleanupCampaignId

If you want to display a campaign, use the Nexthink Library campaign disk_cleanup_invoke.

If you don’t want a campaign confirmation pop-up to appear, enter value 00000000-0000-0000-0000-000000000000

CleanupCompletedCampaignId

If you want to display a campaign, use the Nexthink Library campaign disk_cleanup_completed.

If you don’t want a campaign notification pop-up to appear, enter value 00000000-0000-0000-0000-000000000000

RemoveFilesNotModifiedInDays

Default value from Nexthink Library (7)

MaximumDelayInSeconds

Default value from Nexthink Library (30)

CleanupLevel

Choose the cleanup level, Light or Deep.

This field works only if you do not to use a campaign and involve the employee in choosing the cleanup level. Otherwise, an employee’s choice takes precedence.

When you complete this step, save the remote action's NQL ID for use in the next steps.

NQL ID: disk_cleanup

Creating 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: Identify device.

  • Get device data to perform diagnostics for the current topic—Stage 2: Diagnosie device.

  • Get the remote action status and results—Stage 4: Follow up on the fix.

See details of each NQL API query.

Get user devices based on the username of the user

Query ID: #get_device_basic_infos

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. For alternative approaches, see the Pre-built section.

Get device data to perform diagnostics for the current topic

Query ID: #diagnose_device_bad_health

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

Prerequisites:

  • You retrieved the device name in a previous step.

  • In this example, you collect three data points:

    • The free disk space is an out-of-the-box metric.

    • Checking applications with high startup impact requires a remote action called Get Startup Impact from Nexthink Library. Install, configure and schedule the remote action to run daily.

    • Checking battery health requires a remote action called Get Battery Status from Nexthink Library. You must install, configure and schedule the remote action to run daily.

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

Get the disk cleanup remote action

Content: Remote Action from Nexthink Library (NQL ID: disk_cleanup)

Prerequisites:

  • The collector.uid has been retrieved in a previous step via the NQL API or a data export.

  • Install the remote action Disk Cleanup or copy the remote action from Nexthink Library and configure it as follows:

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

Creating API credentials

Create API credentials in the Nexthink web interface to establish secure communication between Nexthink and the self-service portal. Select Remote Actions API and NQL API in the Permissions section. Refer to the API credentials documentation for more information.

In the self-service portal

After configuring all necessary API features within Nexthink, move on to implementing API calls.

Step 1: Authenticate communication

Prior to executing the following API calls, you first need to retrieve a valid authentication token. Refer to the Nexthink Developer documentation on how to obtain a valid OAuth token using your generated API credentials.

Step 2: Identify the device

To identify the device, use the #get_device_basic_infos NQL API query that you created under Get user devices based on the username of the user.

API Request

POST /api/v1/nql/execute

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

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"
        ]
    ]
}

Note:

  • If the status code is not 200, the request either failed or the rate limit was exceeded. Refer to the Nexthink Developer 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. 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.

For larger organizations, Nexthink recommends relying on your CMDB to identify which devices are used by which employees. Leverage Nexthink data to enrich and fix your CMDB data using the Data exporter. Refer to the following documentation on how to set up exported via SFTP or exported via HTTP for ServiceNow.

Consider performing a regular data export based on an NQL query to extract key user information. 

session.events past 30d
| summarize last_event = time.max() by collector.uid, device.name, operating_system.platform, operating_system.name,
       hardware.type, hardware.manufacturer, last_seen

Step 3: Diagnose a given device

To get device information after the user has selected their device, use the #diagnose_device_bad_health NQL API query that you created previously under Get device data to perform diagnostics for the current topic.

API Request

POST /api/v1/nql/execute

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

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.

Note:

  • If the status code is not 200, the request either failed or the rate limit was exceeded. Refer to the Nexthink Developer documentation for further details.

  • If the returned list is empty, the user has not been active on any device within the specified timeframe.

  • 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 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.

Step 4: Remediate the issue

Use Remote Action API to execute the Disk Cleanup remote action that you configured in the previous step and remedy the problem after an employee clicks on the button in their self-service widget—see Configuring remediation remote actions.

API Request

POST /api/v1/act/execute

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

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.

Note:

  • If the status code is anything other than 200, then the request failed or the rate limit was reached. Refer to the Nexthink developer portal documentation for more information.

Step 5: Follow up on the fix

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

Nexthink recommends making a call to get the remote action results no earlier than 1 minute after triggering the remote action with the API.

For real-time feedback and if supported by your self-service portal development, consider using a webhook to be notified when the remote action completes instead.

Input from the previous step

You retrieved the request_id in Step 4: Remediate the issue via the Remote action API call.

API Request

POST /api/v1/nql/execute

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

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 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, this is not exposed directly to employees.

  • remote_action.execution.outputs is a JSON map that includes 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.

Note:

  • If the status code is anything other than 200, then the request failed or the rate limit was reached. Refer to the Nexthink developer portal documentation for further 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.

Pre-built content

To help you get started with self-service portal integration, find examples of topics that you can use in typical chatbot conversations. Each topic includes:

  • Prerequisite data collection remote actions. All remote actions referred to in this section are available in Nexthink Library and you must configure them beforehand:

    • Choose the trigger type Schedule active for data collection remote action and set the schedule to hourly or daily, depending on the required frequency.

    • Choose the trigger type API active for the remediation remote action. Refer to the Manage Remote Actions documentation for more information.

  • A diagnostic NQL query.

  • Logic on how to interpret the diagnostic query results.

  • Possible remediations for each diagnostic.

Implement the examples using a similar flow to the end-to-end use case, assuming you have identified the device name beforehand.

General queries

As shown in the end-to-end use case, configure generic queries in order to perform basic tasks that can be useful across all use cases:

Task
NQL queries

Retrieve device of a user

Query ID: #get_device_basic_infos - matching based on the username

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

You can adjust the where clause | where user.name == $username for use with alternative approaches, for example:

  • If you know the user UPN: | where user.upn == $upn (requires the UPN to be activated at Collector level)

  • If you know the user email address: | where user.ad.email_address == $email (requires the Azure AD connector to be activated and the email field synced)

  • If you know the device name: | where device.name == $device_name

Adjust the timeframe if you want to consider devices on which the user has been active during a period of time other than 7 days.

Replace both past 7d clauses with the desired timeframe, up to the maximum data retention period in your Nexthink tenant, which is by default 30 days.

Retrieve the status and outputs of remediation remote actions

Query ID: #get_remote_action_result

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

RELATED TOPIC

Last updated

Was this helpful?