Installation and configuration

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

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

  • 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

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

$ ./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_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

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.

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

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)

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:

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

If the API key was generated previously, use:

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:

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.