LogoLogo
LearnDocumentationSupportCommunity
Version 6.30
Version 6.30
  • Welcome
  • Nexthink V6
  • Overview
    • Software components
    • Collector
    • Finder
    • Engine
    • Portal
    • Nexthink Library
    • Digital Experience Score
  • Installation and configuration
    • Planning your installation
      • Overview of the installation process
      • Hardware requirements
      • Connectivity requirements
      • Software requirements
      • Reference architectures
    • Installing Portal and Engine Appliances
      • Installing the Appliance
      • Installing the Appliance on Azure
      • Installing the Appliance on AWS
      • Installing the Appliance on OTC
      • Managing Appliance accounts
      • Setting the names of the Portal
      • Setting the names of the Engines
      • Specifying your internal networks and domains
      • Federating your Appliances
      • STIG compliance in Web Console
      • Connecting the Portal to the Engines
      • Configuring session performance storage
      • Configuring device performance storage
      • Setting up a software license
      • Sending email notifications from the Appliance
      • Allocating resources for the Portal
    • Installing the Collector
      • Installing the Collector on Windows
      • Installing the Collector on macOS
      • Installing the Collector for a Proof of Value
      • Assigning Collectors to Engines
      • Assignment of roaming Collectors
      • Collector MSI parameters reference table
      • Nxtcfg - Collector configuration tool
      • Inspecting the connection status of the Collector
      • Querying the status of the TCP connection of the Collector
      • Reporting the URL of HTTP web requests
      • Auditing logon events
      • Viewing user interactions in virtualized and embedded environments
      • Engage notifications on macOS
      • Configuring Collector level anonymization
    • Collector remote connectivity
      • Redirecting and anonymizing Collector traffic
      • Redirecting the Collector TCP channel
      • Support for DirectAccess
      • Windows Collector proxy support
      • Mac Collector proxy support
    • Installing the Event Connector
      • Installing the Event Connector on Linux
    • Installing the Finder
      • Installing the Finder on Windows
      • Enabling Cross-Engine Finder features
      • Expanding the time frame of investigations in the Finder
      • Enabling Finder access to the Library
      • Finder proxy support
    • Updating from V6.x
      • Updating the Appliance
      • Content centralization when updating the Appliance
      • Updating the Collector
      • Viewing Collector deprecated fields
      • Updating the Finder
    • Security and user account management
      • Importing and replacing certificates
      • Hierarchizing your infrastructure
      • Adding users
      • Enabling SAML authentication of users
      • Just-In-Time provisioning of user accounts
      • Enabling Windows authentication of users
      • Multi-factor authentication for local accounts overview
      • Provisioning user accounts from Active Directory
      • Establishing a privacy policy
      • Disabling local accounts for interactive users
      • Setting the complexity and minimum length of passwords for local accounts
      • Protecting local accounts against brute force attacks
      • Preventing password saving in the Finder
      • Controlling session timeouts in the Portal
      • Security settings in the Appliance
      • Setting the Do Not Disturb periods between campaigns
    • Data retrieval and storage
      • Data retention
      • Increasing the maximum number of metrics
      • Establishing a data retention policy in the Engine
      • Storing Engine data in a secondary disk drive
      • Importing data from Microsoft Active Directory
      • Setting the locale in the Portal
      • Changing the Time Zone of the Portal
      • Time Zones and data collection
      • Changing the data collection time of the Portal
      • Nightly task schedules timetable
      • Changing the thresholds of High CPU warnings
      • Automatic restart of unresponsive Engine
    • Maintenance operations
      • Logging in to the CLI
      • Special operation modes for the Engine and the Portal
      • Changing the default ports in the Appliance
      • Centralized Management of Appliances and Engines
      • Monitoring the performance of the Appliance
      • Resizing partitions in Appliance
      • Configuring the system log
      • Examining the logs in the Portal
      • GDPR - Retrieving or anonymizing personal data
      • Finding out unlicensed devices
      • Removing devices
      • Installing third-party software in the Appliance
      • Installing VMware Tools in the Appliance
      • Operational data sent to Nexthink
      • Sending additional data to Support
    • Disaster recovery
      • Planning for disaster recovery
      • Web Console backup and restore
      • Engine backup and restore
      • Portal backup and restore
      • Rule-based assignment backup and restore
      • License backup and restore
      • PKI backup and restore
    • Branding
      • Branding the Portal
      • Branding of campaigns
  • User manual
    • Getting started
      • Logging in to the Finder
      • Logging in to the Portal
      • Enabling STIG in Webconsole
    • Querying the system
      • Searching the subject of interest
      • Executing an investigation
      • Creating an investigation
      • Editing the options of an investigation
      • Combining logical conditions in investigations
      • Navigating through the results of an investigation
      • Properties of users and devices
    • Visualizing system activity in the Finder
      • Getting a quick overview
      • Graphically observing the activity of users and devices
      • Observing service performance
      • Viewing network connections
      • Viewing web requests
      • Viewing executions
    • Monitoring IT custom metrics
      • Creating a metric
      • Examples of metrics
      • Session performance
      • Device performance
      • Following the evolution of a metric
      • Finding the visuals of a metric
    • Monitoring IT services
      • Analyzing service quality
      • Creating a service
      • Following the evolution of a service
      • Specifying URL paths of web-based services
    • Engaging with the end user
      • Getting feedback from the end users
      • Types of campaigns
      • Creating a campaign
      • Editing a campaign
      • Types of questions
      • Controlling the flow of questions
      • Translating a campaign
      • Triggering a campaign manually
      • Limiting the reception rate of campaigns
      • Scrutinizing the results of a campaign
      • Continuously measuring the satisfaction of employees
    • Rating devices and users with scores
      • Computing scores
      • Creating a score
      • Checking and comparing ratings
      • Computing potential savings
      • Score XML Reference
      • Documenting scores
    • Remotely acting on devices
      • Scenarios for remote actions
      • Creating a remote action
      • Executing remote actions
      • Triggering a remote action manually
      • Writing scripts for remote actions on Windows
      • Writing scripts for remote actions on Mac
      • Example of self-healing scenario
      • Example of self-help scenario
      • Application control and remote actions
    • Organizing objects with categories
      • Classifying objects of the same type
      • Creating categories and keywords
      • Tagging objects manually
      • Tagging objects automatically
      • Importing tags from text files
    • Getting notified by the system
      • Receiving Engage campaigns
      • Receiving email digests
      • Receiving alerts
      • Creating a service-based alert
      • Creating an investigation-based alert
    • Building web-based dashboards
      • Introducing dashboards in the Portal
      • Creating a dashboard
      • Examining metrics in depth
      • Documenting dashboards
      • Assessing license use
      • Computing dashboard data
      • Reusing dashboard content
    • Importing and exporting authored content
      • Methods for reusing authored content
      • Manually sharing Finder content
      • Importing a content pack
      • Conflict resolution
      • Exporting a content pack
  • Library packs
    • Compliance
      • Device Compliance
    • Configuration Manuals
      • Overview (Configuration Manuals)
      • Installing A New Version Of A Library Pack
    • Digital Employee Score (DEX score)
      • DEX Score Installation And Configuration
      • Detailed Library Pack Changelog
    • Device management
      • Reduce logon duration
      • Group Policy Management
      • Hardware Asset Renewal
      • Hardware Asset Renewal Advanced
      • Application Auto-Start Impact
    • Remote Employee Experience
      • Remote Worker Experience
      • Home Networking
      • Change Log And Upgrade Process
      • Remote Worker Vs Office Worker Device Category
      • Remote Worker Insights
      • DEX V2 Upgrade Of Remote Worker
    • Persona Insight
      • Persona Insight - Overview
      • Persona Insight - Library Pack
      • Persona Insight - Score Only Pack
      • Persona Insight - Without Campaign pack
      • Persona Insight - Getting Started and Upgrade Procedure
      • Persona Insight - Configuration Guide
      • Persona Insight - Troubleshooting - Multiple devices on multiple engines
      • Persona Insight - Reference Guide
      • Persona Insight - Example Pack
      • Persona Insight - Device Sizing
        • Persona Insight - Device Sizing Overview
        • Persona Insight - Device Sizing Configuration
      • Persona Insight - Application Sizing
        • Persona Insight - Application Sizing Overview
        • Persona Insight - Application Sizing Configuration
      • Legacy Persona documentation
        • Persona Insight - Library Pack (V.1.0.0.0)
        • Persona Insight - Base Pack
        • Persona Insight - Base Pack Advanced
        • Persona Insight - Customization Guide (V1.0.0.0)
        • Persona Insight - Configuration Guide (V1.0.0.0)
        • Persona Insight - Reference Guide (V1.0.0.0)
    • GSuite
      • GSuite: Health
      • GSuite: Services
      • GSuite: Sentiment
      • GSuite: Advanced Health
    • Support
      • Support: Level 1
    • Shadow IT
      • Shadow IT
    • Malware Protection
      • Malware Protection
    • Office 365 Health
      • Office 365 Health: Overview
      • Office 365 Health: Services
    • Office 365 OneDrive
      • OneDrive Summary
      • OneDrive Operations
      • OneDrive Advanced Health
      • OneDrive Migration
      • OneDrive Sentiment
      • OneDrive Management
      • OneDrive Advanced Operations
    • Office 365 Teams
      • Teams Overall Configuration
      • Teams - Migration
      • Teams - Health
      • Teams - Advanced Health
      • Teams - Adoption
    • Microsoft 365 Apps
      • Microsoft 365 Apps - Operate
    • Employee Self Service
      • Overview
      • Configuration
      • Usage
    • Onboarding Experience Management
      • OEM - Overview
      • OEM - Configuration
    • Office 365 Outlook
      • Outlook Troubleshooting
    • Virtualization
      • Virtualization: Operate
      • Virtualization: AVD - Advanced
      • Virtualization: Citrix Advanced
      • Virtualization: Project
      • Virtualization: Troubleshooting
        • Virtualization: Troubleshooting: Configuration
    • Windows
      • Win10: Configuration
      • Win10: Migration
      • Win10: Feature Update
      • Win10: Quality Update
      • Windows Defender Management
      • Administrators Management
    • Windows 11
      • Windows 11 - Readiness
      • Windows 11 - Migration Pilot
      • Windows 11 - Migration
      • Windows 11 - Operate
    • Webex
      • Webex Operate
    • Zoom
      • Zoom Operate
    • Remote Actions
      • Get Performance Monitor Data
      • Skype For Business
      • Restart Device
      • Upload Logs to S3 using PreSigned URLs
    • Software Asset Optimization
    • Collaboration Optimization
      • Collaboration Optimization - Solution Overview
      • Collaboration Optimization - Configuration
      • Collaboration Optimization - Usage / Troubleshooting
    • Systems Management
      • Manage Configuration Drift
      • MS ConfigMgr - Client Health
        • MS ConfigMgr - Client Health - Summary
        • MS ConfigMgr - Client Health - Configuration Guide
      • Intune
        • Intune - Health
          • Intune - Health - Summary
          • Intune - Health - Configuration Guide
    • Return to the office
      • Return to the office - Planning
      • Return to the office - Readiness
    • Green IT
      • Green IT - Overview
      • Green IT - Configuration Guide
    • Hybrid Working
      • Hybrid Working Experience
      • Hybrid Working Experience - Installation and upgrade procedure
  • Integrations
    • Nexthink ServiceNow Service Graph Connector
      • Overview
        • Roles and Permissions
        • Modules
      • Installation and Configuration Guide
        • Pre-requisites
          • Configure Identification Rules
          • Import and setup the CMDB categories in Finder
        • Setup
          • Configure the connection
          • Configure import properties
          • Configure additional engines
          • Set up scheduled import jobs
      • Data transformation and mapping by default
      • How to customize the behaviour of the Connector
      • FAQ
        • Why ServiceNow Service Graph Connector?
        • What about Nexthink CMDB Connector?
        • Why is the name the primary key for the devices?
      • Troubleshooting
        • IRE identification issues
          • [No Choice found in the sys_choice table for the target table](integrations/nexthink-servicenow-service-graph-connector/troubleshooting/ire-identification-issues/ no-choice-found-in-the-sys_choice-table-for-the-target-table.md)
          • Identification rules not created
          • Discovery_source choice not created
        • Timeout Errors
          • ECCResponseTimeoutException
          • HTTP 0 error
        • MID server issues
          • java.lang.NullPointerException
          • MID Server memory issues
          • Not trusted certificates in Quebec release
        • Configure credentials issues
          • [Not allowing update of property authentication_choice](integrations/nexthink-servicenow-service-graph-connector/troubleshooting/configure-credentials-issues/ not-allowing-update-of-property-authentication_choice.md)
          • Invalid username/password combo (HTTP 401/403)
        • Configure Engines Issues
          • [The client secret supplied for a confidential client is invalid](integrations/nexthink-servicenow-service-graph-connector/troubleshooting/configure-engines-issues/ the-client-secret-supplied-for-a-confidential-client-is-invalid.md)
        • No Cis imported and no errors found in the log
    • Nexthink ServiceNow Incident Management Connector (IMC)
      • Installation and configuration guide (IMC)
      • Troubleshooting Guide (IMC)
      • Domain separation installation (IMC)
    • Nexthink ServiceNow CMDB Connectors
      • Installation and Configuration Guide
      • Troubleshooting Guide
      • Field transformation and normalisation examples
    • Nexthink Event Connector
      • High level overview
      • Installation and Configuration Guide
      • Troubleshooting guide
      • RPM installation
      • Splunk specific documentation
        • Upgrading from Splunk Connector to Event Connector
        • Splunk add-on installation and usage
    • Nexthink Chatbot SDK
      • Introduction and concepts
      • Installation, configuration and update guide
        • Installation and configuration
        • Update to newer version
        • Uninstallation
        • Authentication
        • Topics configuration
        • Remote action configuration
        • Advanced configuration
        • Additional resources and references
      • Dimensioning guide
      • Troubleshooting
      • Technical solution description
      • Downloads and release notes
  • Glossary and references
    • Search and information display
      • Search in Finder
      • Keyboard shortcuts for column display selection
      • Campaign display compatibility
      • Real-time and consolidated service data
      • Service errors and warnings
      • Errors and warnings for devices and executions
      • Types of widgets
      • Widget compute state in charts
      • Errors in the execution of remote actions
      • Top results of Cross-Engine investigations
      • Engine data history
    • Tooltips in the user and device views
      • Alerts tooltips
      • Warnings tooltips
      • Errors tooltips
      • Activity tooltips
      • Services tooltips
    • Database information and organization
      • Maximum supported values
      • Local and shared content
      • Device Identification
      • Local IP address of devices
      • Timestamping of events
      • Boot and logon duration
      • Application startup duration
      • Application not responding events
      • Memory and CPU usage
      • Status of TCP connections
      • Status of UDP connections
      • Network and port scan conditions
      • Binary paths
      • Maximum number of Binaries
      • Package Executable Mapping
      • Metro apps
      • Investigation with packages
      • Portal aggregation and grouping
      • Focus time metric
    • Security
      • Access rights and permissions
      • Active Directory authentication
      • Canonical domain names for Windows authentication
      • System alerts
      • Audit trail
      • Appliance hardening
      • STIG hardening
      • FIPS 140-2 compliance
      • Security bulletins
        • Is Nexthink affected by Okta breach
        • Is Nexthink affected by SolarWinds breach
        • Nexthink and Log4j - Security bulletin
        • CVE-2022-22965 - Security Vulnerability Spring4shell - Spring Framework
        • Version 6.22.2.10: Security Vulnerability Maintenance Release
        • The Collector V6.27.X Release – Security Bulletin
    • References
      • Components of the Collector
      • Server support
      • Compatibility mode
    • Glossary
      • Activity
      • Alert
      • Application
      • Binary
      • Campaign
      • Category
      • Connection
      • Dashboard
      • Destination
      • Device
      • Domain
      • Entity
      • Event
      • Executable
      • Execution
      • Focus time
      • Hierarchy
      • Installation
      • Investigation
      • Keyword
      • Metric
      • Module
      • Object
      • Package
      • Platform
      • Port
      • Printer
      • Score
      • Service
      • Session
      • System boot
      • User
      • User logon
      • Web request
      • Widget
  • API and integrations
    • Integrating with Nexthink
      • Event Connector
      • Getting data through the NXQL API
      • Bidirectional integration with the Finder
      • Count metrics API
      • Software metering API
      • Services API
      • List Engines API
      • GetSID API
      • Triggering campaigns via their API
      • Triggering remote actions via their API
      • Audit trail API
      • Integrating investigation-based alerts
      • Downloads
    • NXQL API
      • Introducing the NXQL API
      • NXQL Tutorial
      • NXQL language definition
      • NXQL Data Model
    • Integrations
      • Excel integration with NXQL
      • Power BI
      • Azure Data Lake Storage Gen2
      • Splunk Event Connector
    • ServiceNow
      • CMDB Connector
      • Incident Management Connector
      • Event Management

© Nexthink

  • Privacy policy
  • Responsible Disclosure Policy
On this page
  • Overview
  • Out-of-the-box topics
  • Topic high-level content
  • Topic syntax
  • Topics configuration elements
  • version
  • diagnosis
  • diagnosis_ra
  • platform
  • Allowed comparison operators:
  • Diagnosis types
  • Diagnosis using NQXL queries
  • Diagnosis using NXQL queries based on remote actions information
  • Diagnosis using a remote action
  • No diagnosis (always applies)
  • Examples
  • Example of NXQL queries
  • Example using an expression
  • Adding or changing topic configurations
  • Limitations

Was this helpful?

  1. Integrations
  2. Nexthink Chatbot SDK
  3. Installation, configuration and update guide

Topics configuration

Last updated 8 months ago

Was this helpful?

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

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.

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.

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

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 

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

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

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.

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

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

NXQL is one of two ways to diagnose an employee device. The NXQL syntax details can be found in the .

Refer to the documentation for more information.

The types of the output fields in remote actions are described in the and available in Finder.

Implementation of the example described in the section regarding Outlook Issues :

Nexthink Support Portal
REST API
Creating a remote action
YAML website
.
online documentation
Remote action configuration
Library documentation
Topics high-level content