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
  • Installation checklist
  • Common errors
  • Remote actions are not executed
  • Remote actions do not have an investigation
  • Permission denied when starting the services after the installation
  • Configuration changes not applied
  • Invalid default port 8090
  • Invalid subnet or connectivity lost
  • Authentication failed in the HTTP client (browser, Postman…)
  • Service is not working after the installation of a custom certificate
  • REST API: 500 error code
  • REST API: 502 error code
  • REST API: 401 error code
  • REST API: 404 error code
  • REST API: 429 error code
  • REST API: Ingress is returning a Client.Timeout error
  • REST API: Topic diagnosis gives back a set of null fields
  • REST API: Error “NXQL query returned no results” in diagnosis error
  • REST API: Error: “Remote Action '<remote_action_id>' not configured properly”
  • REST API: Chatbot SDK is not retrieving all fields of a remote action
  • Table of Error Codes
  • Logs Handling
  • How to read logs
  • How to increase the log level
  • Recovery procedures
  • Restart the Docker containers
  • Refreshing the local cache manually, the discovery process
  • Updating the list of fields in the local cache
  • Updating the cached fields automatically
  • Edit the cache fields manually
  • Rollback
  • Support script
  • Launching the support script
  • Content of the output file

Was this helpful?

  1. Integrations
  2. Nexthink Chatbot SDK

Troubleshooting

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.

Installation checklist

The following are the steps needed in order to validate that Chatbot SDK has been properly installed and configured, and is running without any problems:

  • Check that all services have started. List Docker running processes to ensure that everything is running:

$ docker ps

If any process is restarting, check the logs following the instructions in the section.

  • Check that the ingress port is open. By default, it is 8090.

Option 1: From the appliance itself:

$ netstat -atn | grep 8090

If this command doesn’t return anything, check if the configured port on /var/nexthink/nexthink-chatbot-adapter/.env is correct. Otherwise, change it and restart the services with:

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

Option 2: From another machine:

Code
>ping 192.168.5.15 
>telnet 192.168.5.15 8090

If the machine or the port is not visible from the outside, check your network and port forwarding configurations.

  • Validate the API request to list the topics without the API key. This can be done either from the appliance itself or from the outside with Postman or Rested browser add-on.

Code
$ curl -k https://localhost:8090/v1/topics 
Invalid API key 

If the result is different, check that the previous steps were done correctly.

  • Validate the API request to retrieve the API key.

$ curl -k https://user:password@localhost:8090/v1/api_key

If this request returns a 404 not found error, then the API key must be set again. If it fails with a 401 unauthorized error, then review the user and password that are being used. Please note that if the user and password contain special characters, they must be URL encoded when using curl.

  • Validate the API request to list the topics.

$ curl -k -H "X-API-key:" https://localhost:8090/v1/topics

If this request fails with a 401 unauthorized error, then review the API key which is being used.

  • Check remote actions execution with Finder.

Connect Finder to Portal using the same credentials which are configured in the chatbot adapter. Trigger a remote action for a device. If triggering remote actions is not enabled, review the user profile configuration.

  • Validate the API request to retrieve the information of a given device.

$ curl -k -H "X-API-key:" https://localhost:8090/v1/device/{device_name}

  • Test the API request to execute a remote action.

$ curl -k -H "X-API-key:" -X POST https://localhost:8090/v1/remote_action/{ra_id}/{device_uid}

  • Check the API request to see the result of a remote action execution.

$ curl -k -H "X-API-key:" https://localhost:8090/v1/remote_action/{ra_id}/{device_uid}

  • Check the API request to retrieve a topic.

$ curl -k -H "X-API-key:" https://localhost:8090/v1/topic/{topic_id}/device/{device_uid}/{platform}

Common errors

Remote actions are not executed

Problem: Remote actions are not being executed and there is a log entry that reads:

[RemoteActionManagerDebug] radispatcher.go:56: Remote action not configured for manual execution

Solution: Configure the remote action in Finder for manual triggering and save it.

Remote actions do not have an investigation

