.png)
Topics configuration
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.
Overview
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 PCSlow or 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.
Out-of-the-box topics
The following list is the catalog of topics provided with Chatbot SDK and available in the /var/nexthink/nexthink-chatbot-adapter/config/topics directory.
Use case | Topic Name | Description |
Outlook issues | app_outlook_issues.yaml | Detection of most common Outlook issues (outdated version, offline, etc.) and their remediation |
PC slow issues | pc_slow.yaml | Detection of most common issues that slow down a device (most consuming start-up apps, GPO consumption, outdated versions, etc.) and their remediation |
Printing issues | print_issues.yaml | Allows for the cleaning of the print spooler |
OneDrive issues | app_onedrive_issues.yaml | Detection of most common OneDrive issues (not running, not properly installed, etc.) and their remediation |
Install OneDrive | app_onedrive_installation.yaml | Installation of OneDrive if not installed |
PC health | l1_device_checklist.yaml | Scores based on L1 checklist (disk space, antivirus definition, memory, CPU, etc.) |
Device bad health | device_bad_health.yaml | Detection of device’s bad health (drive usage, most consuming start-up apps or battery health) and their remediation |
Skype for Business health | app_sfb_issues.yaml | 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:
A
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.
Example:
OutlookIssues
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
Topic syntax
The topic files can be found in the config/topics directory inside the Chatbot SDK location, /var/nexthink/nexthink-chatbot-adapter/config/topics.
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 Header content
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 #
topic_name
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 config/topics directory.
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 app_outlook_issues.
version
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.
diagnosis
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.
query
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 device_uid.
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)))))' Multi-line example:
my_topic:
version: '1.0.0'
diagnosis:
- query: '(select …
(from device
(where device (eq device_uid (md5 %1)))))' diagnosis_ra
Executing a remote action is another way of performing a diagnosis, its content is a ra_id.
ra_id
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.
timeout:
This is the time in seconds that Chatbot SDK waits for a remote action to return a response before throwing an error.
platform
This is a platform that is compatible with the diagnosis. The possible values are windows, mac_os or windows,mac_os, which identifies a Windows only, MacOS only or Windows and MacOS valid diagnosis respectively.
remediation
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.
condition
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.
Example:
- 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
system_drive_usageandtotal_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_startupAllowed comparison operators:
Type | Operator | Description |
|---|---|---|
String | == | Compare content of two strings for equality |
!= | Compare content of two strings for inequality | |
contains | Verifies if a given substring is within the string | |
!contains | Verifies if a given substring is not within the string | |
Numeric | < | Lower than |
<= | Lower than or equal to | |
> | Greater than | |
== | Equal to | |
!= | Not equal to | |
String lists | contains | 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:
|
Always matching | true | 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.
remediation_ras
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 diagnosis_ra.
Diagnosis types
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_nameNo 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 Examples
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 /var/nexthink/nexthink-chatbotadapter/config/topics/ folder.
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
/var/nexthink/nexthink-chatbot-adapter/config/topics/folder.Add the new remote actions used in the topic in the
/var/nexthink/nexthink-chatbotadapter/config/topics/remote_actions.yaml.Create the new cache structure in the local DB.
$ cd /home/nexthink/nexthink-chatbot-adapter-X.X.X/
$ ./scripts/nexthink-chatbot-adapter-create-cached-fields.sh
Refresh the cache data by restarting all the Docker containers. This will create a new DB schema and will force a discovery.
$ ./scripts/nexthink-chatbot-adapter-restart.sh
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.
Limitations
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
containsand!containsoperators.Comparison in diagnosis from remote actions with a
StringListreturn type must be done against the whole string element.