Installation and configuration

This document provides comprehensive information about the introduction and concepts around the 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.

Installation requirements

Hardware requirements

• A separated dedicated appliance with Oracle Linux 8 is required for the deployment.

  • Do not run any Engine or Portal on the same server.

  • For dimensioning details, please check Dimensioning guide.

• The server must have access to the Internet to download required libraries during the installation.

• The Oracle Linux 8 server must have Docker version 27.2.0 installed. Otherwise, these will be automatically downloaded from the Internet during the installation process.

• There must be a dedicated nexthink user with sudo privileges with home /home/nexthink in the appliance. If the nexthink user doesn’t exist, create one.

Nexthink pre-requisites

• Nexthink 6.30 or higher

• Nexthink Engines with licenses for Integrate, Act and Engage modules

• Local user in Nexthink Portal with a profile that allows for Web API access and remote action execution For more details on how to configure this in Finder, go to Nexthink local user configuration in Portal and configure the profile section.

  • We recommend creating a new user in Portal for Chatbot SDK integration. The information is required during the installation process.

• The necessary remote actions are installed and configured in Engines.

  • If you want to use the out-of-the-box catalog, install the Chatbot Content Pack, available in Nexthink Library.

  • Remote actions must be configured as explained in the remote actions settings section.

  • Installation and configuration of remote actions is necessary before Chatbot SDK is installed.

Installation Steps

You will have to write Docker commands during the installation process. For more information, refer to Basic Docker commands.

Update

If you are using a regular Oracle Linux 8 instead of a Nexthink appliance, please ensure it is up to date by running:

$ sudo yum install -y yum-utils unzip

It may require sudo permissions.

Download

Download the file nexthink-chatbot-adapter-X.X.X.zip, save it on the Linux appliance at the /home/nexthink directory and decompress it.

$ cd /home/nexthink

$ unzip nexthink-chatbot-adapter-X.X.X.zip

$ cd nexthink-chatbot-adapter-X.X.X/

If needed, add the Nexthink user execution permission for the scripts.

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

Execute the script

Execute the installation script and pass the tgz path you want to install as a parameter.

To avoid file permission problems, it is recommended to execute the installation with the same Nexthink user that is going to be used to execute Docker commands.

If you do not have a separated file with the list of Engines:

$ ./scripts/nexthink-chatbot-adapter-install.sh ./nexthink-chatbot-adapter-X.X.X.tgz

For the Engine list created in a separated Engine YAML configuration file, use the following command. Please refer to Modifying the list of Engines for more details:

$ ./scripts/nexthink-chatbot-adapter-install.sh -c ~/my_engines.yaml ./nexthinkchatbot-adapter-X.X.X.tgz

The installation script is going to check if your environment meets the installation requirements and check the tgz file. It creates the installation directory at /var/nexthink/nexthink-chatbotadapter and decompresses the tgz file into the installation directory.

For those steps that need to be executed with sudo, the user password may be required during the installation process.

During the installation process, you will be asked to include certain configurations via a prompt.

Configure the environment variables

Portal and chatbot ingress network configuration including users and passwords are required as described in the following steps.

The script will prompt for the following values:

PORTAL_HOST: FQDN or IP of your Portal host

NEXTHINK_USER: Finder or Portal user described in the Installation requirements section

NEXTHINK_PASS: Finder or Portal user password

CHATBOT_ADAPTER_PORT: By default, the external TCP port for incoming connections to Chatbot SDK is 8090

PROXY_URL (optional): FQDN or IP of the proxy, including the protocol http://or https://. Empty for no proxy configuration.

PROXY_USER (optional): The proxy user if basic authentication is used. Empty if no proxy configuration or no authentication is required.

PROXY_PASSWORD (optional): The proxy password if basic authentication is used. Empty if no proxy configuration or no authentication is required.

These values will be stored in a file located in the installation directory: /var/nexthink/nexthink-chatbot-adapter/.env

Optional: there are other advanced variables that have default values and are not required to be modified for the default configuration. If needed, they can be changed manually later by editing the /var/nexthink/nexthink-chatbot-adapter/.env file. For more details, please check the Advanced configuration page.

Configure Nexthink Engines

The script asks for confirmation in case you want to automatically load the Engine configuration values from Portal, which was configured in the previous step.

Please note that the Portal API used to retrieve Engine information does not provide the Web API ports. They are set by the script with the following default values: 1671 for on-premise and 443 for Cloud deployments. If other ports differ from the default ones for the Web API, you need to manually modify the resulting engines.yaml file to include the correct ports. In order to apply these manual changes, the Docker containers need to be restarted. To do so, navigate to the folder where the original zip was decompressed and execute the restart script:

$ ./scripts/nexthink-chatbot-adapter-restart.sh

If you choose not to load any configuration from Portal you may enter the Engine configuration manually. You can enter as many Engines as needed.

Engine Address: FQDN or IP of Engine host

Engine Port: Engine Web API port. The default value is 1671 for on-premise deployments and 443 for Cloud deployments. You may need to modify these values if you are not using the default ports.

Engine Database UID: This value can be taken from the Portal API or it can be left blank if it is unknown. Please refer to the Advanced configuration section for more details.

Engine Timezone: Engine timezone as it appears in TZ database, for example, Europe/Madrid.

Please note that the timezone is case-sensitive and should be typed exactly as it appears in the link.

This information will be stored in the file located in the directory /var/nexthink/nexthinkchatbot-adapter/config/engines.yaml. The file will be populated automatically with the information included during the installation prompts. It can be changed manually at a later time as described on the Advanced configuration page.

