Skip to content

Upgrade

Smart Check-In upgrade/downgrade scenarios

The Kiosk Services adapter hub template contains two version numbers:

  • Template's version number (description field and version seen in the template name in the “Adapter Hub Service Templates” drop down in UIP)
  • The Kiosk Orchestrator image version seen in the file

The Kiosk Server and Kiosk Administrator services are deployed by the Kiosk Orchestrator. Kiosk Server and Kiosk Administrator individual version numbers are listed in the “kiosk-version.txt” file included with the Kiosk distribution files.

The Template version number is for information only and can be used to reference which distribution media is being used.

The Kiosk Orchestrator image version is used to determine if this is an upgrade or downgrade scenario. It is possible to edit the Kiosk Orchestrator image version to download a different set of Kiosk Server and Kiosk Administrator services. If the Kiosk Orchestrator image version is different than what was originally listed in the Kiosk Services template that was provided with the Kiosk distribution, then the Kiosk Server and Kiosk Administrator version seen in the “kiosk-version.txt” used as a reference will not match and should not be used to determine what is already installed.

  • An upgrade scenario is a deployment operation where the new Kiosk Orchestrator version is higher than the current Kiosk Orchestrator version. It is desirable that all deployment operations using adapter hub templates are upgrade scenarios.
  • A downgrade scenario is any deployment operation where the new Kiosk Orchestrator version is lower than the current Kiosk Orchestrator version.

The most common upgrade scenario will be when a template with a higher version number is deployed. Another option is if the Kiosk Orchestrator image version is manually altered to be higher than the currently deployed version.

Supported downgrade scenarios

In general, performing a downgrade is something that is not recommended, unless advised by a NEC representative. For example, we may need to downgrade when the newer versions present serious functionality or security issues. In this case, to mitigate, customers will be advised to downgrade to the last known good template version while they wait for a patch.

The most common downgrade scenario will be the one in which we deploy a template with a lower version number. Another option is if the Kiosk Orchestrator image version is manually altered to be lower than the currently deployed version.

Uncommon scenarios that should be avoided

An uncommon scenario is when we manually edit the Kiosk Server or Kiosk Admin versions directly in the text editor in UIP then we redeploy.

Doing this kind of operation is to be avoided, because it may end up in incompatible Admin/Server versions, with unpredictable effects.

Preparation

During setup, configuration and the life of the product at a customer site, many customizations could have been made. To ensure those customizations are not lost, it is important to keep a continuous record of the changes made. During an upgrade it is important to review all customizations and ensure it is known what changes will need to be merged after the upgrade so that nothing is lost, and custom behaviors will not need to be re-implemented.

If it is unclear what customizations were made, these guidelines will help cover all aspects to review where custom changes may have been made.

These preparation steps should be started well in advance of the planned upgrade date and all steps completed before going on site to perform the upgrade.

Record the Current Versions

Make note of the current version of the following software:

  • Ubuntu OS
  • UNIVERGE Integration Platform
  • Adapter Hub
  • Kiosk Orchestrator (Kiosk Services Template)
  • Kiosk Client

Backup the System

To ensure all customizations are preserved and the system can be recovered if needed, backup of the data should be made.

Note

If the existing version of Smart Check-In is version 1.8 or earlier, follow the additional instructions for backing up and restoring the Kiosk Services MongoDB to a new system using How to Backup and Restore Smart Check-In Data.

  • Perform the Export Configuration option in UIP Administrator.  ("UIP Administrator > Export Configuration", select all checkbox options and then Export)
  • Export each individual workflow from UIP as seen under "UIP Administrator > Workflows", then for each row select the "More" link and select the "Export" option.
  • Screen shot / write down all adapter names, the names can be customized per kiosk for certain adapters such as dispenser adapters. The upgrade will retain adapters and adapter config but if a mistake is made this information will be preserved.
  • Make a copy of the current and active Kiosk Services Adapter Hub template. This contains IP Address and machine names that are in use.
  • In Kiosk Administrator, go through every page and screen shot settings or write them down. Kiosk Administrator settings are not lost or overwritten however between versions, changes to default data may have been made which will require restoring defaults to see the new fields. The previous selections will need to be restored.
  • For Kiosk Client, backup the current install folder and all sub folders. During upgrade, backups are automatically made, and new files will overwrite what is in the current install folder. Backup the customizations folder and sub folders located at “C:\ProgramData\NEC\kiosk”.
  • Backup config files in the installation folders for the "Serial2TCP" service and "TCPProxy" service (if installed).

Determine what has been Customized

Customizations for Kiosk behavior can be made in both UIP (related to adapters and workflows) and for each individual Kiosk Client. As part of the Smart Check-In documentation, each release contains a document with a list of files that were affected by changes for the release called “Smart Check-In Affected Files List”. This document should be used to know which files and which customizations may need to be merged after the Kiosk Client upgrade.

Workflows in UIP

Many workflows used by Kiosk can be customized to perform site specific actions and some contain configuration settings and contact information for notifications. When a new UIP import json file is imported as part of an upgrade, the exiting workflow is overwritten. Any changes to a workflow need to be re-applied after the latest workflow has been imported.

Kiosk Client Customizations

Kiosk Client files can be customized from their default. Newer versions of these files may contain new features or fixes. A review of the “Smart Check-In Affected Files List” document should be done to see if there are changes to any files that have customizations at the site they will need to be merged.

  • GDPR / Privacy Policy/ TCNotes files (Default file must be modified by the customer)
  • Credit Card images (if images are different than default)
  • Membership images
  • Email Message Text
  • Credit Cards images
  • Add-on Packages images (custom images to match the hotel’s add-on packages are placed in the “PackageImages” folder).
  • Language translation files (On screen text customizations for multiple languages)
  • Registration Card (modify formatting, data and images if desired to match hotel’s reg card)
  • Health Questionnaire
  • xml (sets Kiosks behavior and enables/disables features)

