Home → Installation and Upgrade Manual → HelpSpot 4 - Installation & Setup → Updating to HelpSpot 4 from Version 3

3. Updating to HelpSpot 4 from Version 3

HelpSpot version 4 improves support for multiple languages and search. Both of these improvements require extra steps from the usual HelpSpot update process when updating to version 4.

Windows Users

As of version 4, Windows users must use the provided Windows installer to update to version 4. 

You should fully backup your HelpSpot files before updating to HelpSpot 4.

The following are new requirements for Windows users:

  1. If you have not already, you must update to HelpSpot version 3.2.12 before updating to version 4+
  2. For SqlServer installs, SqlServer 2008+ (SqlServer Version 2005 is no longer supported)
  3. Windows Server 2008+ (Windows Server Version 2003 is no longer supported)
  4. The update may take a bit longer than usual due to the conversion process of the content to the UTF8 character set into a new database. This would present itself in the last steps of installation and may appear as if the installer is stalled.

If you have installed HelpSpot on windows "manually" (without using the provided Windows installer), please contact customer support for help and available update options.

Portal requests: reCAPTCHA

If you use the reCAPTCHA spam catcher on the Portals, you will need to generate a new reCAPTCHA site key. HelpSpot 4 uses Googles reCAPTCHA. You can login and get a reCAPTCHA site key and secret key here.

You can find your current portal spam filter settings and update them within Admin > Settings > Portal. If you have "Captcha Type" set to "reCaptcha", you'll have the ability to update your site/secret keys within the "reCaptcha Service" section of that page.

Linux Users

The basic steps to upgrading from version 3 to 4 include:

Some of the following steps requires the use of the command-line. If you do not have access to the command-line to run the following commands, please contact us to discuss some available options on updating to Version 4!

The following steps and further documentation are the steps to update to HelpSpot 4:

  1. Server Setup - If you need to update your server to a newer PHP
  2. Download HelpSpot and overwrite current files:
    • Run the convert:base command
    • Run the convert:requests command
    • Run the update command
    • Be sure to backup Version 3 and restore any customizations
  3. Install and configure SphinxSearch (optional for advanced users)

Prerequisites

Note that you must update to HelpSpot 4 from version 3.2.12 This may mean updating to that version before updating to HelpSpot 4. Previous versions of HelpSpot are available to all customers.

The base version of PHP required has been changed from PHP 5.3 to PHP 5.6.

This may also mean updating your IonCube loader to be compatible with a newer version of PHP. The process of installing/updating IonCube is outlined in our Server Guide for Debian/Ubuntu and RedHat/CentOS servers.

Note that there is a bug in IonCube version 4. Please update to IonCube version 5 for use with HelpSpot. 

Portal requests: reCAPTCHA

If you use the reCAPTCHA spam catcher on the Portals, you will need to generate a new reCAPTCHA site key. HelpSpot 4 uses Googles reCAPTCHA. You can login and get a reCAPTCHA site key and secret key here.

You can find your current portal spam filter settings and update them within Admin > Settings > Portal. If you have "Captcha Type" set to "reCaptcha", you'll have the ability to update your site/secret keys within the "reCaptcha Service" section of that page.

Latest HelpSpot Files

HelpSpot files are available for download in the HelpSpot Store.

You should backup your entire HelpSpot installation prior to updating. 

You will likely need/want to restore any customizations made to HelpSpot, typically found in the following locations:

These have not changed between HelpSpot versions 3 and 4, and should continue to operate normally.

New Data Directory

The new HelpSpot comes with a "data" directory found in the root of the HelpSpot files. This directly will contain logs and generated files such as Sphinx Search configuration, cache files and serve as a place for attachments to be saved.

This directory needs to be writable by HelpSpot. Windows users will have this setup for them automatically by using the Windows installer. Linux users can follow the HelpSpot 4 Server Security documentation to securely allow this directory to be writable.

Update Config.php

The config.php file has new variables which are required for HelpSpot 4. The included "config-empty.php" contains the full set that are expected, and can be used to compare your existing config.php in order to add the new ones.