Problem: After installing Chatbot SDK, no investigation can be found in the remote actions that require it.

Solution: Create an investigation that retrieves all the laptops and desktops that run under Windows and assign it to all the required remote actions by dragging it into an appropriate place.

Permission denied when starting the services after the installation

Problem: The following message is printed after Chatbot SDK is installed:

[...] Got permission denied while trying to connect to the Docker daemon socket at unix [...]

Solution: Reboot the computer. The installation process assigns all the necessary permissions to the user but sometimes it is necessary to perform a reboot to use them effectively.

Configuration changes not applied

Problem: Changes do not show in the configurations (environment variables or topics configuration).

Solution: When changing configurations, ensure that one of these procedures is followed:

  • Environment and installation changes (.env file changes)

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 
  • Topics, Engines list or remote action changes (YAML files changes)

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$./scripts/nexthink-chatbot-adapter-create-cached-fields.sh [Only if topics changes] 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

Invalid credentials

Problem: Chatbot is receiving a 401 error code and the following log error is printed:

[Discovery][nxqlclient.go:65]: [401] Your credentials are invalid.

Solution: Check that the Nexthink user and password are correct in the .env file and update if needed. Apply the changes via:

$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

Invalid default port 8090

Problem: While trying to start the services, the user receives the following response from Docker Compose:

[...] Bind for 0.0.0.0:8090 failed: port is already allocated

Solution:

  • Change the CHATBOT_ADAPTER_PORT variable in /var/nexthink/nexthink-chatbotadapter/.env

  • Load the Docker images again.

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh  

Invalid subnet or connectivity lost

Problem: While trying to start the services, Docker Compose chooses a subnet that potentially collides with the one used by the host.

Solution: Stop the containers.

Code
$ cd /var/nexthink/nexthink-chatbot-adapter 
$ docker compose down 

Include the networks section in the docker-compose.yaml file just after version and at the same level as services. Be sure to select a suitable subnet.

Code
version: '3.2' 
  networks:      
 default:  
       driver: bridge       
       ipam:    
          config:  
            - subnet: 10.10.100.0/24 
  services 
  ...

Load the Docker images again:

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

Authentication failed in the HTTP client (browser, Postman…)

Problem: When using a browser or another HTTP client, the client complains that it cannot authenticate or cannot get any answer.

First, ensure that you have already checked that:

  • The API key is valid.

  • The requests work using curl from a terminal in the local machine or from another machine. For example, to retrieve the list of topics:

$ curl -k -H "X-API-key:" https://{hostname}:8090/v1/topics

This can happen because your HTTP client is not allowed to connect to Chatbot SDK. The SDK uses a self-signed SSL certificate (not trusted).

Solution: To connect correctly to Chatbot SDK from an HTTP client, use one of the following options:

  • Option 2: You can change the SSL verification parameters in the HTTP client.

    • For example, in Postman this can be fixed by turning off SSL certificate verification in the General settings.

    • Refer to the documentation of your specific HTTP client to change the SSL certificate validation options.

Service is not working after the installation of a custom certificate

Problem: Service is not responding to any HTTP request, chatbotingress service is restarting continually and logs show an error message:

open /certs/ca_certificates.crt: permission denied

Solution:

  • Check if the format of the certificate and the key are X.509. You may convert your key to the proper format using the following commands:

openssl rsa -in .key -out key.pem -outform PEM

- Restart the docker services

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

REST API: 500 error code

Problem: Chatbot SDK is returning a 500 error code and the logs show a critical error:

configreader_1 ... [CRI][ConfigReader][configreader.go:121]: Config value already exists for [topic_name]

Also, when checking the status of the services, the configreader service reports the status Restarting (1), as follows:

Code
$ docker ps 

configreader "./configreader -log…"   About a minute ago   Restarting (1)
10 seconds ago    nexthink-chatbot-adapter_configreader_1 

The error is generated because there are two topics with the same name.

Solution:

  • Review the topic name inside the files in the /var/nexthink/nexthink-chatbotadapter/config/topics directory. [topic_name] described in the log above is repeated in another file.

  • Restart the services:

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