Configure cached fields

In order to configure the local cache, the script will automatically extract all suitable fields from the NXQL queries found in the topics in the config directory and create the /var/nexthink/nexthink-chatbot-adapter/config/cached_fields.yaml file with a list of all the fields.

Once you have configured the installation, the script will load the Docker images and will start the Docker containers.

You must log out and log in to be able to run Docker commands successfully.

Check that the Docker containers are up and running

$ docker ps

Customize remote actions (optional)

If remote actions are different from those provided in the content pack, then you should customize the remote actions in: /var/nexthink/nexthink-chatbotadapter/topics/remote_actions.yaml

The values formatted as code below should be replaced based on your setup.

Verify remote actions

Verify that the remote actions mentioned in the file exist in your Nexthink installation. You can find them by their name. Below is an example of what to replace:

Please note that the name of the remote action defined in this file is case sensitive and it must exactly match the name in Finder.

$ vi /var/nexthink/nexthink-chatbot-adapter/config/topics/remote_actions.yaml

repair_outlook_ost_problem: name: Repair Outlook OST Problem UID: 130bb94e-3e0b-f87c-e2::/vb8-3a2d022394fe

set_outlook_online: name: Set Outlook online UID: 683c5c12-6160-913a-99df-6087dbefab6c

clear_outlook_autocomplete_cache: name: Clear Outlook AutoComplete Cache UID: 24c76f25-dcbe-26b9-0fec-b118cce4075d

disk_cleanup: name: Disk Cleanup UID: bf8fe752-03b8-4936-a51c-769705e1fd3d

Update UID

It is necessary to update the UID value in the file if it differs from the UID in the installation.

Change SSL certificate (optional)

You can change the self-signed SSL certificate included in the installation by your own trusted SSL certificate. This can be done by following instructions on the Custom certificate installation page.

Restart the environment

After all the remote actions have been properly configured in Finder to be either launched manually or automatically, it is recommended to restart the containers. Navigate to the folder where the zip was decompressed and execute the restart script:

$ ./scripts/nexthink-chatbot-adapter-restart.sh

Check that the containers are up and running

$ docker ps

Check the API

To check the correct configuration of the deployment, call the API to assure it is working properly.

If the API Key was not previously generated, use curl to generate it:

Code

$ curl -X POST -k https://<Nexthink_User>:<Nexthink_Pass>@localhost:8090/v1/api_key  
1574fbf6cece2c1d0af2c771a1bf192161b7956d3551b5eb33bc42bafafe9adc

<Nexthink_user>is the local user in Nexthink Portal added during the installation.

If the API key was generated previously, use:

Code

$ curl -k https://<Nexthink_User>:<Nexthink_Pass>@localhost:8090/v1/api_key 
1574fbf6cece2c1d0af2c771a1bf192161b7956d3551b5eb33bc42bafafe9adc 

Ensure that only one API key is valid at a time. The key is not regenerated at restart, and it never expires. However, once you generate a new one, the previous one is automatically invalidated.

Validate that the endpoint is working by listing the topics:

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

Validate access to Engines by finding the devices for an employee.

• Find the employee in Finder.

• Retrieve the employee devices by sending the API Key as a custom header.

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

Example:

Code

$ curl -k -H "X-API-key:1574fbf6cece2c1d0af2c771a1bf192161b7956d3551b5eb33bc42bafafe9adc" 
\https://localhost:8090/v1/user/jsmith@NXT-JSMITH/devices  

[{"name":"NXT-
JSMITH","device_uid":"f38d649e92b44788cf5674f704834591","platform":"windows",
"total_ram":42 94967296,"last_ip_address":"192.168.5.11",
"group_name":"WORKGROUP","entity":"","device_mode l":"VMware Virtual Platform",
"os_version_and_architecture": "Windows 10 Enterprise (64 bits)",
"system_drive_capacity":26317156352,"system_drive_free_space":16200781824,
"number_of _days_since_last_boot":2}] 

Follow an installation checklist in the Troubleshooting guide if you have trouble with any of the steps listed above.

Check the Logs

Check the logs to verify that the installation is going as expected. Each log can be read from the stdout of each container. For instance, for an overview of incoming and outgoing requests, we can check the chatbotingress logs.

Code

$ docker logs -f nexthink-chatbot-adapter_chatbotingress_1 

2019-03-06T12:23:10Z [Ingress] main.go:54: Debug flag true 
2019-03-06T12:23:10Z [Ingress] main.go:62: Secure flag true 
2019-03-06T12:23:10Z [Ingress] main.go:129: Starting Chatbot Ingress on port 8090 
2019-03-06T12:23:10Z [Ingress] main.go:132: /user_devices: http://userdevices:8001/v1 2019-03-06T12:23:10Z [Ingress] main.go:132: /topic: http://topicmanager:8002/v1 
2019-03-06T12:23:10Z [Ingress] main.go:132: /remote_action: http://remoteactionmanager:8003/v1 
2019-03-06T12:23:28Z [IngressDebug] router.go:20: URL: 
http://userdevices:8001/v1/user_devices/nexthink@NXTV-WIN10EN 
2019-03-06T12:23:29Z [IngressDebug] router.go:34: Response: [{"name":"NXTV-WIN10EN-
15","device_uid":"54965105b7192099cc5c17e2be830df3","platform":"windows"},{"name":"NXTV-
WIN10EN","device_uid":"9a1dcb96b1f185fa23b728fd29b773e1","platform":"windows"}]