New variables introduced in HelpSpot 4 include:

Each of these are set in the following format:

define('VARIABLE_NAME', 'VARIABLE_VALUE');

So, for example, to turn on debugging (show full PHP errors, a new feature of HelpSpot 4), you can set cDEBUG to "true":

define('cDEBUG', true);

Turning on debugging is recommended only for debugging purposes, if you are encountering an error. A typical use case for this might be if you receive a white screen with no output within HelpSpot. Note that php.ini error reporting values may affect whether the HelpSpot debugger can show errors.

Here is the new config.php file and all variables:

/**
 * How To Use This File:
 * 1. Copy and Rename this file to "config.php"
 * 2. Fill out/change necessary database credentials and base URL (cHOST).
 */

/**
 * Database Credentials
 */
define('cDBTYPE',      'mysql');               // 'mysql', 'mssql' or 'postgres_helpspot'
define('cDBHOSTNAME',  '127.0.0.1');           // e.g. '127.0.0.1', 'localhost' or 'db.example.com'
define('cDBUSERNAME',  'helpspot_user');
define('cDBPASSWORD',  'something-random');
define('cDBNAME',      'helpspot_db');

define('cDBCHARSET',   'utf8');                // Use "utf8mb4" for MySQL 5.5.3+
define('cDBCOLLATION', 'utf8_unicode_ci');     // Use "utf8mb4_unicode_ci" for MySQL 5.5.3+
/**
*Define search engine
*/
define('SEARCH_ENGINE', 'database'); //Defaults to database search.
/**
 * SphinxSearch Search Engine
 */
define('cSEARCHHOST', '127.0.0.1');
define('cSEARCHPORT', '9306');

/**
 * General
 */
define('cHOST','http://example.com/helpspot'); // Base URL used within HelpSpot, WITHOUT tailing slash "/"

define('cBASEPATH',   dirname(__FILE__));      // Base file path to HelpSpot
define('cDATADIR',    cBASEPATH.'/data');      // Path to server-writable `data` directory
define('cDEBUG',      false);                  // Setting to true will output errors to the browser and log file

New Database

The HelpSpot version 3 database is encoded in a way that doesn't support all the characters in non-latin alphabets. In order to update to HelpSpot version 4 and support multiple languages and alphabets, follow these steps:

This update will not change your current database, but will copy and convert its data to a new database. Even so, we suggest backing up the current HelpSpot database before proceeding.

There are two main steps to upgrading the database:

1. Creating a new database supporting UTF-8
2. Copying the old database to the new, which also converts existing data to UTF-8

Note that while this process will convert old data to UTF-8, any special characters (non-latin characters) may already be "lost" - characters that appear as "?" in HelpSpot requests, for example, may remain that way. New data, however, will fully support HelpSpot

1. Create a new, empty database which supports UTF-8

HelpSpot requires a database which supports UTF-8. For instructions on creating a database supporting UTF-8, see our documentation on Creating a UTF-8 Database.

Most hosting will give you the ability to define the database parameters needed to make your database support UTF-8. You can usually adjust your database after it's created as well.

Once the database is created, edit the config.php file to add in your NEW database information:

# Example for MySQL database configuration
define('cDBTYPE','mysql')
define('cDBHOSTNAME','localhost');
define('cDBUSERNAME','new_user_name');
define('cDBPASSWORD','new_password');
define('cDBNAME','new_database_name');

2. Convert the old database to UTF-8

This step will take data from the old database, convert it to UTF-8, and put it into the new database. It runs in two steps:

1. First it takes "supporting" data, such as users, knowledge books, forums and more, and converts it.
2. Then it runs through each Request, starting from the newest, and converts each request and related data (request and history, attachments, reminders, reporting data, etc). This step can take a while, so it can be run to first convert the last 90 days (or so) of data, and then convert the remaining in the background to finish the remaining data, while still being able to use the site.

These documents cover Linux installation. The Windows installer will automate this process for you. However, should you need to, you can run these commands on Windows as well.