REST API: 502 error code

Problem: The chatbot is receiving a 502 error code and one of the following messages:

  • Invalid Server Error

  • The Engine returned an error while processing the Remote Action - <error_information>

  • All Engines failed

  • Another type of error

These errors point out a problem after a remote action is dispatched to Portal. In order to fully understand them, review the log as the causes can vary.

Solution:

It is recommended to always configure a databaseUID in the engines.yaml file. This way, the remote actions dispatch targets a specific Engine and it is easier to narrow down the errors.

The following are general descriptions for each of the possible error outputs:

  1. Invalid Server Error: Portal always answers with an error code that was caused by a lack of proper permission, or a failure of another kind.

  2. Engine returned an error while processing the RA - : Portal returned a success code, but the remote action dispatch failed. <error_information>refers to this failure.

  3. All Engines failed: All Engines to which the remote action was dispatched returned a problem. To avoid this, configure databaseUID in the engines.yaml file.

  4. Another kind of error information: Portal returned an error, but the Chatbot SDK API did not identify it as an Invalid Server Error. Please read the logs and the output to obtain more information.

REST API: 401 error code

Problem: The chatbot is receiving a 401 error code with the message Invalid API Key

Solution:

  • Check that the API Key is correctly added in an extended header X-API-key in the HTTP requests sent by the chatbot. Use the following command to retrieve the current API Key:

$ curl -k https://:@localhost:8090/v1/api_key

Nexthink_User is the Portal user configured in /var/nexthink/nexthink_chatbot_adapter/.env

REST API: 404 error code

Problem: The chatbot is receiving a 404 error code with the message Device or Remote Action not found when requesting the status of a remote action or when executing synchronously.

This problem may be originating from the underlying NXQL query requesting the status fails due to the device not being in the local Chatbot SDK cache or due to the remote action not being found.

Solution: Check the name of the remote action in remote_actions.yaml. The name is case-sensitive and should match the name of the remote action in Finder.

REST API: 404 error code

Problem: The chatbot is receiving a 404 error code with the message Device not found when requesting data from an existing device.

This problem may be caused by the device not being in the local Chatbot SDK cache. There could be several reasons for this behavior:

  • The device has not been detected for an extended period of time by Engine.

  • The device is not generating user activity in the way it was expected or the discovery process has failed for some reason.

Solution:

  • Validate whether the discovery process runs successfully for all Engines by checking the logs of the discovery service:

Code
$ cd /var/nexthink/nexthink-chatbot-adapter 
$ docker compose logs discovery 

Check for errors such as:

[engine_10-10-10-1_1672] Discovery failed for this Engine. Information has not been updated due to previous error.

  • Check the query configured in the discovery.yaml file. There are two queries, one of them is commented out.

  • Execute the active NXQL query in the NXQL editor on one of the Engines to check if:

    • the device exists in Engine.

    • the device has sent data to Engine, showing existing rows for that device in the user_activity or executions objects, depending on the active query, in the last USER_ACTIVITY_PERIOD days.

Replace <USER_ACTIVITY_PERIOD> with your configured period in the NXQL Editor. The default value is 30 days.

If the device does not appear in the query, then it is not included in the Chatbot SDK cached database. It was not reporting activity and therefore it cannot be found.

  • Check the execution of the commented query in the NXQL editor. If it returns information about the device then change the configured commented query and restart Chatbot SDK services:

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

REST API: 429 error code

Problem: The chatbot is receiving a 429 error code with the message Throttle limit reached. This is caused by Chatbot SDK reaching the max limit of transactions per second to access either Portal, Engines or the internal cache.

Solution:

  • When receiving this error, the chatbot will ask the user to try the operation later after a few minutes. The limit on the number of transactions can be configured using parameters in /var/nexthink/nexthink_chatbot_adapter/.env

  • A less recommended solution, which is valid only for very specific cases in environments with low load on the Engines or Portal, is to increase those limits by no more than 10% in /var/nexthink/nexthink_chatbot_adapter/.env