Custom Theme

Most hotels will want to change the color and apply custom logos to match their hotel appearance. The “styles.css” file is modified to make the custom theme. As new features are added, the default styles.css deployed with a new Kiosk Client version may be modified to include these new features. Use the Utilities Tool in Kiosk Administrator to compare a new styles.css found in the Kiosk Client installation folder with the original styles.css file in a backup folder to see the differences and then merge the custom changes for the hotel to the new styles.css file.

Making Changes and Testing

Some sites may have many customizations. Merging changes from one file to another can be tedious and error prone. After the custom changes have been identified, it is recommended to merge those customizations to new files on a test Kiosk Client or offsite in a dealer lab and then test prior to performing the upgrade. All aspects of customizations should be known, merged and tested before applying on a Kiosk that needs to be upgraded to minimize downtime and issues on startup.  This includes all items mentioned, UIP workflows, Kiosk Client files and the custom theme.

Performing the Upgrade and Configuring Kiosk

The same steps for performing a new installation and configuring a system should be followed when performing an upgrade. The Installation guide should be followed for installing and configuring the system (UIP, Adapter Hub, Kiosk Services, Kiosk Client and other supporting services). Between versions its possible new improvements to security and component communication have been made and instructions should be followed to setup and configure the system after upgrade.

Upgrade Hardware Components

Follow the NEC UNIVERGE Integration Platform Documentation to determine if the current UIP and Adapter Hub host VM’s and operating systems meet the recommended system requirements and versions. If not, make plans for OS system upgrade or new server migration and correct server deficiencies as needed.

Upgrade Software Components

  • Before upgrading UIP and the Adapter Hub Services (which includes Kiosk Services) to the latest version, it is recommended to apply the latest security updates to Ubuntu. Run "apt update" and then "apt upgrade" on the UIP and Adapter Hub machines to get the latest package versions including kernel updates. If the system is using one or more remote Adapter Hubs, it is recommended to apply the latest security updates for Ubuntu to all Adapter Hubs.
  • Upgrade UNIVERGE Integration Platform to the latest version from UIP Admin.
  • Upgrade Adapter Hub if a newer version is available. See Adapter Hub - NEC UNIVERGE Integration Platform Documentation for updating Adapter Hub to latest version.
  • Kiosk Services
    • If the previous version of Kiosk Services were from Kiosk 1.8 or earlier, a new Kiosk Service will need to be created and the old Kiosk Service undeployed. Using UIP, navigate to "UIP Administrator > Adapter Hubs > Adapter Hub Services" and in the "Deploy Actions" drop down select "Undeploy".  This will stop and remove the Kiosk Services 1.8 on the Adapter Hub; the data (logs, volumes, etc.) will remain and may be manually cleaned up in a later step to recover disk space on the Adapter Hub machine.
    • If the previous version of Kiosk Services were from Kiosk 1.8 or earlier, follow the instructions for creating and configuring new Kiosk Services.
    • For updates to an existing deployed Kiosk Service, use the new template for the existing Kiosk Services deployment. Configure a new template with information from the old template and overwrite the old template. The same Kiosk Services should be used, or data will be lost or appear missing since each Kiosk Service deployment has its own database. Creating multiple Kiosk Services and having multiple Kiosk services running on the same adapter hub will impact performance and potentially use all hard disk space on the server.
  • Update all installed adapters to the latest version from the Adapter Type store in UIP Admin on the Adapter type page.
  • Import Kiosk UIP Config files as needed to get latest workflows and trigger changes. Uncheck all other checkboxes for import including adapters. Select overwrite existing so that the new workflows and triggers will get updated. (https://smartcheck-in.nec-help.com/latest/#download-uip-configuration)
  • Upgrade all Kiosk Client installations
  • Upgrade supporting connection services as needed (Serial2TCP service, TCP Proxy service, NEC AssureID service)

Reclaiming Hard Disk Space

Performing upgrades to UIP and Kiosk Services copies the install image to the server’s hard disk as part of the deployment process. Overtime the images may fill the hard disk space causing the system to not respond.

To clear the installed images after upgrade if available hard disk space is a concern see the following methods:

If UIP and Adapter Hub are running on the same machine:

  • UIP automatically performs install image cleanup for UIP and Kiosk Services when the UIP is upgraded.
    • Before upgrading to the latest Kiosk Services, upgrading to the latest available UIP is recommended to ensure old images are removed.
  • Restarting the Adapter Hub does not perform image cleanup if it is running on the same machine as the UIP.

If Adapter Hub is on a separate machine from UIP:

  • An Adapter Hub will run install image cleanup each time it is restarted
    • To restart the Adapter Hub, in UIP, navigate to Home > Adapter Hubs. Locate the Adapter Hub that is running the Kiosk Services and select the Restart link.
  • An Adapter Hub automatically runs image cleanup on a 30-day interval from last restart.
  • When an Adapter Hub is upgraded, it will run image cleanup.

Configuration

Configuring the Smart Check-In Kiosk after upgrade should follow the same instructions as a new install. New features or changes in settings will be described in this documentation.

Apply customizations for workflows where changes were determined to be made.

Kiosk Client files and custom theme that were merged and prepared prior to te site upgrade can be copied into place. Custom files should be copied to the C:\ProgramData\NEC\kiosk\Custom folder structure as described in Customizing Kiosk Theme.

Test On-site

Thoroughly test the full functionality of all Kiosk Client positions after the upgrade and configuration and file merge has been completed.  Ensure there were no copy or merge errors during the final setup.