By default, HelpSpot used to default to the latin1 character set (ISO-8859-1). Some customers have changed these character sets within the helpspot/lang/english-us/lg.charset.php file (or similar file within their language). Any customers that have changed this should add the --from-encoding flag in the following two commands. Otherwise do not include the --from-encoding flag.

The following are common character sets used. Please use the format highlighted in bold when using the "--from-encoding" flag, for example "--from-encoding=latin2":

If you are unsure or have not changed the default HelpSpot character set in the passed, the --from-encoding flag can be unused! If you have used an alternative character set not listed above, you can try that character set (use a value from this table's "charset" column) or contact us for assistance!

From your HelpSpot installation, on your server, first run the initial conversion command:

cd /path/to/helpspot
php hs convert:base

# Of if HelpSpot character set was modified:
php hs convert:base --from-encoding=latin2

This conversion may take 10 minutes and upward, depending on the database size. A database of about 2 GB took us about 10 on a single-core virtual machine with 1GB of ram allocated.

This will take you through steps and information needed to begin conversion the old database to the new one.

Note that your config.php database credentials should point to the new database. Database access credentials asked within the convert:base command will be for the old database.

When that is complete, you can run the next command, which will convert requests and related data, going back the amount of days you specify:

# Convert the last 90 days of requests
php hs convert:requests --days-back=90

# Of if HelpSpot character set was modified:
php hs convert:requests --days-back=90 --from-encoding=latin2

These commands interactively ask for input, but all input can be defined as flags in the command to help with automation! See the documentation on the command line tools for more information.

Converting the first 90 days of requests should only take about a minute or less. However more time could be used if there are many/large requests with many responses within the time period selected.

4. Update HelpSpot

HelpSpot will have some futher updates to make from this point on. You can run these updates using the following comand:

php hs update

That will upgrade HelpSpot to the latest version 4.

Once this is complete, you can start using HelpSpot.

At this point, you can continue to use HelpSpot, and run the conversion of older requests in the background or at a time of your choosing.

# Convert the remaining requests
php hs convert:requests --days-back=all

HelpSpot will keep track of the last Request converted so as not to convert a request and its data more than once.

When you next visit HelpSpot, it may ask you to turn off Maintenance mode. Additionally, it may ask you to update from version 4.0.0 to 4.0.0. This is currently normal behavior.

Speed Tips

Because this upgrade converts all database data from a previous encoding to UTF-8, the more data that's in your database, the longer the conversion will take.

Some tables which may include data you can truncate from your database before the conversion include:

Tables that can be safely truncated

These tables can have hundreds of thousands of rows of data in HelpSpot installs that have been in use for years, and can slow the conversion process down.

Truncating a table is best done directly using a SQL query. For most database types, you can truncate these tables like so:

TRUNCATE TABLE HS_Errors;

# Optionally also explicitly state which database
# In this case, database "helpspot_db"
TRUNCATE TABLE helpspot_db.HS_Errors

In PostgreSQL, table names must be quoted, as they contain capital letters

TRUNCATE TABLE "HS_Errors";

Attachments

One last speed tip is to also move attachments out of the HelpSpot database. This will move attachments to the server file system, and therefore take the attachments out of the database conversion process. The preceding link provides a script you can run. This must be run BEFORE the update to version 4, as updates includes changes the database schema for attachments.

If you wish to move files to the file system after the update to HelpSpot 4, you can use the new attachments:tofile command.

While documents are not converted or modified in anyway, they are copied to the new database during the conversion process. Removing them from the database before the update and saving them as files will ensure that the script does not need to handle them.

Sphinx Search

After the conversion, HelpSpot 4 will be installed and updated. It will now be useable!

HelpSpot does not require SphinxSearch, but the search capabilities can be enhanced in certain circumstances. 

Linux users can find guides for installing SphinxSearch on Debian/Ubuntu servers here, and on RedHat/CentOS servers here.

This page was: Helpful | Not Helpful
← HelpSpot 4 Overview Installing a New HelpSpot 4 →