Update to newer version

This document provides comprehensive information about the introduction and concepts around Nexthink Chatbot SDK, its API and use cases. The information contained herein is subject to change without notice and is not guaranteed to be error-free. If you find any errors, please report them to us via Nexthink Support Portal. This document is intended for readers with a detailed understanding of Nexthink technology.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Considerations

The following elements are persistent during updates:

• Environment configuration file (.env)

• The API key for authentication

• Custom certificates

• discovery.yaml file

The persistence of the following files depends on your choices, but a backup will always be created:

• Topic configuration files

• Remote actions file

These files are in the /var/nexthink/nexthink-chatbot-adapter/config/topics folder. A manual step is required to use the non-persistent files again as described in the following sections.

The persistence of the Engine configuration also depends on your choices. During the update process, the Engines which are already configured in the file are automatically compared against those retrieved from Nexthink Portal. You can find more information in the Update steps section.

Update requirements

The latest Chatbot SDK Content Library has been downloaded, installed and configured in Finder as explained in the Customize remote actions section.

For hardware dimensioning guidelines, please refer to the Dimensioning guide.

Update steps

In order to update to a newer version, you must use the update script.

Download

Download the zip file to /home/nexthink and unzip the file

$ cd /home/nexthink 
$ unzip nexthink-chatbot-adapter-X.X.X.zip 

Update script

Call the update script

$ cd ~/nexthink-chatbot-adapter-X.X.X/ 
$ chmod +x scripts/nexthink-chatbot-adapter-*.sh 
$ ./scripts/nexthink-chatbot-adapter-update.sh ./nexthink-chatbot-adapter-X.X.X.tgz

This creates a backup of your existing configuration with the timestamp of the update, for instance, /var/nexthink/nexthink-chatbot-adapter_2019-09-04-15-07_bak. During the update process, the script reuses the existing configuration for the .env file. The backup folder includes the following information:

• The config folder, including the topics subfolder (topics and remote actions YAML files) in addition tocached_fields.yaml, discovery.yaml and engines.yaml configuration files

• The environment configuration file (.env)

• The docker-compose.yml configuration file

• The release.md file

Replace topics

If there are changes to the current topics and remote actions configuration files, the script will prompt a question of whether existing files should be kept or replaced with the new ones. If kept, the update process will create a new folder named after the new release number topics.<release_number> inside /tmp/nexthink-chatbotadapter_<release_number>.update.<current_date>, containing the new topics and remote actions configuration files.

Keep in mind that although this folder contains the newest content, Chatbot SDK will continue functioning with the old content. If you want to merge the newest content with the old content, follow these steps:

• If you have custom topics, ensure they have different names from those in the newest topics folder.

• If you add custom topics, the manual merge is always required for remote actions.

• To apply changes to remote actions and the configuration of topics, follow the process in Adding or changing topics configurations.

If there are no changes, the topics.<release_number> folder will not be created.

Update Engine configuration

The script also detects the differences between the current Engine configurations and those from Nexthink Portal. If any differences are detected in the fields host, port, databaseUID or timezone, the update process shows these differences before asking whether the existing Engine configurations should be kept or replaced with the latest ones. If kept, a new engines.yaml file with the most up-to-date information retrieved from Nexthink Portal will be created in the /tmp/nexthink-chatbot-adapter_<release_number>.update.<current_date> folder and will be available for manual review.

If there are no changes, a new engines.yaml file will not be created in the temporary folder.

Example:

This is an example of how the differences are shown:

• “+” indicates that the line will be added

• “-“ indicates that the line will be removed from the Engine configuration

• the values 10.0.0.51 for the host and Europe/Madrid for the timezone will be removed

• the values 10.0.0.52 and Europe/Zurich will be added to the configuration

- host: 10.0.0.51 
+  host: 10.0.0.52 
- timezone: Europe/Madrid 
+  timezone: Europe/Zurich 

Proxy configuration

When upgrading to version 1.2.0 or greater, the new environment variables for the proxy configuration will be added to the .env file /var/nexthink/nexthink-chatbot-adapter/.env. If you intend to use the proxy, modify those variables accordingly.

Rollback

When an operation fails during the update process, a rollback is performed. Essentially, the rollback undoes the changes that the update process has performed and reverts all the relevant directories to their previous state: Docker containers, database state, etc.