Code
MAX_CACHE_REQUESTS_PER_SECOND=500 
MAX_PORTAL_REQUESTS_PER_SECOND=20 
MAX_ENGINE_REQUESTS_PER_SECOND=40

This is not recommended for Engines or Portal under a heavy load.

REST API: Ingress is returning a Client.Timeout error

Problem: Chatbot SDK returns the following error:

Code
chatbotingress_1       | 2019-12-31T05:10:54-05:00 [DEB][Ingress][router.go:32]: Post 
http://remoteactionmanager:8003/v1/remote_action/<remote_action_name>/<remote_action_id>: 
net/http: request canceled (Client.Timeout exceeded while awaiting headers) 

Solution: Check the value which has been assigned to the parameter NXQL_CLIENT_TOPIC_TIMEOUT in the .env file. Generally, it is not necessary to change its default value, however, in this case you might need to set it to a higher value.

REST API: Topic diagnosis gives back a set of null fields

Problem: The JSON retrieved from a topic contains a list of fields that are all null, for example:

Code
"fields": { 
 "action:Get Outlook Plugin Crash Details/CrashedPluginList": null, 
 "action:Get Outlook Plugin Crash Details/Execution status": null, 
 "action:Get Outlook Plugin Crash Details/Execution status details": null, 
 "action:Get Outlook Plugin Crash Details/Last execution time": null, 
 "action:Get Outlook Plugin Crash Details/Last target time": null, 
 "action:Get Outlook Plugin Crash Details/LastCrashedPluginDate": null, 
 "action:Get Outlook Plugin Crash Details/LastCrashedPluginName": null, 
 "action:Get Outlook Plugin Crash Details/MaximumCrashCountPluginName": null, 
 "action:Get Outlook Plugin Crash Details/Number of days since last execution": null,         
 "action:Get Outlook Plugin Crash Details/Target status": null 
    }     

This issue is also printed in the Chatbot SDK log:

[DEB][TopicManager][topicmanager.go:395]: The value for the field action:Get Outlook Plugin Crash Details/CrashedPluginList is NULL. No comparison will be performed.

Solution:

REST API: Error “NXQL query returned no results” in diagnosis error

Problem: The JSON retrieved from a topic contains a diagnosis error with the message “NXQL query returned no results”. For example:

Code
{ 
 "diagnosis_error": { 
 "checked_issue": "(select name (from device (with execution_error 
                          (where device (eq device_uid (md5 %1))) 
                          (where application (eq name (pattern \"*outlook*\"))) 
                          (compute number_of_application_crashes number_of_application_not_responding_events) 
                          (between now-7d now))))", 
 "errors": [ 
              { 
 "code": 2, 
 "message": "Error executing NXQL query: [404]The NXQL query returned no results. 
                  Query: (select name (from device (with execution_error 
                          (where device (eq device_uid (md5 %1))) 
                          (where application (eq name (pattern \"*outlook*\"))) 
                          (compute number_of_application_crashes number_of_application_not_responding_events) 
                          (between now-7d now))))" 
              } 
        ] 
    } 
} 

The issue is also printed in the Chatbot SDK log:

Code
[ERR][TopicManager][topicmanager.go:332]: Error executing NXQL query: 
[404]The NXQL query returned no results. Query: (select name (from device 
(with execution_error (where device (eq device_uid (md5 %!)(MISSING))) 
(where application (eq name (pattern "*outlook*"))) 
(compute number_of_application_crashes number_of_application_not_responding_events) 
(between now-7d now)))) 

Solution:

  • Check if the device has had any recent user activity using Nexthink Finder. If not, it is normal not to receive any information about the device.

  • Validate that the NXQL query syntax is correct.

    • Check the where clause in case there is a non-existing condition.

    • Check if there are any other typographical errors.

REST API: Error: “Remote Action '<remote_action_id>' not configured properly”

Problem: The JSON retrieved from a topic contains a diagnosis_error and the message: Error: Remote Action ... not configured, for example:

Code
[{"code":7,"message":"Error while preparing diagnosis. Error: Remote Action 
'<remote_action_id>' not configured properly. Please check that it exists in 
your configuration files."}] 

This message indicates that Chatbot SDK is trying a diagnosis using a remote action that does not exist in /var/nexthink/nexthink-chatbot-adapter/config/topics/remote_actions.yaml. To fix the problem, add it to the file and restart the Docker services.

  • If the topic contains only one diagnosis, Chatbot SDK will return a 500 status code.

  • If by any chance other diagnoses are evaluated and the result is successful, a 200 status code along with the usual response message structure will be generated.

REST API: Chatbot SDK is not retrieving all fields of a remote action

Problem: Remote actions fields are retrieved even though they are included in the configuration files.

Solution: Check that you are always using the latest version of all remote actions.

Table of Error Codes

Chatbot SDK logs an error message with a specific code. The following are the error codes that you may encounter:

Code
Type

0

Remote Action Client error

1

Remote Action Execution error

2

NXQL Client error

3

NXQL Query format error

4

Remediation Condition error

5

NXQL Fields error

6

Remediation Comparison error

7

Remote Action Configuration error

Logs Handling

How to read logs

Logs are written in the standard output of each microservice. You can retrieve all of them as follows:

Code
$ cd /var/nexthink/nexthink-chatbot-adapter 
$ docker compose logs  

How to increase the log level

The log level is set in Chatbot SDK .env file with the variable LOG_LEVEL

$ vi /var/nexthink/nexthink-chatbot-adapter/.env

The default value is 4 (Info). The valid values are:

  • 1 (Critical)

  • 2 (Error)

  • 3 (Warning)

  • 4 (Info)

  • 5 (Debug)

  • 6 (Trace)

To take the new value, you need to restart the affected microservices by typing:

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

Recovery procedures

Restart the Docker containers

To list the status of the Docker containers:

$ docker ps --all

If any containers are down, restart them. To restart the Docker containers:

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

Refreshing the local cache manually, the discovery process

The cache is refreshed automatically with a frequency defined in the file /var/nexthink/nexthinkchatbot-adapter/.env and with the variable CHATBOT_CACHE_REFRESH

There are cases where it might be required to force the cache refresh manually, for example, when the waiting time to refresh the cache automatically is too long as indicated by some tests. This can be caused by:

  • New Engines being added into the system, in /var/nexthink/nexthink-chatbotadapter/config/engines.yaml

  • Execution of new remote actions

  • Addition of new devices

This requires restarting the discovery microservice as follows:

Code
$ cd /var/nexthink/nexthink-chatbot-adapter 
$ docker compose restart discovery 

Updating the list of fields in the local cache

You may need to update fields in the cache in order to gain performance or to fix certain configuration issues. The information stored in the cache is listed in the /var/nexthink/nexthink-chatbotadapter/config/cached_fields.yaml

This file is automatically generated during the installation and upgrade process based on the NXQL queries found in the selected topic files.

Updating the cached fields automatically

The fields are updated automatically by default every time there is an installation or upgrade. The content of the cached fields is created in the config/cached_fields.yaml file programmatically.

You have to manually launch the script when changes to the configuration of the topics are made, the topic files are modified or new topics are added.

To regenerate the cache fields follow these steps:

  • Start SSH-client, connect to VM and login with the Nexthink user.

  • Go to the directory where the installation zip was extracted, usually in the user’s home directory.

  • Add execution permission to the script, if needed:

$ chmod +x scripts/nexthink-chatbot-adapter-create-cached-fields.sh

  • Execute the script:

$ ./scripts/nexthink-chatbot-adapter-create-cached-fields.sh

  • Restart the running containers in order to apply the changes:

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

Edit the cache fields manually

The list of fields to be cached can be customized. Since the config/cached_fields.yaml file is automatically created, it is recommended to perform the following operation only for troubleshooting reasons:

  • Start SSH-client, connect to VM and login with the Nexthink user.

  • Go to Chatbot SDK installation directory:

$ cd /var/nexthink/nexthink_chatbot_adapter/config

  • Open and edit the cached fields file:

$ vi cached_fields.yaml

Each line represents a cache field that is stored for every device during the discovery process.

  • Restart the running containers in order to apply the changes:

Code
$ cd /home/nexthink/nexthink-chatbot-adapter-1.1.0 
$ ./scripts/nexthink-chatbot-adapter-restart.sh 

Rollback

While executing an update, it is possible that the process is unable to finish successfully. If this is the case, Chatbot SDK will perform a rollback by itself. Despite the error messages being shown in the logs and command line, everything will be restored to its previous state automatically.

Support script

In order to retrieve useful information for troubleshooting purposes, a support script is provided along with the installation.

Launching the support script

  • Go to the directory where the installation zip was extracted, normally in the user’s home directory.

  • Add execution permissions to the script in case they are needed:

$ chmod +x scripts/nexthink-chatbot-adapter-support-script.sh

  • Execute the script. In order to retrieve all the necessary information, Chatbot SDK should be up and running. If it is not running, important information about the status of the containers will not be retrieved.

$ ./scripts/nexthink-chatbot-adapter-support-script.sh

  • The script returns to the console location of the compressed file with the results, which will be in the /tmp directory, with the name nexthink-chatbot-adapter-support, and suffixed with a timestamp. For example, for some information generated on March 4th, 2020, at 15:16, the path would be /tmp/nexthink-chatbot-adapter-support-2020-03-04-15-16-47.tar.gz

Content of the output file

The compressed output file consists of the following elements:

  • config (folder): copy of the original user configuration directory which contains:

    • topics (folder): a folder containing topics and remote actions .yaml files

    • .yaml configuration files: cached_fields.yaml, discovery.yaml and engines.yaml

  • docker_inspect (folder): contains a .txt file per container with the docker_inspect information, for example, docker-inspect-nexthink-chatbot-adapter_chatbotingress_1.txt

  • docker_logs (folder): contains the docker logs files, both, those created by the restart script and a log file created by the support script. The file content is sorted by ascending timestamp.

  • .env: copy of the .env configuration file without any password

  • general_information.txt: text file which contains the following:

    • The number of installed release versions

    • Permissions for the /config directory and /topics contained within it

    • Docker image information: REPOSITORY, TAG, IMAGE ID, CREATED and SIZE

    • Docker container information: CONTAINER ID, IMAGE, COMMAND, CREATED, STATUS, PORTS and NAMES

    • Docker stats: CONTAINER ID, NAME, CPU %, MEM USAGE/LIMIT, MEM %, NET I/O, BLOCK I/O and PIDS

  • Folders with the result of the install, update, restart and uninstall processes

Refer to the section if you encounter an error.

Refer to the section if you encounter an error.

Refer to the section if you encounter an error.

Refer to the section if you encounter an error.

The API key needs to be regenerated in order to change the credentials and it has to be shared with the chatbot. Refer to the documentation.

Option 1: Change the self-signed certificate to a trusted SSL certificate by following the installation guide.

Check certificate file names, ca_certificates.crt for the certificate file and key.pem for the key. Ensure proper file permissions: 755 for the directory and 644 for the files, as described in the guide.

If required, generate a new API Key and share it with the chatbot as explained in the guide.

The Web API port may not be the proper one. Verify that all the information in the engines.yaml file is correct and fix it accordingly. Refer to the section on how to restart the services properly after fixes have been applied.

Check with your Nexthink operator if the remote action shown in the example above Get Outlook Plugin Crash Details is scheduled to be automatically launched and has been executed, as described in the guide.

What the rollback reverts, depends on the updating stage in which the error occurred. Refer to the documentation.

Authentication
Authentication
Installation and configuration
Updating to newer version
Nexthink Support Portal
Common errors
Common errors
Common errors
Common errors
Common errors
Configuration changes not applied
Custom certificate
Custom certificate installation
Enable manual execution for a Remote Action