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 on YAML website.

Topics configuration elements

A topic configuration is structured as follows:

Code

--- 
# 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:

Code

my_topic:   
  version: '1.0.0' 
  diagnosis: 
    - query: '(select … (from device (where device (eq device_uid (md5 %1)))))' 

Multi-line example:

Code

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

Code

--- 
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:

Code

- 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_usage and total_drive_usage for a specific device.

• The first condition compares the value of system_drive_usage with 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_usage with 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:

Code

- 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:

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: Asterisk (*): represents any number or characters Question mark (?) - represents a single character
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

Code

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

Code

# 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

Code

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)

Code

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 :

Code

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:

Code

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 contains and !contains operators.

• Comparison in diagnosis from remote actions with a StringList return type must be done against the whole string element.