This document provides comprehensive information about the introduction and concepts around Nexthink Chatbot SDK, its API and use cases. The information contained herein is subject to change without notice and is not guaranteed to be error-free. If you find any errors, please report them to us via Nexthink Support Portal. This document is intended for readers with a detailed understanding of Nexthink technology.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
A topic is a part of the configuration of Chatbot SDK where the list of diagnosis and resolution options are recorded. It is usually related to a high-level, employee issue such as a
OutlookIssues to simplify the integration on the third-party chatbot side. The chatbot only needs to know the available topics in the Chatbot SDK and call them using REST API.
The following list is the catalog of topics provided with Chatbot SDK and available in the
Detection of most common Outlook issues (outdated version, offline, etc.) and their remediation
PC slow issues
Detection of most common issues that slow down a device (most consuming start-up apps, GPO consumption, outdated versions, etc.) and their remediation
Allows for the cleaning of the print spooler
Detection of most common OneDrive issues (not running, not properly installed, etc.) and their remediation
Installation of OneDrive if not installed
Scores based on L1 checklist (disk space, antivirus definition, memory, CPU, etc.)
Device bad health
Detection of device’s bad health (drive usage, most consuming start-up apps or battery health) and their remediation
Skype for Business health
Scores based on Skype for business checklist (video and voice quality, etc.)
Topic high-level content
Every topic has a
version and a list of diagnoses to check. A
diagnosis can be performed either by requesting information via an NXQL query or by triggering a remote action.
It is recommended to substitute the use of remote actions as a diagnosis with an NXQL query that retrieves the same information from the remote action for the following reasons:
Improvement in UX of the chatbot: there is less latency to get a response since the result is already available.
Better scalability: launching a remote action and checking the result has more impact.
This means that the remote action must be executed first on the device for the information to be available. Thus, the administrator will be responsible for scheduling the necessary remote actions. This approach only makes sense for certain remote actions, as the information they provide is not purely in real-time and gathering data on a daily basis is sufficient for most use cases. Please refer to Creating a remote action for more information.
In some cases, the diagnosis query can be left empty with the default remediations if no other diagnosis matches.
A diagnosis can have
remediation with one or several conditions:
condition, for example,
Used Disk Space > 85%
For each condition, a list of suggested remote actions is written that can be launched by the chatbot to fix a problem. This list can be left empty if there is no available remote action. In this case, it is expected that the chatbot give a recommendation. For example, the chatbot can decide to route to a Life Agent or open a support ticket in the customer’s ITSM tool.
Purpose: Detect and fix the most common Outlook issues
Issue 1: Outlook offline → Diagnosis 1: check if Outlook is offline → Remote action 1: set Outlook online
Issue 2: Outlook outdated version → Diagnosis 2: check Outlook version → Remote action 2: repair Office 365
The topic files can be found in the
config/topics directory inside the Chatbot SDK location,
The topic configuration can be done by editing the topic YAML files. The indentation is important in YAML formatting and additional information about YAML syntax can be found onYAML website.
Topics configuration elements
A topic configuration is structured as follows:
--- # Header content topic_name: version: '1.0.0' diagnosis: - query: '(select (name) … )' platform: windows remediation: - condition: '"nxql_field_value" > 1' remediation_ras: - ra_id: remote_action_id - platform: windows diagnosis_ra: ra_id: diag_remote_action_id timeout: 120 remediation: - condition: '"nxql_field_value" > 1' remediation_ras: - ra_id: remote_action_id
The header includes a description of the topic and its requirements such as necessary remote actions, Nexthink content packs, how the remote actions should be configured in Finder and a changelog for the topic’s versions. This content is formatted as a commented text in YAML and each line begins with the hashtag character
This is the descriptive name of the topic. It only uses lower-case letters, numbers and the underscore character. This name is used internally to identify the topic and needs to be unique among all topics in the
Although you can configure several topics inside a single YAML file, it is good practice to create a single topic file for each one and name it as the topic, for example,
app_outlook_issues.yaml should contain only one topic with the name
This is the current, semantic version of the topic. This field is descriptive and should have numeric values separated by dots. For example,
1.2.3 where 1 is the major version, 2 is the minor version and 3 is the patch version.
This is the list of diagnoses that can be used to identify and remediate issues. There are two ways of making a diagnosis on a device, by either using an NXQL
query or a remote action
diagnosis_ra. You can have any number of them.
NXQL is one of two ways to diagnose an employee device. The NXQL syntax details can be found in the online documentation.
When creating or editing a query it is necessary to set the
where clause to filter only the employee device data. Please use the following snippet
(where device (eq device_uid (md5 %1))). Nexthink Chatbot SDK will replace the
%1 by the proper employee
You can write the NXQL query in YAML in two different ways as a single line sentence surrounded by single quotes or in multi-line.
Single line example:
my_topic: version: '1.0.0' diagnosis: - query: '(select … (from device (where device (eq device_uid (md5 %1)))))'
my_topic: version: '1.0.0' diagnosis: - query: '(select … (from device (where device (eq device_uid (md5 %1)))))'
Executing a remote action is another way of performing a diagnosis, its content is a
The remote action identifier listed in the
remote_actions.yaml file located in the
config directory. The identifier is the descriptive name of the remote action and is internal for Chatbot SDK. Name and
uid are the descriptors available in Finder. Please note that they should exactly match those values in Finder.
The name of the remote action is case sensitive
--- repair_outlook_ost_problem: name: Repair Outlook OST Problem uid: 130bb94e-3e0b-f87c-e2b8-3a2d022394fe get_outlook_online: name: Get Outlook Online uid: bc55147a-519c-4216-43ef-c350957d5aca
Refer to the Remote action configuration documentation for more information.
This is the time in seconds that Chatbot SDK waits for a remote action to return a response before throwing an error.
This is a platform that is compatible with the diagnosis. The possible values are
windows,mac_os, which identifies a Windows only, MacOS only or Windows and MacOS valid diagnosis respectively.
Remediation contains actions that should be taken to fix a diagnosed issue. You can have as many remediations as you need. Each one is composed of a condition and a list of remote actions that should be applied.
This section is used to set a condition composed of an expression to compare the returned value from a diagnosis with a threshold or another value. If this condition matches, Nexthink Chatbot Adapter issues the execution of the remote actions which are defined in the
remeditation_ras in the device.
- query: 'select (system_drive_usage total_drive_usage) (from device (where device (eq device_uid (md5 %1))))' platform: windows remediation: - condition: system_drive_usage > 0.85 remediation_ras: - ra_id: disk_cleanup - ra_id: system_cleanup - condition: total_drive_usage > 0.7 remediation_ras: - ra_id: disk_cleanup
Chatbot SDK queries Engine for values of
total_drive_usagefor a specific device.
The first condition compares the value of
system_drive_usagewith 0.85, which can be translated as:
If the system_drive_usage is higher than 85%, then execute the remote actions called disk_cleanup and system_cleanup on this device.
The second condition is very similar, the difference is that it compares the value of
total_drive_usagewith 0.7, which can be translated as:
If the total_drive_usage is higher than 70%, then execute the remote action called disk_cleanup on this device.
Note that both conditions are evaluated.
The right clause can be either a single element or a literal expression. In the first case, declaring either a single word or a number is allowed. The name of another field or aggregate from the query is also allowed. In the second case, a string is composed of two or more words surrounded by quotes.
Example of a diagnosis that uses two field values:
- query: '(select (last_boot_duration) (from device (with device_activity (where device (eq device_uid (md5 %1))) (compute average_boot_duration) (between now-365d now))))' platform: windows remediation: - condition: last_boot_duration > average_boot_duration remediation_ras: - ra_id: disable_application_startup
Allowed comparison operators:
Compare content of two strings for equality
Compare content of two strings for inequality
Verifies if a given substring is within the string
Verifies if a given substring is not within the string
Lower than or equal to
Not equal to
Verifies if the list includes a certain value among its entries. Please note that wildcards can be used to perform a simpler search on each one of the strings composing the list.
Allowed wildcards are:
Condition will always match, this is useful for default cases
The types of the output fields in remote actions are described in the Library documentation and available in Finder.
This section defines the list of remote actions
ra_id that should be executed when a condition is met. These remote actions must be configured with the label
ra_id as explained in the
ra_id section for
The following are examples of diagnosis blocks. The commented text following
# indicates what has to be customized.
Diagnosis using NQXL queries
topic_name: # change topic_name to reflect the name of the topic version: # enter the version, for example '0.0.1' diagnosis: - query: (select # enter your query) platform: windows remediation: - condition: # field_from_query >= X where X can be string or float remediation_ras: - ra_id: # RA_name
Diagnosis using NXQL queries based on remote actions information
# The header of the topic will inform the user about which remote action(s) # must be configured and scheduled first. topic_name: # change topic_name to reflect the name of the topic version: # enter the version, for example '0.0.1' diagnosis: - query: # (select Remote_Action/Dynamic_Field ... # (where device ... (for example Remote_Action/Execution status # (enum “success”)))) platform: windows remediation: - condition: # string_in_the_dynamic_field_from_query >= X # X can be string or float remediation_ras: - ra_id: # RA_name
When creating queries for retrieving remote action information via NXQL queries, it is recommended to validate the remote action status by adding a
where clause in the query itself in order to check the execution status.
Diagnosis using a remote action
topic_name: # cchange topic_name to reflect the name of the topic version: # enter the version, for example '0.0.1' diagnosis: - diagnosis_ra: ra_id: # RA_name timeout: # [10, 300] - in seconds. Only values in the interval are valid remediation: - condition: # string_in_the_dynamic_field >= X where X can be string or float remediation_ras: - ra_id: # RA_name
No diagnosis (always applies)
topic_name: # change topic_name to reflect the name of the topic version: # enter the version, for example '0.0.1' diagnosis: - query: null # Set query parameter to null for this topic always to match platform: windows remediation: - condition: true # Set to true for this condition always to match remediation_ras: - ra_id: # RA_name
Example of NXQL queries
Implementation of the example described in the Topics high-level content section regarding Outlook Issues :
app_outlook_issues: version: '1.2.0' diagnosis: - query: '(select (#"action:Get Outlook Plugin Crash Details/CrashedPluginList" #"action:Ge t Outlook Plugin Crash Details/Execution status" #"action:Get Outlook Plugin Crash Details/Execution status details" #" action:Get Outlook Plugin Crash Details/Last execution time" #"action:Get Outlook Plugin Crash Details/Target status") (from device (where device (eq device_uid (md5 %1)) (eq #"action:Get O utlook Plugin Crash Details/Execution status" (enum "success")))))' platform: windows remediation: - condition: '"action:Get Outlook Plugin Crash Details/CrashedPluginList" !contains "-"' remediation_ras: - ra_id: set_outlook_plugins
Example using an expression
This example will check OneDrive installation:
app_onedrive_installation: version: '1.0.1' diagnosis: - platform: windows diagnosis_ra: ra_id: get_onedrive_status timeout: 60 remediation: - condition: '"action:Get OneDrive Status/OneDriveStatus" contains "OneDrive is not installed"' remediation_ras: - ra_id: repair_onedrive
Adding or changing topic configurations
Adding a new topic file or modifying an existing one can be done while Nexthink Chatbot Adapter is running. The new topic has to be created in the
It is recommended to copy an existing topic with another name to use it as a template. Then, you must modify the topic name field inside the file.
Below are the steps:
Add the new topic in the
Add the new remote actions used in the topic in the
Create the new cache structure in the local DB.
$ cd /home/nexthink/nexthink-chatbot-adapter-X.X.X/
Refresh the cache data by restarting all the Docker containers. This will create a new DB schema and will force a discovery.
The modified out-of-the-box topic is overwritten when updating to a new version of Chatbot SDK. Copy it as another topic instead. The same approach is applicable for the
remote_actions configuration file.
Comparisons in the topics:
Diagnosis does not allow category queries.
Diagnosis does not allow for a comparison of two fields retrieved from Engines.
Diagnosis does not allow for time comparison.
Comparison on version field values is performed similarly to strings, using
Comparison in diagnosis from remote actions with a
StringListreturn type must be done against the whole string element.