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:
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.
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
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:
IFfree_space_GB <= 6THEN trigger library remote action for remediation Disk Cleanup.
IFremote_action.get_startup_impact_windows.execution.outputs.HighImpactCount > 0THEN 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.
IFremote_action.get_battery_status.execution.outputs.BatteryHealth <= 0.85THEN 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.
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_resultNQL 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.
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
