HomeAdmin ManualPrinter Friendly Version

Admin Manual

Everything you need for installation, upgrading, configuration and other advanced issues.

1. HelpSpot 5 Installation and Upgrade

1.1. HelpSpot 5 Overview

Welcome to the HelpSpot Installation Documentation. Please review the documentation in this chapter carefully to install a new instance of HelpSpot 5 or upgrade your existing instance.

1.2. HelpSpot 5 Installation

Installation

HelpSpot 5 server requirements can be found here.

Windows Installation

The Windows Server installation guide can be found here. This guide uses an IIS and Microsoft SQL Server based installation. Legacy windows installer is provided on the download page for HelpSpot. However, we do not recommend using that installer at this point for new installations. You can read more about these changes here.

Linux Installation

General Linux installation documentation can be found here. We also have specific walk-through examples of installing HelpSpot:

  1. Red Hat
  2. Ubuntu

 

1.3. HelpSpot Linux Installation

The general steps for installing HelpSpot on linux are:

  1. Ensure server is ready to serve a PHP application
  2. Add HelpSpot files to the web server
  3. Configure the .env file
  4. Run the installer command
  5. View HelpSpot in the web browser
  6. Setup CRON tasks
  7. Setup Queue worker

We provide specific setup guides for Red Hat and Ubuntu.

Server Configuration

Your HelpSpot server should be configured to meet the server requirements prior to beginning installation.

HelpSpot Files

You can download HelpSpot files and your license from the HelpSpot Store.

Once the files are on your server, the HelpSpot site files should sit one directory "above" the web root.

For example, if your Apache/Nginx web root is configured to /var/www/helpspot/public, then the HelpSpot site files should be placed in /var/www/helpspot.

The HelpSpot files include a public directory to be used as the public web root. The webroot configured in Nginx/Apache should therefore be configured to point to the public directory e.g. /var/www/helpspot/public.

Create HelpSpot Database

MySQL databases for HelpSpot version 5 should default to the InnoDB storage engine and to a UTF-8mb4 character set and collation.

CREATE DATABASE helpspot_db2
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

Note that you can change the database name (helpspot_db) as needed for your use case. You may also need to assign a specific user to the database.

Environment Configuration

HelpSpot requires a file named .env with configuration details.

HelpSpot includes a .env.example file. You can copy this file to create a file named .env and change the parameters as needed:

APP_DEBUG=false
APP_URL=https://example.org
APP_KEY=

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=helpspot
DB_USERNAME=some_user
DB_PASSWORD=some_pass

QUEUE_CONNECTION=database

Here are some details on the configuration:

  • APP_DEBUG - Setting this to true will show full error stack traces in the web browser if errors occur. Errors will always appear in the log file at storage/logs/helpspot.log whether this is set to true or false.
  • APP_URL - The URL used to access HelpSpot from the web browser. This is important to set correctly so HelpSpot generates links correctly. This should include the "https://" portion and any trailing file paths, such as "https://example.org/helpspot".
  • APP_KEY - This will be set during installation should be present but left blank (exactly as APP_KEY=).
  • DB_CONNECTION - one of mysql or sqlsrv. Use mysql for any MySQL variant such as MariaDB or Percona
  • DB_* - the connection details for the database
  • QUEUE_CONNECTION - This should stay as database, but it's possible to use other queue connections, such as redis.

Install HelpSpot

This will install HelpSpot, which primarily consists of setting up your database for use.

Be sure a plaintext text file with your HelpSpot license is present on the server in a location that your webserver can read from.

To install HelpSpot, you must run a command in your terminal. The following with prompt you for details, although you can provide this command with the required data to automate this:

# Get the help menu to see available options
php hs install -h

# Run the installer interactively
php hs install

For a list of possible timezones, see here.

The value for the license file (one of the prompts you'll receive) shouild be the full path to the text file containing your license, or a relative file path relative to your current directory (the result of the pwd command).

View in Web Browser

Once that is installed, you should be ready to view HelpSpot in your browser. If your HelpSpot is available at https://example.org, you can view:

  • Public Portal at https://example.org
  • Admin area at https://example.org/admin

CRON Task

HelpSpot requires the use of some periodic tasks. On Linux systems, these are powered by CRON.

HelpSpot 5 files include an example CRON task to use in helpers/cron/helpspot. This file can be added to /etc/cron.d or the contents of it can be used to create a cron task using your preferred configuration.

There is just a single CRON task to use:

# Timing    User       Command
* * * * *   www-data   cd /var/www/helpspot && /usr/bin/php hs schedule:run

The above example has a user defined to run the task as. You'll need to adjust the user and file paths as needed for your server. You can omit the user if you're installing this configuration into a user-specific crontab, for example if you're running the command sudo crontab -u www-data -e to run the cron task as user www-data.

Queue Configuration

HelpSpot uses a queue worker to process incoming and outgoing emails.

The command to run in a queue worker is as follows:

php hs queue:listen database --queue=high,default --sleep=3 --tries=3

This assumes you are running the queue worker as a user appropriate (generally the same that runs PHP for web requests, such as www-data) and are running it relative to your HelpSpot directory, such as /var/www/helpspot.

More documentation on setting up the queue worker can be found here.

1.4. Installing HelpSpot 5 On Redhat

This video guide walks through the full setup of HelpSpot 5 On Redhat Linux.

HelpSpot 5 Server Setup

On our RedHat 8 server, we'll install and setup the following:

  • MariaDB - to store HelpSpot data
  • Nginx - to serve web requests and pass them to PHP
  • PHP - to serve the HelpSpot application
  • CRON - to run scheduled tasks
  • Queue Worker - to read and send email

Install

On RedHat 8:

sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm

sudo dnf module list php

sudo dnf module enable -y php:remi-8.0

sudo dnf install unzip vim mysql-server nginx supervisor \
    php-cli php-common php-fpm php-mysqlnd php-imap php-ldap \
    php-pdo php-mcrypt php-gd php-xml php-curl

On Amazon Linux 2:

sudo amazon-linux-extras enable php7.4 nginx1 epel

sudo yum install -y epel-release

sudo yum install -y unzip vim mariadb-server nginx supervisor \
    php-cli php-common php-fpm php-mysqlnd php-imap php-ldap \
    php-pdo php-mcrypt php-gd php-xml php-curl

Configure MySQL

On Redhat:

sudo systemctl enable mysqld
sudo systemctl start mysqld

sudo mysql_secure_installation

mysql -u root -p

create database helpspot charset utf8mb4; create user helpspot@'localhost' identified by 'secret'; grant all privileges on helpspot.* to helpspot@'localhost';

On Amazon Linux 2:

sudo systemctl enable mariadb
sudo systemctl start mariadb

sudo mysql_secure_installation

mysql -u root -p

create database helpspot charset utf8mb4;
create user helpspot@'localhost' identified by 'secret';
grant all privileges on helpspot.* to helpspot@'localhost';

Configure PHP

File /etc/php.ini:

max_execution_time = 120
max_input_time = 120
memory_limit = 256M
post_max_size = 256M
upload_max_filesize = 100M
date.timezone = UTC

File /etc/php-fpm.d/www.conf:

; Note: User/Group used is "apache"
; Note: Socket file is /run/php-fpm/www.sock
pm.max_requests = 500
sudo systemctl enable php-fpm
sudo systemctl start php-fpm

Configure Nginx

sudo systemctl enable nginx
sudo systemctl start nginx

Test it out in the browser! We can create a PHP file to see that it is setup to run PHP applications already:

Create file /usr/share/nginx/html/index.php with:

<?php
phpinfo();

And we'll see that page load without further configuration.

The only change we'll make then is to set a new root to point to where HelpSpot will be installed to.

Edit file /etc/nginx/nginx.conf and change the root:

root         /var/www/helpspot/public;

location / {
    try_files $uri $uri/ /index.php$is_args$args;
}

Then reload Nginx:

# Test nginx configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

Install HelpSpot

cd ~/
curl -o helpspot.zip https://s3.amazonaws.com/helpspot-downloads/5.0.58/helpspot.zip

sudo mv helpspot.zip /var/www
cd /var/www

sudo unzip -q helpspot.zip
sudo mv helpspot_5.0.58 helpspot

cd helpspot
sudo cp .env.example .env

# Update .env file
sudo vim .env

# Change owner of files
sudo chown -R apache:apache /var/www/helpspot
sudo chcon -Rv --user=system_u --role=object_r --type=httpd_sys_content_t /var/www/helpspot
sudo chcon -Rv --type=httpd_sys_content_rw_t /var/www/helpspot/bootstrap
sudo chcon -Rv --type=httpd_sys_content_rw_t /var/www/helpspot/storage


sudo -u apache php hs install

Configure Cron

Create file /etc/cron.d/helpspot and add the following:

* * * * * apache php /var/www/helpspot/hs schedule:run

Check that it's being run:

sudo tail -f /var/log/cron

Configure Queue

We'll enable/start the service supervisord:

sudo systemctl enable supervisord
sudo systemctl start supervisord

Create file /etc/supervisord.d/helpspot.ini with contents:

[program:helpspot]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/helpspot/hs queue:listen database --queue=high,default --sleep=3 --tries=3
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=apache
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/helpspot-worker.log

Then run the following to start the workers:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start helpspot:*

Keep an eye on your error log to spot any issues at storage/logs/helpspot.log, e.g. /var/www/helpspot/storage/logs/helpspot.log.

1.5. Installing HelpSpot 5 On Ubuntu

This video walks through the entire process of setting up a new install of HelpSpot on Ubuntu Linux.

 

1.6. HelpSpot 5 Windows Installation Changes

New Installations:

In order to accommodate a more flexible installation and administration process for Windows HelpSpot installs we are now recommending using the process outlined here to install HelpSpot. This process allows easy updates to each system component and allows for more customization based on system architecture requirements. In general the support for PHP on windows has improved greatly since we introduce the windows installer. So, the automated setup through an install tool is no longer needed.

Updates

Updates are also being streamlined into a process very similar to the linux update process. This process will require less downtime and be less prone to errors based on system customization. If you need to update your instance from HelpSpot 4 (which was installed with the windows installer) to HelpSpot 5 we have documented those steps here.

Windows Installer

The windows installer / updater will still be available for download for the time being.

1.7. Installing HelpSpot 5 On Windows Step by Step

Download HelpSpot

  1. Download the latest zip package of HelpSpot from https://store.helpspot.comOpen in new icon
  2. Download your HelpSpot license file from https://store.helpspot.comOpen in new icon

Install IIS

  1. You can follow Microsoft's provided documentation: https://docs.microsoft.com/en-us/iis/install/installing-iis-85/installing-iis-85-on-windows-server-2012-r2Open in new icon
  2. Make sure to enable the CGI Role under Web Server > Web Server > Application Development

Install PHP

  1. Go to https://windows.php.net/downloadOpen in new icon and download the latest NTS (Non thread safe) build of php 8.0 for x64
  2. Extract the downloaded zip to a temporary location
  3. Create a new PHP directory at C:\PHP
  4. Paste the the contents of your downloaded php package into C:\PHP

Configure PHP

  1. Rename C:\PHP\php.ini-production to C:\PHP\php.ini
  2. Edit the php.ini file and add upload_tmp_dir=c:\PHP\tmp to the bottom of the file.
  3. Find the "Dynamic Extensions" area of your php.ini file and enable these extensions: curl, gd, imap, ldap, mbstring,fileinfo and openssl
  4. Create a directory at c:\PHP\tmp

Install Certificate Store for PHP

  1. Go to https://curl.se/docs/caextract.htmlOpen in new icon and download the latest certificate bundle to C:\PHP\
  2. Edit the php.ini file in C:\PHP\ and add these two lines to the bottom of the file:
    curl.cainfo="C:/php/cacert.pem"
    openssl.cafile="C:/php/cacert.pem"

SQL Server Drivers For PHP

  1. Download the SQL Server drivers for PHP 8.0 from https://github.com/microsoft/msphpsql/releases/download/v5.10.0/Windows-8.0.zipOpen in new icon
  2. Extract the Zip to a temporary location
  3. Open the x64 folder in the extracted folder.
  4. Copy php_sqlsrv_80_nts.dll and php_pdo_sqlsrv_80_nts.dll to C:\PHP\ext\
  5. Open the php.ini file in C:\PHP\php.ini in a editor of your choice
  6. Search for Dynamic Extensions
  7. You will find a list of extensions in this section. Add the two new extensions needed:
    extension=php_pdo_sqlsrv_80_nts
    extension=php_sqlsrv_80_nts
    

Add PHP as an IIS FastCGI Module

  1. Open the IIS Manager
  2. Click on your server in the tree view and then select Handler Mappings
  3. Choose add Module Mapping
    Request path: *.php
    Module: FastCgiModule
    Executable: C:\PHP\php-cgi.exe
    Name: PHPFastCGI
  4. Click Ok to save the new mapping
  5. Select "Yes" to add a entry to FastCGI Collection

Add IIS Default Document

  1. Click on your server in the tree view
  2. Click Add... in the Actions panel to add a new default document.
  3. Enter index.php as a new default document and click ok.

Set Default Directory to Public

  1. In IIS manager expand Sites in the tree view
  2. Click on the Default Website
  3. In the Actions panel under the Edit Site section, click Basic Settings
  4. Change the physical path to %SystemDrive%\inetpub\wwwroot\public

Setup IIS URL Rewrite Extension

  1. Download the extension from https://www.iis.net/downloads/microsoft/url-rewriteOpen in new icon
  2. Install the extension.

Create Your HelpSpot Database and User

  1. Open the SQL Server Management Studio and connect to your SQL Server
  2. Right click on Security and choose New > Login
  3. Enter the desired login name e.g. "helpspot_user"
  4. Choose SQL Server authentication and set a password
  5. Create the user.
  6. Right click on Databases and choose New Database
  7. Enter the desired database name e.g. "helpspot_db"
  8. Set the owner to your previously created user

Setup HelpSpot Files

  1. Copy the contents of your extracted helpspot zip package to C:\inetpub\wwwroot\
  2. Your wwwroot directory should contain an app\ folder, bootstrap\ folder, config\ folder etc.
  3. Edit the properties of the storage directory
  4. In the Security tab give the IIS_IUSRS full control

Environment Configuration

HelpSpot requires a file named .env with configuration details.

HelpSpot includes a .env.example file. You can copy this file to create a file named .env and change the parameters as needed:

APP_DEBUG=false 
APP_URL=http://localhost 
APP_KEY= 
DB_CONNECTION=sqlsrv 
DB_HOST=localhost 
DB_PORT=1433 
DB_DATABASE=helpspot_db
DB_USERNAME=helpspot_user 
DB_PASSWORD=test 
QUEUE_CONNECTION=database

Here are some details on the configuration:

  • APP_DEBUG - Setting this to true will show full error stack traces in the web browser if errors occur. Errors will always appear in the log file at storage/logs/helpspot.log whether this is set to true or false.
  • APP_URL - The URL used to access HelpSpot from the web browser. This is important to set correctly so HelpSpot generates links correctly. This should include the "https://" portion and any trailing file paths, such as "https://example.org/helpspot".
  • APP_KEY - This will be set during installation should be present but left blank (exactly as APP_KEY=).
  • DB_CONNECTION - one of mysql or sqlsrv. On most windows installs you will be using sqlsrv
  • DB_* - the connection details for the database
  • QUEUE_CONNECTION - This should stay as database, but it's possible to use other queue connections, such as redis.

Install HelpSpot

  1. Open the command line and cd to cd C:\inetpub\wwwroot
  2. Run the HelpSpot Installer: c:\PHP\php.exe hs install
  3. Enter the requested information in the install wizard

Setup Your Queue

  1. Navigate to c:\inetpub\wwwroot\helpers\windows
  2. The setup.bat file is preconfigured to use the default paths that are used in these docs. If your php or website are installed at different paths, modify the first two lines to reflect your paths.
  3. Run setup.bat. This will create your supervisor.conf file and install your queue services

1.8. Updating to HelpSpot 5 - Linux

Updating to HelpSpot 5

Note: Updating to HelpSpot 5 requires the latest version 4 be installed first (4.9.5).

The general steps for updating HelpSpot 4 to HelpSpot 5 on linux are:

  1. Ensure your server environment meets the minimum requirements for HelpSpot 5
  2. Backing up HelpSpot 4 files and database
  3. Removing HelpSpot 4 CRON tasks
  4. Running HelpSpot 5 Update Tasks
  5. Restoring Files and Customizations
  6. Configuring HelpSpot 5 CRON tasks
  7. Configuring HelpSpot 5 queue worker

 

 

Requirements

General server requirements for HelpSpot 5 can be found here. It should be noted that HelpSpot 5 no longer requires the IonCube loader php module. It also now requires PHP 7.4 which means most installations will need to upgrade their PHP version.

 

 

Backing up HelpSpot 4

It's important to backup HelpSpot site files and the database prior to updating.

  1. This allows you to roll back if needed
  2. This allows you to copy file-based customizations made to HelpSpot 4 (such as portal templates) and apply them to HelpSpot 5

If attachments are stored on-disk (recommended!), it's not necessarily needed to backup those attachment files. You may not wish to back those up if you have limited disk space or if the attachments are large and copying them takes too much time. Moving them will be enough!

Backing up the HelpSpot 4 database from MySQL/MariaDB/Percona can be run using a commmand similar to this:

mysqldump -u user -p \
    --max_allowed_packet=1073741824 \
    --single-transaction \
    --default-character-set=utf8mb4 \
    helpspot_db \
    | gzip > /path/to/backup/helpspot_db.sql.zip

Larger databases may receive errors about the max allowed packet size, or "mysql has gone away". These errors are usually prevented by increasing the max-allowed-packet configuration for the server to its maximum value, generally under the [mysqld] section of the my.cnf file.

The above example sets max_allowed_packet on the mysqldump command, but that does not affect the server-side configuration for max_allowed_packet. That setting exists on both the mysql client (mysqldump) and mysql server (mysqld) sidses.

 

 

Remove HelpSpot 4 CRON Tasks

You should remove all HelpSpot 4 CRON tasks. HelpSpot 5 has a newer way to run periodic tasks. These still use CRON, but HelpSpot 5 uses a single command rather than multiple CRON tasks.

CRON tasks may be in a few places. The most common locations are:

  1. Within /etc/crontab
  2. A file in /etc/cron.d
  3. A user-specific cron task edited via sudo crontab -u some-user -e

The default HelpSpot 5 CRON tasks (that you should disable/remove) are to run the tasks.php and tasks2.php file, and look similar to this:

* * * * * php /var/www/helpspot/tasks.php
* * * * * php /var/www/helpspot/tasks2.php

 

 

Updating to HelpSpot 5

After backing up the HelpSpot 4 files and database, and ensuring HelpSpot is not running (disabling CRON tasks and perhaps putting HelpSpot into maintenance mode), you can update to HelpSpot 5.

The steps to update to HelpSpot 5 are as follows:

  1. Update the HelpSpot files
  2. Configure your web server
  3. Update HelpSpot (this will affect your database)

Update HelpSpot Files

You'll need to replace the HelpSpot 4 files with the HelpSpot 5 files just like with any HelpSpot update. We recommend moving the HelpSpot 4 code base and then replacing that directory with HelpSpot 5's files (rather than copying/overwriting the files directly).

# Let's assume helpspot 4 is installed at /var/www/helpspot
cd /var/www
sudo mv /var/www/helpspot /var/www/helpspot_old

# Let's assume helpspot 5 is located at ~/helpspot_5.0.xx
sudo mv ~/helpspot_5.0.xx /var/www/helpspot

# Finally, keep HelpSpot 4's config.php file:
sudo cp /var/www/helpspot_old/config.php /var/www/helpspot/config.php

# Likely you'll want to ensure all files are owned by the web server user
# such as "www-data" or "apache" or "httpd":
sudo chown -R www-data:www-data /var/www/helpspot

 

Configure the web server

The web server configuration should be updated to change the web root to HelpSpot's public directory, e.g. /var/www/helpspot/public

More details and examples can be found in the Linux Server Administrations documentation

 

Update HelpSpot

Updating HelpSpot involves creating a new .env file, and then updating the database. The steps to do so are as follows:

# NOTE: We recommend running all commands
# as the same user that runs the web server, such as
# www-data, apache, or httpd:
# e.g. "sudo -u www-data php hs config:convert"

# !! Ensure your HelpSpot 4 config.php file is present
# in the root of your helpspot installation,
# e.g. /var/www/helpspot/config.php

# This will convert your config.php file to a .env file
php hs config:convert

# Generate a new APP_KEY, used for encryption
php hs install:key

# Update HelpSpot's database
php hs update --yes

The above converts the config.php file used in HelpSpot 4 to a .env file usable for HelpSpot 5. However you can also copy/rename the .env.example file and change settings there as needed instead.

The php hs update --yes command will run tasks against your database and may take some time to make certain changes, depending on your database size. A database with multiple millions of request history rows can take multiple (single digit) hours.

 

File Permissions

You will also want to be sure all files are owned as the user running the web server. This is typically a user such as "www-data", "apache" or "httpd". On other servers (cPanel, Plesk, Forge), the user will change per your setup. To change file ownership, run the following:

# We assume the web server runs as user www-data
# and helpspot is installed at /var/www/helpspot
sudo chown -R www-data:www-data /var/www/helpspot

Servers using SELinux may have extra steps to ensure the web server can write to HelpSpot's files. See this video for some examples on modifying SELinux permissions.

 

 

Restoring Files and Customizations

We'll want to restore certain files to the proper location, notably:

  1. Attachment files, if saved to disk (recommended) rather than the database
  2. Portal files and customizations
  3. Custom code and pages (e.g. Live Lookup, items in the custom_code and custom_pages directories, BlackBox or AD authentication files)

 

Attachments

Attachments from emails are most likely being saved to the disk drive. In HelpSpot 4, these were saved into the data/documents directory by default. In HelpSpot 5, the default location changed to storage/documents

Attachments from your HelpSpot 4 installation should be moved to the updated location. However, check the configured Attachment Storage Location in HelpSpot's Admin area found in Admin > Settings > System to see where they are being saved.

Since the Attachment Storage Location is configurable, these locations may be different for you.

# Move HelpSpot 4's attachments to the new location
sudo mv /var/www/helpspot_old/data/documents/* /var/www/helpspot/storage/documents/

# Ensure permissions are set to the web server's user, such as 
# www-data, apache, or httpd
sudo chown -R www-data:www-data /var/www/helpspot/storage

 

Portals

First, we'll cover changes to the primary portal:

The custom_templates directory for the primary portal has been moved from the root directory (/path/to/helpspot/custom_templates) to the public web root /path/to/helspot/public/custom_templates.

So, if that directory used to be located at /var/www/helpspot/custom_templates, those customizations should be restored to /var/www/helpspot/public/custom_templates.

For secondary portals, there are several changes:

  1. Secondary portal directories should be moved from the into the public directory - for example, from /path/to/helpspot/some-portal to /path/to/helpspot/public/some-portal.
  2. The configuration for secondary portals (Admin > Customize > Secondary Portals) should be updated with the new File Directory Path setting (to include the public directory)
  3. Saving changes to any Secondary Portal should update the portal's file-based configuration to HelpSpot 5's standards
  4. There is no longer a config.php file needed within portal directories
  5. The index.php file created has been changed. Saving the secondary portals settings will generate a new index.php file.

There are more details about HelpSpot 5 Portal changes here. These include:

  1. Configuration changes
  2. Updates to portal templates

 

Custom Scripts and Pages

 

Custom Code

The custom_code directory has been moved to the public directory as well. If that directory used to live in /var/www/helpspot/custom_code, it should be moved to /var/www/helpspot/public/custom_code.

The custom_code directory usually contains BlackBox and/or Active Directory authentication files as well.

Any other scripts that need to be accessed by HTTP requests (such as live lookup scripts) should also be moved into the public directory.

 

Custom Pages

The custom_pages directory has been moved from the base HelpSpot directory into the helpspot directory. If it used to be located at /var/www/helpspot/custom_pages, custom pages should be moved into /var/www/helpspot/helpspot/custom_pages.

 

 

Configuring HelpSpot 5 CRON tasks

The following CRON task should be set for HelpSpot 5:

# File /etc/cron.d/helpspot
* * * * * www-data /usr/bin/php /path/to/helpspot5/hs schedule:run

Where and how you configure this CRON task can vary and is up to you. The above example shows adding a new file in /etc/cron.d/helpspot, which also allows you to define what system user runs the CRON task.

You'll likely need to adjust the user and file path used for your system. For more details, see the Linux Administration documentation on CRON tasks

 

 

Configuring HelpSpot 5 queue worker

HelpSpot 5 uses a built-in queue system that allows certain tasks to be run in the background. This includes sending and receiving emails.

Previously, HelpSpot would send emails immediately upon updating a request. This feature pushes that job into a queue, allowing the email sending to happen in the background, reducing the possibility of issues or timeouts when sending multiple emails.

Setting up the queue worker is required for HelpSpot 5. Please see our Queue Worker Configuration section within the Linux Administration documentation to see how.

1.9. Updating to HelpSpot 5 - Windows

Updating to HelpSpot 5 on Windows

Note: Updating to HelpSpot 5 requires the latest version 4 be installed first (4.9.5).

Updating to HelpSpot 5 on windows involves these basic steps. Note: this update will upgrade your windows server to PHP version 7.4. If you run custom PHP scripts on your HelpSpot server it is advisable to check on compatibility.

  1. Backup your HelpSpot files and database
  2. Download and run the HelpSpot 5 installer / upgrader
  3. Restore any customization that were not in the custom_code, custom_pages or custom_templates folders
  4. Restoring any Secondary Portals

 

 

Backing up HelpSpot files and database

The HelpSpot updater will backup the site files, however you may want to create your own backup by copying the HelpSpot site files, typically found at C:\Program Files (x86)\helpspot\helpspot.

Backing up a SqlServer database is best done in Sql Server Management Studio, available as a task on the HelpSpot database.

Backing up a MySQL database can be done using the mysqldump.exe command, available as part of the MySQL installation. If you use the bundled MySQL with HelpSpot, the mysqldump.exe command will likely be available at C:\Program Files (x86)\helpspot\mysql\bin\mysqldump.exe.

An example mysqldump.exe command to use is as follows, best run in cmd.exe instead of PowerShell:

mysqldump.exe -u root -p --max_allowed_packet=1073741824 --default-character-set=utf8mb4 --single-transaction helpspot_db > .\helpspot_db.sql

 

 

Restoring Customizations

The HelpSpot installer/updater will restore customizations found in the custom_code, custom_pages, and custom_templates directories.

However, if you have customizations in other locations, you will need to restore those yourself. You can take them from your own backups, or from the "previousVersionBackup" directory created by the installer. That is most likely at C:\Program Files (x86)\helpspot\backup/previousVersionBackup.

 

 

Restoring Secondary Portals

Secondary portals can be restored to their original location from the previousVersionBack directory (most likely found at C:\Program Files (x86)\helpspot\backup/previousVersionBackup). Once they are back in their location, a helper command can be used to move them to a new location if needed for HelpSpot 5.

For example, if a secondary portal used to be located at C:\Program Files (x86)\helpspot\helpspot\my-portal, then it can be copied back to that location after updating to HelpSpot 5.

Once Secondary Portals are back in place, you can run the following command, which will move and reconfigure the portal as needed. This can be fun in cmd.exe or PowerShell:

cd C:\Program Files (x86)\helpspot\helpspot
..\php\php.exe -c ..\php\php.ini hs portal:migrate --dry-run
..\php\php.exe -c ..\php\php.ini hs portal:migrate

The --dry-run flag can be used to preview what portals will be moved/updated. If it reports that a portal will not be moved, it means that HelpSpot cannot determine where it should be placed and can be moved/updated manually. You can move the directory to a location of your choosing, and then update file paths in the HelpSpot admin area when editing that Secondary Portal.

1.10. Updating to HelpSpot 5 - Windows Manual Update IIS/MSSQL

Update PHP

  1. Stop IIS
  2. Download the latest NTS build of PHP 8 for x86 - https://windows.php.net/download/
  3. Extract the files to a temporary location
  4. Backup your current PHP directory located C:\Program Files (x86)\helpspot\php
  5. Copy the new PHP 8 installation to C:\Program Files (x86)\helpspot\php
  6. Copy the php.ini file from your php backup folder to your new php folder
  7. Download the latest SQL Server php extensions from https://github.com/microsoft/msphpsql/releases and move the x86 dll files to the C:\Program Files (x86)\helpspot\php\ext directory
  8. Edit your php.ini file as follows
    Remove the ioncube loader line:
    [Zend]
    zend_extension="C:\Program Files (x86)\helpspot\ioncube\ioncube_loader_win_7.2.dll"
    
    Update the sql server extension file names:
    extension=php_sqlsrv_72_nts.dll
    extension=php_pdo_sqlsrv_72_nts.dll
    should become
    extension=php_sqlsrv__80_nts.dll
    extension=php_pdo_sqlsrv_80_nts.dll
    

Update HelpSpot Files

  1. Download and unpack the latest helpspot zip package from https://store.helpspot.com
  2. Backup your current helpspot directory in C:\Program Files (x86)\helpspot\helpspot\
  3. Create a new C:\Program Files (x86)\helpspot\helpspot\ directory and place the HelpSpot 5 files in that directory.
  4. Copy the config.php from your HelpSpot 4 backup to C:\Program Files (x86)\helpspot\helpspot\
  5. Copy the \custom_templates directory from your HelpSpot 4 backup to C:\Program Files (x86)\helpspot\helpspot\public\custom_templates
  6. Copy the \custom_code directory from your HelpSpot 4 backup to C:\Program Files (x86)\helpspot\helpspot\public\custom_code
  7. Copy the \custom_pages directory from your HelpSpot 4 backup to C:\Program Files (x86)\helpspot\helpspot\helpspot\custom_pages
  8. Copy the \data\documents directory to C:\Program Files (x86)\helpspot\helpspot\storage\documents

Move IIS Site Directory

  1. Open the IIS Manager
  2. If your HelpSpot site is hosted in a virtual directory click on it and then select "basic settings" from the actions tray
  3. Change the physical path to the public subdirectory in your installation
  4. If you HelpSpot site is hosted at the root of the site change the physical path in the "basic settings" for the site.

Add your handler mapping

  1. In the IIS Manager go the handler mappings for your virtual folder or site.
  2. Add a new Module Mapping Request path: *.php
    Module: FastCGIModule
    Executable: "C:\Program Files (x86)\helpspot\php\php-cgi.exe"
    Name: PHP

Add Default Document

  1. In the IIS Manager go the default Documents for your virtual folder or site.
  2. Add a new default document of index.php

Setup IIS URL Rewrite Extension

  1. Download the extension from https://www.iis.net/downloads/microsoft/url-rewrite
  2. Install the extension.

Modify Storage File Permissions

  1. Modify the file permissions on C:\Program Files (x86)\helpspot\helpspot\storage to allow full access to the user running your application pool. By default this is the IUSR.
  2. Create a php tmp folder in C:\Program Files (x86)\helpspot\php\tmp\ and give full permission to the running your application pool. By default this is the IUSR.

Update HelpSpot

  1. Open the command line and cd to C:\Program Files (x86)\helpspot\helpspot
  2. Convert your config file: ..\php\php.exe hs config:convert
  3. Generate a app key: ..\php\php.exe hs install:key
  4. Update HelpSpot: ..\php\php.exe hs update

Setup Your Queue

  1. Navigate to C:\Program Files (x86)\helpspot\helpspot\helpers\windows
  2. Modify the first two lines to reflect your paths in your installation. By default these will be:
    set AppPath=C:\Program Files (x86)\helpspot\helpspot
    set PHPPath=C:\Program Files (x86)\helpspot\php
  3. Run setup.bat. This will create your supervisor.conf file and install your queue services

1.11. Minor Version Upgrades (v4 or v5)

These instruction apply to minor version upgrades. For example: v4.5.1->v4.8.1 or v5.0.45->5.0.58. For major version upgrades (v4 to v5) see the separate upgrade documentation as the process is a bit different.

The update process for windows installations and and Linux installations are separate on HelpSpot 4 and greater.

Windows

Before running the windows update executable ensure that you have backed up your database and HelpSpot files. You can then download and run the windows updater executable. This updater will perform all of the upgrade steps for you via the graphical wizard.

Linux

It's strongly recommended that you backup your HelpSpot database and files before upgrading. It's especially important to backup files if you have customized your templates or edited the language file.

The installer will make database changes during an upgrade. If something goes wrong the only way to roll back the changes is if you have an up to date backup.

Upgrading Files

Before beginning review the latest system requirements to make sure that the software installed on your server are compatible witht he latest version.

After downloading the new version of HelpSpot, move the files to your server and unpack the tar.gz or zip file in a temporary location.

  1. Stop your supervisor or systemd queue worker.
  2. Move your current helpspot install directory to a backup location (we'll need to restore some files from this backup).
  3. Copy your new helpspot package to that same location where HelpSpot was installed
  4. Copy these directories and files back into your production helpspot folder:
    File / Directory Description
    .env Environment Configuration File
    storage/documents Attachment Storage
    storage/app Application Storage for Jobs
    public/custom_code Custom Code
    public/custom_templates Custom Portal Templates
    public/custom_pages Custom Page Code
    Any secondary portal sites or other custom code you have defined  

Note: The HelpSpot files are binary and your FTP program will most likely upload them as text unless you tell it to use binary mode. This is why it's recommended to move the compressed file (tar.gz/zip) directly to the server first which will avoid any problems. After uploading if you get a file corrupted or Fatal error in your browser at the installer then the files have been uploaded as text instead of binary.

Upgrade Database

The best way to upgrade the database is by using command line php. From your HelpSpot directory run:

php hs update

You can find more info on the HelpSpot command line here: The HelpSpot Command Line

Restart Queue (v5.0.0+)

After upgrading complete we need to ensure that the queue is using the latest code. We'll restart the queue to do this.

php artisan queue:restart 

1.12. Linux Server Administration

Linux Server Administration

 

Webroot Configuration

HelpSpot 5 introduces a new directory in its code base that is intended to be used as the web server's public root directory. That directory is named public.

Web servers should update their web root directive as follows:

  • Nginx: Update the root directive, e.g. root /var/www/helpspot/public;
  • Apache: Update the DocumentRoot directive, e.g. DocumentRoot /var/www/helpspot/public

In HelpSpot 4 and earlier, web server configuration's pointed the web root (root in Nginx, DocumentRoot in Apache) to HelpSpot's root directory.

For example, if HelpSpot was installed at /var/www/helpspot, then the web server's web root would be located at the same directory, /var/www/helpspot.

HelpSpot 5 uses the public directory as an added security measure. It ensures that HelpSpot's code files are not accessible to the public internet. Security measures were previously in place to prevent this, but this adds an extra layer of security.

 

 

Nginx Configuration

Here's an example Nginx configuration, which assumes PHP-FPM for PHP 7.4 is installed.

This configuration assumes an SSL certificate is used.

server {
    # Enforce the use of HTTPS
    listen 80 default_server;
    server_name example.org;
    return 301 https://$host$request_uri;
}

server {
    listen 443 default_server ssl;

    root /var/www/helpspot/public;
    index index.html index.htm index.php;

    access_log /var/log/nginx/helpspot.log helpspot;
    error_log  /var/log/nginx/helpspot-error.log error;

    server_name example.org;

    charset utf-8;

    ssl_certificate           /etc/ssl/helpspot/example.org.crt;
    ssl_certificate_key       /etc/ssl/helpspot/example.org.key;

    # Allow lets encrypt checks
    location ^~ /.well-known/acme-challenge/ {
        allow all;
    }

    # Disallow dot file access
    location ~* (?:^|/)\. {
        deny all;
    }

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location = /favicon.ico { log_not_found off; access_log off; }
    location = /robots.txt  { log_not_found off; access_log off; }

    location ~ \.php$ {
        # This included snippet is on Debian/Ubuntu servers but
        # may not be on RedHat/CentOS/Fedora/AWS Linux servers
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
        fastcgi_buffers 36 64k;
        fastcgi_buffer_size 32k;
        fastcgi_read_timeout 120s;
    }
}

We have detailed video examples of configuring Linux servers for use with HelpSpot 5 available here:

 

HelpSpot in Subdirectory

If HelpSpot is being used in a subdirectory, the following Nginx configuration can help make that work:

server {
    listen 443 default_server ssl;

    # We assume the example.org website is hosted
    # out of the /var/www/html directory
    root /var/www/html;

    index index.html index.htm index.php;

    access_log /var/log/nginx/example.org.log helpspot;
    error_log  /var/log/nginx/example.org.log error;

    server_name example.org;

    charset utf-8;

    ssl_certificate           /etc/ssl/helpspot/example.org.crt;
    ssl_certificate_key       /etc/ssl/helpspot/example.org.key;

    # Allow lets encrypt checks
    location ^~ /.well-known/acme-challenge/ {
        allow all;
    }

    # Disallow dot file access
    location ~* (?:^|/)\. {
        deny all;
    }

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    # If HelpSpot is served from the "/helpdesk" subdirectory
    # then we create a location {} block for it and use
    # an alias to point to the correct web root for HelpSpot
    location /helpdesk {
        alias /var/www/helpspot/public;
        try_files $uri $uri/ @nested;

        location ~ \.php$ {
            include snippets/fastcgi-php.conf;
            fastcgi_param SCRIPT_FILENAME $request_filename;
            fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
            fastcgi_buffers 36 64k;
            fastcgi_buffer_size 32k;
            fastcgi_read_timeout 120s;
        }
    }

    # We also need a rewrite to correctly rewrite the
    # /helpdesk subdirectory, so we don't need index.php
    # in the URI
    location @nested {
        rewrite /helpdesk/(.*)$ /helpdesk/index.php?/$1 last;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
        fastcgi_buffers 36 64k;
        fastcgi_buffer_size 32k;
        fastcgi_read_timeout 120s;
    }
}

 

Note that we installed the HelpSpot code base outside of the web root for the main site.

The web root for example.org is found in /var/www/html while the web root for the HelpSpot installation is found within the HelpSpot code base at /var/www/helpspot. This prevents unauthorized access to HelpSpot code files so we don't, for example, make secrets available within the URL http://example.org/helpspot/.env, which could happen if the HelpSpot code files were installed into directory /var/www/html/helpspot.

 

 

Apache Configuration

Here's an example Apache configuration, which assumes the following Apache modules are installed and enabled:

  1. PHP module
  2. Rewrite module
<VirtualHost *:80>
    ServerName support.example.com
    DocumentRoot /var/www/example.org/public

    <Directory /var/www/example.org/public>
        Options -Indexes +FollowSymLinks +MultiViews 
        # Allow .htaccess file usage: 
        AllowOverride All 
        Require all granted
    </Directory>

    # Disallow access to dotfiles
    # such as the .env file
    <FilesMatch "^\.">
        Order allow,deny
        Deny from all
    </FilesMatch>

    ErrorLog ${APACHE_LOG_DIR}/example.org-error.log
    # Possible values include: debug, info, notice, warn, error, crit, 
    # alert, emerg. LogLevel warn
    CustomLog ${APACHE_LOG_DIR}/example.org-access.log combined
</VirtualHost>

 

HelpSpot in Subdirectory

If HelpSpot is installed into a subdirectory, some extra configuration will be required.

For example, if HelpSpot is accessed in the URL /helpdesk (e.g. https://example.org/helpdesk), the following configuration will work for HelpSpot 5.

This assumes the following Apache modules are installed an enabled:

  1. PHP module
  2. Rewrite module
  3. Alias module
<VirtualHost *:80>
    ServerName example.org
    # We assume the example.org website is hosted
    # out of the /var/www/html directory
    DocumentRoot /var/www/html

    # If HelpSpot is served from the "/helpdesk" subdirectory
    # then we can use an Alias to tell Apache where to find 
    # the HelpSpot site files. In this case, "/var/www/helpspot"
    # (HelpSpot's webroot is the "public" directory within the
    # code base, e.g. "/var/www/helpspot/public").
    Alias "/helpdesk" "/var/www/helpspot/public"
    <Directory /var/www/helpspot/public>
        Options -Indexes +FollowSymLinks +MultiViews 
        # Allow .htaccess file usage: 
        AllowOverride All 
        Require all granted
    </Directory>

    # Disallow access to dotfiles
    # such as the .env file
    <FilesMatch "^\.">
        Order allow,deny
        Deny from all
    </FilesMatch>

    ErrorLog ${APACHE_LOG_DIR}/example.org-error.log
    # Possible values include: debug, info, notice, warn, error, crit, 
    # alert, emerg. LogLevel warn
    CustomLog ${APACHE_LOG_DIR}/example.org-access.log combined
</VirtualHost>

 

Then we need to update the .htaccess file. Within the public directory is a file named .htaccess, e.g. /var/www/helpspot/public/.htaccess. This file needs to be edited to add the RewriteBase directive to include the subdirectory /helpdesk:

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews
    </IfModule>
    
    RewriteEngine On
    
    # Redirect Trailing Slashes If Not A Folder...
    RewriteBase /helpdesk
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)/$ /$1 [L,R=301]
    
    # Handle Front Controller...
    RewriteBase /helpdesk
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
    
    # Handle Authorization Header
    RewriteBase /helpdesk
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
</IfModule>

 

Note that we installed the HelpSpot code base outside of the web root for the main site.

The web root for example.org is found in /var/www/html while the web root for the HelpSpot installation is found within the HelpSpot code base at /var/www/helpspot. This prevents unauthorized access to HelpSpot code files so we don't, for example, make secrets available within the URL http://example.org/helpspot/.env, which could happen if the HelpSpot code files were installed into directory /var/www/html/helpspot.

 

 

CRON Configuration

HelpSpot requires some periodic tasks to be run. On Linux systems, these are powered by CRON.

The HelpSpot 5 code base include an example CRON configuration found in the file helpers/cron/helpspot. This file can be added to /etc/cron.d or the contents of it can be used to create a cron task using your preferred configuration.

There is just a single CRON task to use for HelpSpot 5:

# Timing    User       Command
* * * * *   www-data   cd /var/www/helpspot && /usr/bin/php hs schedule:run

You may need to adjust the system user that runs the task, as well as the above file paths as needed for your server. You can omit the user if you're installing this configuration into a user-specific crontab, for example if you're running the command sudo crontab -u www-data -e to run the cron task as user www-data.

The schedule:run command periodically runs other sub-commands which perform various tasks such as checking for new emails, cleaning out error log tables, sending email reports, running automation rules, and more.

Checking Email Mailboxes for new mail occurs every 1 minute by default, but a CRON expression can be used to change that timing by modifying the .env file and adding a MAIL_CRON_INTERVAL option:

# Default, check every one minute
MAIL_CRON_INTERVAL="* * * * *"

For example, to check email every 5 minutes, you can add the following to your .env file:

# Check mail every 5 minutes
MAIL_CRON_INTERVAL="*/5 * * * *"

You can also disable checking emails by editing the .env file and adding the following:

# Disable mail checks
AUTO_COLLECT_MAIL=false

You can then check email mailboxes directly using the following command (either manually or as a new CRON task):

# Check all mailboxes
php hs mail:check

# Check specific mailboxes
php hs mail:check --id=1
php hs mail:check --id=1,2,3

 

 

Queue Worker Configuration

HelpSpot uses a queue worker to process incoming and outgoing emails.

The command to process jobs in the queue worker is as follows:

php hs queue:listen database --queue=high,default --sleep=3 --tries=3

This command should be run in a way that restarts on failure and when the server is rebooted. To accomplish that, an "init" system such as Supervisord or Systemd should be used.

Supervisord is recommended as it allows you to run more than one queue worker process easily. We recommend running 2+ worker processes (2 of the above commands).

Systemd is available on most Linux systems without needing to install extra software. A limitation is that a service can only run one process, however as mentioned, we recommend running 2+ worker processes. This can be accomplished with 2 separate Systemd configurations if you choose.

The HelpSpot 5 code base comes with configuration examples for Supervisord and Systemd within the helpers/init directory.

 

Supervisord

You can install supervisord by running one of the following:

# Debian/Ubuntu
sudo apt-get install -y supervisor

# CentOS/RedHat/Fedora
sudo yum install -y supervisor
sudo systemctl enable supervisor
sudo systemctl start supervisor

If you are using the recommended Supervisord, the helpers/init/helpspot-supervisord.conf file can go into the /etc/supervisor/conf.d directory.

If that directory does not exist, the configuration can be copied into file /etc/supervisor/supervisor.conf or /etc/supervisord.conf (the exact path varies by Linux OS).

Be sure to edit the file if needed to change the user the service runs as, the log file path if required, and the number of worker processes to run (2+).

After placing the file, run:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start helpspot:*

As mentioned, you'll likely want to customize some configurations in the file:

  1. command: The command should be changed to use the correct file paths for the location of your HelpSpot installation
  2. user: The proper user should be configured to run the process, usually the same user that runs the PHP web server
  3. numprocs: The number of worker processes to run. We recommend starting with 2 and adding more if your HelpSpot installation monitors many Email Mailboxes.
  4. stdout_logfile: Adjust the log file path to a path of your choosing

 

Systemd

If you are using Systemd, the helpers/init/helpspot.service file can be placed in directory /etc/systemd/system/ or /lib/systemd/system/.

Note that we recommend using Supervisord instead of Systemd.

After placing the file, run:

sudo systemctl enable helpspot
sudo systemctl start helpspot

Note that you'll likely want to customize some configuration in the file:

  1. ExecStart: The command may need adjusting, for example if PHP is installed in a different location
  2. WorkingDirectory: The working directory should be adjusted to the path that HelpSpot is installed in
  3. User/Group: The proper user should be configured to run the process, usually the same user that runs the PHP web server

1.13. .env Config (Self Hosted)

HelpSpot Configuration

## Enable debugging output in the web front end
APP_DEBUG=false
## The base url of the HelpSpot application (without a trailing slash)
APP_URL=https://example.org

## Database type mysql or mssql
DB_CONNECTION=mysql
## The DNS name or IP of the database server
DB_HOST=localhost
## The port for the database server
DB_PORT=3306
## The database name for the helpspot database
DB_DATABASE=helpspot
## The database user name
DB_USERNAME=some_user
## The database user password
DB_PASSWORD=some_pass

## The selected queue driver. Database is default.
QUEUE_CONNECTION=database

Any other configuration setting you used to put into config.php can also be added into the .env file.

To convert old settings to new settings, you can use this formula:

Used to be this in config.php:

define('cHD_FOOBAR', 'some-value');

Can now be this within .env:

cHD_FOOBAR="some-value"

Secondary Portals

Secondary portals can optionally use their own .env file as well. If the Portal Path is, for example, /var/www/helpspot/public/some-portal, you can add a .env file to that path: /var/www/helpspot/public/some-portal/.env.

Any items added here will over-ride the settings from the main .env file configuration file.

If .env files are used in secondary portals, it will be important to configure the web server to not serve .env files if requested. Blocking requests for any "dot-file" (files that start with a period) is a common configuration:

Nginx:

## Disable access to all dot files, except for ".well-known",
## which is used for SSL generation
location ~* /\.(?!well-known\/) {
    deny all;
    access_log off;
    log_not_found off;
}

Apache:

## Disable access to all dot files, except for ".well-known",
## which is used for SSL generation
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_URI} "!(^|/)\.well-known/([^./]+./?)+$" [NC]
    RewriteCond %{SCRIPT_FILENAME} -d [OR]
    RewriteCond %{SCRIPT_FILENAME} -f
    RewriteRule "(^|/)\." - [F]
</IfModule>

The New Configuration File

The new configuration file (.env) looks like this:

APP_DEBUG=false
APP_URL=https://example.org

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=helpspot
DB_USERNAME=some_user
DB_PASSWORD=some_pass

QUEUE_CONNECTION=database

Maping old config to new config

The following configurations are no longer defined within a configuration file:

  • cDBCHARSET
  • cDBCOLLATION
  • SEARCH_ENGINE
  • cSEARCHHOST
  • cSEARCHPORT
  • cBASEPATH
  • cDATADIR

The following configurations map to the new configuration fields:

  • cDBTYPE => DB_CONNECTION (note that valid values now are mysql or sqlsrv - Value mssql for database type is no longer valid)
  • cDBHOSTNAME => DB_HOST
  • DB_PORT => This is a new value. Note that sqlserver value 127.0.0.1,1433 will need to be split into two values (hsotname and port are separate)
  • cDBUSERNAME => DB_USERNAME
  • cDBPASSWORD => DB_PASSWORD
  • cDBNAME => DB_DATABASE
  • cHOST => APP_URL
  • cDEBUG => APP_DEBUG

Fresh Installations

New installations can create a new .env file (or copy the .env.example file and replace values as needed).

Updates

We've provided a script to that reads the old config.php file (assuming it's located at C:\Program Files (x86)\helpspot\helpspot\config.php) and generates a .env file:

Working directory: C:\Program Files (x86)\helpspot\helpspot

Command: ..\php\php.exe -c ..\php\php.ini hs config:convert. This command creates (or over-write) file C:\Program Files (x86)\helpspot\helpspot\.env

For testing, you can run ..\php\php.exe -c ..\php\php.ini hs config:convert --dump to see the text output it would otherwise create.

Hidden Settings

Setting MAINTENANCE_MODE=true can be used within the .env file to force maintenance mode.

1.14. HelpSpot 5 Attachment Storage Location Change

Default attachment storage directory data/documents (e.g. /var/www/helpspot/data/documents has been moved to storage/documents (e.g. /var/www/helpspot/storage/documents.

For upgrades, you should:

  1. Move directories/files from data/documents into storage/documents
  2. Update HelpSpot's configuration to set the Admin > Settings > System > Attachment File System Directory to the storage/documents location, e.g. /var/www/helpspot/storage/documents

The data directory can be deleted in HelpSpot 5+.

1.15. HelpSpot 5 Admin Theme Changes

Helpspot 5 introduces a new admin / workspace interface. With this change comes changes to how admin area themes are handled. In the past, you would create a new admin theme and customize the js and css in order to apply your customization. Those admin themes now need to be migrated to the custom JS and CSS boxes found in Admin > Customize > Customize Admin.

CSS customization

The css customization setting will override default styles. So for example if you wanted to make the new request button green, you can target that element with a normal css class.

a.btn.newrequest {background-color: #65ac5d;}

JS customization

Javascript can be added for making programmatic changes to the HelpSpot admin area. JQuery is available under the $jq alias.

1.16. HelpSpot 5 Portal Changes

Form CSRF Fields

A number of portal templates need a csrf token added after the form tag  <?php echo csrf_field(); ?> for added security. These updates will need to be made to any portal files that have been customized. The addition needed in each file is highlighted and the surrounding code is provided for context.

kb.page.tpl.php

<form action="index.php?pg=vote.helpful" name="votehelpful" method="POST">
<input type="hidden" name="xPage" value="<?php echo $this->page['xPage'] ?>">
<?php echo csrf_field(); ?>
</form>
<form action="index.php?pg=vote.nothelpful" name="votenothelpful" method="POST">
<input type="hidden" name="xPage" value="<?php echo $this->page['xPage'] ?>">
<?php echo csrf_field(); ?>
</form>

login.forgot.tpl.php

<form action="<?php echo route('portal.password.email') ?>" method="post">
    <?php echo csrf_field(); ?>
    <?php if( session('status') ): ?>

login.reset.tpl.php

<form action="<?php echo cHOST.'/index.php?pg=login.reset' ?>" method="post">
    <?php echo csrf_field(); ?>
    <?php if( session('status') ): ?>

loginbar.tpl.php

<form onsubmit="return false;">
    <?php echo csrf_field(); ?>
    <table id="change_password_box" style="display:none;border:1px solid #ccc;padding:10px;margin-bottom:10px;">

request.check.tpl.php

<?php if (!empty($this->get_id)) : ?>
    <form action="index.php?pg=request.check" method="post" enctype="multipart/form-data">
        <?php echo csrf_field(); ?>
        <input type="hidden" name="accesskey" value="<?php echo $this->get_id ?>" />
...

<form action="index.php?pg=login" method="post">
      <?php echo csrf_field(); ?>
      <p><b><?php echo lg_portal_req_login ?>:</b></p>

request.tpl.php

<form action="index.php?pg=request" method="post" enctype="multipart/form-data">
    <?php echo csrf_field(); ?>

    <?php /* Any field names listed in the 'required' hidden field will be checked by HelpSpot to make sure they're not empty */ ?>
    <input type="hidden" name="required" value="sEmail,fullname" />

Request Check Page

The request check page has a new login / password reset flow. If you have customized this page you will need to make these additional edits.

request.check.tpl.php

Find this area:

    <form action="index.php?pg=login" method="post">
        <p><b><?php echo lg_portal_req_login ?>:</b></p>
        
        <p><label for="login_email" class="datalabel"><?php echo ($this->hd_requestCheckAuthType == "internal" ? lg_portal_req_loginemail : lg_portal_req_loginusername) ?></label><br />
            <?php echo $this->helper->showError('login_email','<br />') ?>
            <input type="text" name="login_email" id="login_email" size="40" maxlength="100" tabindex="102" value="<?php echo $this->get_login_email ?>" autocomplete="off" /><br />
            <?php if($this->hd_requestCheckAuthType == "internal"): ?>
            <?php //only show this password retrieval link if we're using internal authentication on the portal ?>
                <span id="retrievePortalPasswordLink">(<a href="#" onclick="RetrievePortalLoginPassword();return false;"><?php echo lg_portal_req_emailpassword ?></a>)</span>
            <?php endif; ?>
        </p>        

        <p><label for="login_password" class="datalabel"><?php echo lg_portal_req_loginpassword ?></label><br />
            <input type="password" name="login_password" id="login_password" size="40" maxlength="100" tabindex="103" value="" autocomplete="off" />
        </p>
        
        <p>
            <input type="submit" name="submit" value="<?php echo lg_portal_req_loginbutton ?>" tabindex="104" />
        </p>
    </form>

Replace it with this

    <form action="index.php?pg=login" method="post">
        <?php echo csrf_field(); ?>
        <p><b><?php echo lg('lg_portal_req_login') ?>:</b></p>

        <p><label for="login_email" class="datalabel"><?php echo $this->hd_requestCheckAuthType == 'internal' ? lg('lg_portal_req_loginemail') : lg('lg_portal_req_loginusername') ?></label><br />
            <?php echo $this->helper->showError('login_email', '<br />') ?>
            <input type="text" name="login_email" id="login_email" size="40" maxlength="100" value="<?php echo $this->get_login_email ?>" autocomplete="off" /><br />
        </p>

        <p><label for="login_password" class="datalabel"><?php echo lg('lg_portal_req_loginpassword') ?></label><br />
            <input type="password" name="login_password" id="login_password" size="40" maxlength="100" value="" autocomplete="off" />
        </p>

        <p>
            <input type="submit" name="submit" value="<?php echo lg('lg_portal_req_loginbutton') ?>" />
            <?php if ($this->hd_requestCheckAuthType == 'internal') : ?>
                <span style="padding: 14px 0px; display: inline-block;"><a href="index.php?pg=login.forgot"><?php echo lg('lg_portal_req_emailpassword') ?>?</a></span>
            <?php endif; ?>
        </p>
    </form>
    <div style="text-align: center;">
        <hr width="80%">
        <div style="margin: 0 auto; padding: 10px;">
            <?php if ($this->hd_requestCheckAuthType == 'internal') : ?>
                <?php //only show this password retrieval link if we're using internal authentication on the portal
                        ?>
                <a href="index.php?pg=login.create"><?php echo lg('lg_portal_req_logincreate') ?></a>
            <?php endif; ?>
        </div>
    </div>

CSS Changes

If you have customized your portal css (css.blue.tpl.php, css.grey.tpl.php etc) you will need to make these CSS changes in those customized files.

Calendar CSS changes to all portal template CSS files:

Remove:

@import "<?php echo $this->cf_primaryurl ?>/static/js/jscal2/css/jscal2.css";

Add:

/* Import styles for calendar used in date/datetime custom fields */
@import "cf_primaryurl ?>/static/js/datetimepicker/css/mobiscroll.jquery.min.css";
@import "cf_primaryurl ?>/static/js/popup/css/mobiscroll.jquery.min.css";

Add the following styles for file attachment display in requests.

.file-extension {
    display: inline-block;
    margin: 5px 0;
}
.file-name {
    display: inline-block;
    padding: 0 10px;
    margin-bottom: 5px;
}

JS Changes

If you have made JS customizations to js.tpl.php you will need to change this line:

document.write('<script type="text/javascript" src="<?php echo $this->cf_primaryurl.elixir('js/helpspot.portal.js') ?>"></script>');

to this:

document.write('<script type="text/javascript" src="<?php echo $this->cf_primaryurl.mix('static/js/helpspot.portal.js') ?>"></script>');

1.17. 508 Portal Template Changes

For HelpSpot v5 we've updated the portal themes to better accommodate section 508 compliance which makes it more accessible to people with disabilities.

The portals didn't need a lot of changes to make the necessary improvements but we wanted to highlight all that was required so you can adjust any portals that you may have customized.

The first main change was the colors in the CSS. The .required and .tag-sep classes need more contrasting colors to go with the backgrounds. For example, in the required class on the default portal, it had a color of red, and now this is changed to #b05050 which gives a better contrast on the white background.

The next change is all tabindex attributes have been removed from form fields, and all fields now have a proper id attribute and matching label.

Finally, in the footer, the search input needed a label.

Those are the primary changes if you'd like to update yours and to help you check your compliance there are a few browser plugins that will automatically check each page and give you a report. One of the most popular is called WAVE.

1.18. Language File Changes

HelpSpot 5 has updates and changes to the language files for the default language english-us.

The HelpSpot 5 code will have the latest language strings in the files located within the helpspot/helpspot/lang/english-us directory.

 

New Language Files

The following language files are new to HelpSpot 5:

  1. lg.pg.admin.customize.php
  2. lg.pg.admin.tools.jobsmgmt.php
  3. lg.pg.tips.php

 

Removed Language Files

The following language files were removed in HelpSpot 5:

  1. lg.pg.emailstaff.php
  2. lg.pg.forums.php
  3. lg.pg.getstarted.php

 

Updated Language Files

The following outlines language string changes, additions, and removals for each affected file. You can find all changes documented here.

2. Email Setup and Troubleshooting

2.1. Mailbox Setup - Microsoft / Office 365 Email Configuration

Office 365 (Exchange Online) email connections are now configured using the mail authentication flow instead of traditional IMAP and SMTP sending settings. Office 365 (Exchange Online) email is received and sent via Microsoft's API using oAUTH authentication. 

If you are migrating from existing IMAP and SMTP connections for your mailboxes, we recommend first disabling your old mailbox, then following the steps below to create a new mailbox connection.

Video Tutorial

Connecting an Office 365 Mailbox

Before beginning this process make sure that your browser is signed into the Office / Microsoft 365 mailbox that you wish to integrate with HelpSpot.

  1. Navigate to Admin > Email Mailboxes
  2. Select "Microsoft 365" from the menu


  3. Next enter the Reply to Email Account This is the email address that maps to this box ie: support@mydomain.com
  4. Click on the link to the HelpSpot email authentication service
  5. This will open a new tab. Select Sign in with Microsoft.


  6. Make sure that the email account listed on the permissions confirmation screen is the one that you want to integrate with HelpSpot.


  7. Next copy your credentials from the screen displayed.

  8. Enter the credentials provided back in your HelpSpot mailbox setup screen.


  9. Set any other options as desired and then select "Add Mailbox" at the bottom.
  10. Important! If you are using Office 365 for all of your mailboxes you will also need to go to Admin > Settings > Email Integration and select a configured mailbox your outgoing email in the "Send Outbound Email Via" setting.

Your Microsoft / Office 365 (Exchange Online) mailbox is now connected to HelpSpot.

 

2.2. Mailbox Setup - Google G Suite and Gmail Email Configuration

Google G Suite and Gmail Email Connections are now configured using the mail authentication flow instead of traditional IMAP and SMTP sending settings. Google Suite email is received and sent via Google's API using oAUTH authentication. 

If you are migrating from existing IMAP and SMTP connections for your mailboxes, we recommend first disabling your old mailbox, then following the steps below to create a new mailbox connection.

Connecting an Office 365 Mailbox

Before beginning this process make sure that your browser is signed into the Office / Microsoft 365 mailbox that you wish to integrate with HelpSpot.

  1. Navigate to Admin > Email Mailboxes
  2. Select "Google" from the menu



  3. Next enter the Reply to Email Account This is the email address that maps to this box ie: support@mydomain.com
  4. Click on the link to the HelpSpot email authentication service
  5. This will open a new tab. Select Sign in with Google.


  6. Make sure that the email account listed on the permissions confirmation screen is the one that you want to integrate with HelpSpot. Also ensure that the bottom two checkboxes are checked if provided.


  7. Next copy your credentials from the screen displayed.

  8. Enter the credentials provided back in your HelpSpot mailbox setup screen.

  9. Set any other options as desired and then select "Add Mailbox" at the bottom.
  10. If you are setting up your default mailbox you will also want to got to Admin > Settings > Email Integration and select your new mailbox as the default sending option.

Your Google Suite / Gmail mailbox is now connected to HelpSpot.

2.3. Legacy Mailbox Setup - Office 365 IMAP/SMTP

IMAP/SMTP settings can be used for Office 365 mailbox setup. However, we now recommend using HelpSpot's API integration with Office 365 as Microsoft will soon be disabling IMAP and SMTP basic authentication functionality.

Please note, before beginning that IMAP must be enabled for the Office 365 Mailbox you want to connect to HelpSpot. This can be done via the Exchange Online Remote Powershell (https://support.microsoft.com/en-us/kb/2416434) or via the web based exchange admin tools. Once your mailbox is setup properly:

 

  1. Login to HelpSpot as an Administrator.
  2. Navigate to Admin > Email Mailboxes
  3. Enter your account information. The non-account specific information is as follows: 
    Hostname: outlook.office365.com 
    Account Type: IMAPS 
    Port: 993 
    Security Type: SSL no-validate
  4. Test your mailbox settings to make sure that your inbound connection is successful
  5. Next select Custom for the Outgoing Email SMTP Settings to use
  6. The non-account specific connection information for SMTP is as follows: 
    SMTP Security Protocol: TLS 
    SMTP Host: smtp.office365.com
    SMTP Port: 587 
    Use SMTP Authentication: Yes 

 

O365

2.4. Legacy Mailbox Setup - G Suite IMAP/SMTP

Because of G Suite's security system, you first need to prep your mailbox for integration with HelpSpot. Here is a guide to the settings that need to be setup before hand. Some of these may be already configured depending on your environment.  If so you can proceed to step 4.

1. Enable Imap Access

  1. Go to https://admin.google.com and login with a G Suite admin account
  2. From the Admin console dashboard, go to Apps > G Suite > Gmail > Advanced settings.

    Tip: To see Advanced settings, scroll to the bottom of the Gmail page.

  3. In the Organizations section, select the organizational unit for which you want to configure settings.
  4. Under POP and IMAP Access, clear the check box for Disable POP and IMAP access for all users in the domain.
It may take up to one hour for IMAP and POP changes to take effect. As long as the box is cleared, users can configure POP and IMAP access for a host of clients.

2. Turn on access for "less secure apps"

  1. Go to https://admin.google.com and login with a G Suite admin account
  2. Click Security > Basic settings.
  3. Under Less secure apps, select Go to settings for less secure apps.
  4. In the subwindow, select the Allow users to manage their access to less secure apps radio button.

3. Toggle access for less secure apps on your G Suite account

  1. Go to the "Less secure apps" section in My Account.
  2. Next to "Access for less secure apps," select Turn on.

4. Setup Your Mailbox In HelpSpot

  1. Login to HelpSpot as an Adminstrator.
  2. Navigate to Admin > Email Mailboxes
  3. Enter your account information. The non-account specific information is as follows:
    Hostname: imap.gmail.com
    Account Type: IMAPS
    Port: 993
    Security Type: SSL no-validate
  4. Test your mailbox settings to make sure that your inbound connection is successful
  5. Next select Custom for the Outgoing Email SMTP Settings to use
  6. The non-account specific connection information for SMTP is as follows:
    SMTP Security Protocol: TLS
    SMTP Host: smtp.gmail.com
    SMTP Port: 587
    Use SMTP Authentication: Yes

2.5. Handling Large Email File Attachments

To properly handle large file attachments it is often necessary to modify settings in your HelpSpot, PHP.ini file and database configuration.

HelpSpot Settings

Admin->Settings->Email Integration->Max Attachment Size - This defaults to 10mb. If you need to handle larger sizes, you'll first need to increase this setting.

PHP.ini Values to Review

memory_limit - PHP may require more memory to import large files then it has available. Increasing this value will give PHP more memory to use. 60mb has proven to be a good value for this variable if you want to handle attachments up to about 10mb.

max_execution_time - The time PHP has to execute a script. If you're downloading large files from across the internet, you may need more time.

upload_max_filesize - The maximum size a file upload can be. This affects files staff try to upload to attach to emails.

post_max_size - The maximum size an HTTP POST request can be, this can limit the maximum size a file can be when uploading files to attach to emails.

upload_tmp_dir - The directory uploaded files are temporarily stored in during transmission. If no attachments of any size are able to be uploaded then this value may be unset or set to a directory which is not writable by the web server.

Database Settings

MySQL: max_allowed_packet - On MySQL, increase the max packet size to greater than the biggest files you expect to handle. This is done in the MySQL configuration file. See your MySQL documentation for specific instructions for your version.

IIS Settings

IIS has a maximum content length setting that can affect the ability to upload / attach files. Here's how you can check that:

  1. Open IIS Manager.
  2. Select the website that you want to configure.
  3. Make sure you are in Features View per the button at the bottom of the manager.
  4. Select Requests Filtering and open it by double-clicking the icon. The Request Filtering pane displays.
  5. From the Actions pane on the right hand side of the screen click Edit Feature Settings... link. The Edit Request Filtering Settings window displays.
  6. In the Request Limits section, enter the appropriate Maximum allowed content length (Bytes) and then click the OK button.
  7. Restart IIS.

NGINX Settings

NGINX has a client_max_body_size that can prevent larger attachments if the value is set too low.

 

3. HelpSpot Mobile Apps

3.1. Setup for Mobile Applications

HelpSpot has both iOS (iPhone / iPad) and Android mobile applications available.

HelpSpot Requirements:

For HelpSpot, these require that:

  1. You use HelpSpot version 4 or greater.
  2. The Private API be enabled within the Admin > Settings > Web Services API configuration.

Login To Mobile App

Since the mobile app connects to your instance of helpspot you will need the URL of your helpspot site the first time you login to the mobile app.

  1. Open the mobile app
  2. Enter the URL to your helpspot instance. For example https://helpspot.yourdomain.com
  3. Enter your username and password

If you encounter issues logging in. Visit our troubleshooting guide.

3.2. Troubleshooting

"HelpSpot Could Not Be Reached" error

There are a few possible reasons why HelpSpot may return the "HelpSpot could not be reached error:

  1. HelpSpot's private API is not enabled
  2. iOS/Android limitations in connecting over "https"
  3. Server does not allow or support HTTP Basic Authorization

Private API

Please be sure to enable HelpSpot's Private API from within the Admin > Settings > Web Services API configuration.

HTTPS and SSL Certificates

If the private API is enabled and you continue to receive an error, you may have an SSL certificate configuration that supports too few secure protocols. For example, Apple's iOS version 9 may only support TLS1.2, but a web server's SSL certificate may only support or enable TLS1.0.

We suggest following these configurations for a secure and functional SSL configuration.

If you are curious about your site's SSL configuration, you can run it through this SSL Certificate tester, which will inform you of any potential issues in your SSL configuration.

Basic Authentication

HelpSpot's API's are authenticated against use HTTP Basic Authentication.

  • Some servers may prevent this type of authentications, perhaps by removing an incoming request's Authorization header.
  • Apache servers running PHP as fast-cgi will not pass basic authentication from Apache to PHP.
  • Nginx users may find that the "auth_basic" setting has been used either in their Nginx configuration. A setting of "auth_basic off;" would prevent the HelpSpot mobile applications from being able to authenticate against HelpSpot.

4. Authentication

4.1. Office 365 / Azure SAML Authentication

Make sure the staff configured within HelpSpot have a " setup matching their Office365 email addresses in their HelpSpot staff profiles.

You also may want to enable SAML Debugging before enabling SAML for the first time.

Office365 Setup

  1. Go to https://aad.portal.azure.com and click on enterprise applications.
  2. We'll create a "non-gallery" application.
    1. Select "New Application"
    2. Select "Create your own application"
    3. Give the application a name, and keep the default option "Integrate any other application you don't find in the gallery"
  3. After the app is created:
    1. Select single sign on and then choose SAML for the sign on type.
    2. Edit step 1 "Basic SAML Configuration" and enter an Identifier (Entity ID) found in HelpSpot Admin > Settings > Authentication > SAML2.0.
    3. Enter the Reply URL (Assertion Consumer Service URL) (also know as ASC URL) that is found in HelpSpot Admin > Settings > Authentication > SAML2.0
    4. Save your settings
  4. Still within the application settings, head to Users and group and choose Add User to add users or role who may authenticate into HelpSpot

HelpSpot Setup

  1. After completing the above, and saving the settings, step 3 on the SAML setup page should update with more information.
    1. Download the Federation Metadata XML file. In this file, you will find the <X509Certificate> tag. Copy the value that is between the <X509Certificate> and </X509Certificate> tags. Paste this value into Certificate field in HelpSpot Admin > Settings > Authentication > SAML2.0.
  2. Move down to step 4 is the azure SAML setup page and copy the Login URL to the Login URL (SSO) in the HelpSpot SAML setup page.
  3. Copy the Logout URL to the Logout URL (SLO) in the HelpSpot SAML setup page.
  4. Copy the Azure AD Identifier to the Entity ID in the HelpSpot SAML setup page
  5. Save your settings in HelpSpot and then head back to the Azure SAML setup page and validate your single sign-on with SAML
 

4.2. Google Suite SAML Authentication

Make sure the staff configured within HelpSpot have a " setup matching their Office365 email addresses in their HelpSpot staff profiles.

You also may want to enable SAML Debugging before enabling SAML for the first time.

Within Google admin for your organization:

  1. Head into the menu > Apps > SAML Apps
  2. Click the blue Add a service/app to your domain link.
  3. Choose "setup my own custom app".
  4. Copy the Google IdP information, and download the certificate (https://d.pr/i/OGcx0h). We will use this in HelpSpot under Admin > Settings > Authentication.
  5. Add the Basic Information for your application (the name and description is arbitrary) (https://d.pr/i/NHTMOu)
  6. Add the IdP information from the HelpSpot Admin > Settings > Authentication section into the Gsuite admin (https://d.pr/i/duEPpx)
  7. Click "Next" to skip attribute mapping (https://d.pr/i/PFkLjS)
  8. Close the confirmation window telling you to "upload" the SAML information, and be sure to add the info from step 6 if you have not done so.
  9. Choose "User Access" to enable users from a domain to use the SAML application (https://d.pr/i/R9gAuq)
    • It defaults to being "OFF for everyone"
  10. It should then be "ON for everyone" (or similar) (https://d.pr/i/SRSJS2)
  11. In HelpSpot navigate to Admin > Settings > Authentication.
  12. Select SAML authentication and enter the Entity ID, SSO URL and copy the certificate contents into the HelpSpot settings.

SAML should then function within HelpSpot.

4.3. Two Factor Authentication (2fa) Support

Helpspot supports native 2fa authentication for staff members when using HelpSpot's internal authentication. To enable this option, follow these steps:

  1. Navigate to your user preferences:
  2. Select "Enable Two Factor Authentication"
  3. You can then scan the displayed QR code with your authenticator app such as Google Authenticator, 1Password, Microsoft Authenticator or Authy. Alternatively, if you don't have a device that can scan QR codes you can manually enter the key in your authenticator app.
  4. After doing this, enter the enter the code from your authenticator app to confirm the key. Two factor authentication will not be enabled on your account until the key is confirmed.

After enabling 2fa authentication you will be prompted to enter your login code whenever you authenticate to HelpSpot. Administrators can disabled 2fa authentication to unlock accounts.

Enabling 2fa will also disable basic authentication on the API. API keys will need to be used for any API interactions.

4.4. Black Box Authentication (agent login) with Active Directory

These instructions should work with most Active Directory installations, however, minor adjustments may need to be made to fit your exact setup.

  • Download the Active Directory/PHP Helper library from http://adldap.sourceforge.net/
  • Unpack the download and place the adLDAP library files (as of this writing, the 'adLDAP.php' file and the 'classes' and 'collections' directories) into the /custom_code folder of your HelpSpot installation.
  • Open adLDAP.php in a text editor. Around line 82 there starts a few variables you'll need to modify so that an AD connection can be made to your AD server. You'll likely need to modify at least $accountSuffix , $baseDn, and $domainControllers variables. When finished save the file.
  • Copy the file /custom_code/BlackBox-base.php to /custom_code/BlackBox.php
  • Open BlackBox.php in a text editor. Replace the BlackBox function with this code (sample file also available at the bottom of this page):
    //include the class
    require_once("adLDAP.php");
    	
    function BlackBox($username, $password){
    	
    	//create the AD LDAP connection
    	$adldap = new adLDAP();
    
    	//authenticate a user
    	if ($adldap->authenticate($username,$password)){
    		return true;
    	}else{
    		return false;
    	}
    
    }
    
  • Login to HelpSpot and go to Settings in the upper right hand corner. Make sure the 'Black Box Username' field contains your Active Directory username or you will not be able to login. Every other user must also have this field filled in or they will not be able to login. You don't need to enter them all right now though.
  • Go to Admin->Settings and under 'Authentication' select 'Black Box'. Save the settings and Black Box/Active Directory authentication will be enabled. You should log out, if the system doesn't do it for you and attempt to login with your Active Directory username and password.

4.5. Black Box Authentication (agent login)

Black box authentication allows you to integrate your organizations authentication system with HelpSpot. Configuration requires only a few simple steps.

Summary: Steps to enable BlackBox Authentication

  • Customize the BlackBox function in the file /custom_code/BlackBox-base.php to authenticate the username and password passed to it against your own authentication system.
  • Rename BlackBox-base.php to BlackBox.php
  • Confirm that your staff has the "Black Box Username" field set correctly in their accounts.
  • Enable Black Box authentication in Admin->Settings

Customizing the BlackBox function

In the root of your installation there's a folder called /custom_code. Within that folder is the BlackBox-base.php file. This file contains the empty BlackBox function:

function BlackBox($username, $password){

	/* DO YOUR AUTHENTICATION HERE */

	return false;

}

Customize this function to do authentication against your internal system by using the username and password provided. Here is an example of the function customized to authenticate against a MySQL database: (some security procedures left out for clarity)

function BlackBox($username, $password){

       $dblink = mysql_connect('localhost', 'mysql_user', 'mysql_password');
       mysql_select_db('database', $dblink);
       
       $username = mysql_real_escape_string($username);
       $password = mysql_real_escape_string($password);

       $result = mysql_query("SELECT userid 
       						  FROM users 
       						  WHERE users = '$username' AND pass = '$password'", $dblink);
       $num_rows = mysql_num_rows($result);

       if($num_rows == 1){
			return true;
       }else{
			return false;
       }
}

Returning true will authenticate the user, while false denies access. Note that even after you return true, HelpSpot looks up the username to make sure the username is that of a valid HelpSpot user. If you have not assigned the username to any of your staff then authentication will still fail.

Enabling Black Box Authentication

Before enabling check each account account that will be impacted by this authentication changes to make sure they have "black blox username" set. If they do not, they will not be able to login.

Enabling Black Box authentication is a two step process. First you must rename the BlackBox-base.php file to BlackBox.php. Second, you must change the authentication type to Black Box [Admin->Settings]. After changing the setting you will likely have to login again at which point the login box should say "username" instead of "email".

HelpSpot Password

HelpSpot still requires a password for all accounts even though it's not used for your custom authentication. This is because HelpSpot will attempt to login against it's own internal authentication when your custom authentication returns false. This allows users to get into HelpSpot even if the custom function is not working correctly using their HelpSpot email and password.

4.6. Black Box Portal Authentication (customer portal login)

Black box authentication allows you to integrate your organizations authentication system with HelpSpot. Configuration requires only a few simple steps.

Summary: Steps to enable BlackBox Authentication

  • Customize the BlackBox function in the file /custom_code/BlackBoxPortal-base.php to authenticate the username and password passed to it against your own authentication system.
  • Rename BlackBoxPortal-base.php to BlackBoxPortal.php
  • Enable Black Box authentication in Admin->Settings->Portal->Request History Login Type

Customizing the BlackBox function

In the root of your installation there's a folder called /custom_code. Within that folder is the BlackBoxPortal-base.php file. This file contains the empty BlackBox function:

function BlackBoxPortal($username, $password){

	/* 
		DO YOUR AUTHENTICATION HERE 
		
		Here's an example of how to return a valid user:
		return "john.smith@company.com";
	*/

	return false;

}

Customize this function to do authentication against your internal system by using the username and password provided. Here is an example of the function customized to authenticate against a MySQL database: (some security procedures left out for clarity)

function BlackBoxPortal($username, $password){

       $dblink = mysql_connect('localhost', 'mysql_user', 'mysql_password');
       mysql_select_db('database', $dblink);

       $username = mysql_real_escape_string($username);
       $password = mysql_real_escape_string($password);

       $result = mysql_query("SELECT email FROM users WHERE users = '$username' AND pass = '$password'", $dblink);
       $num_rows = mysql_num_rows($result);

       if(mysql_num_rows($result) == 1){
              $row = mysql_fetch_assoc($result);
              //An email must be returned
              return $row['email']; 
       }else{
              return false;
       }
}

Returning an email will authenticate the user and show them any requests for that email, while false denies access.

Using LDAP with Portal BlackBox authentication

Just like with the Staff BlackBox authentication, you can use LDAP. However, because HelpSpot needs an email address returned upon successful authentication (instead of simply "true"), we need to do a little more work. Using the above LDAP library, you can query the LDAP server for the user information. This usually contains an email address associated with the account (however that may change depending on your LDAP server).

To get started, follow the instructions on downloading the LDAP library. Then create the BlackBoxPortal.php file. The following is some sample code which shows retrieving a users email address from the LDAP server if they successfully authenticate.

 

require_once("adLDAP.php");

function BlackBoxPortal($username, $password){
 
    //create the AD LDAP connection
    $adldap = new adLDAP();
 
    //authenticate a user
    if ($adldap->authenticate($username,$password))
    {
        $userinfo = $adldap->user()->info( $username, array("mail","displayname"));
        return $userinfo[0]["mail"][0];
    }else{
        return false;
    }
 
}

4.7. SAML Debugging

** These notes are for self-hosted customers only. HelpSpot Cloud customers will need to contact support **

If you become locked out of your SAML authenticated HelpSpot server you can enable a debugging mode to use local accounts to login and change SAML settings.

  1. Edit the .env file located in your HelpSpot directory
  2. Change APP_DEBUG=true and save the file
  3. In your browser navigate to https://myhelpspotsite.com/altlogin
  4. You will then be presented with a local authentication form to temporarily authenticate to the admin area

4.8. SAML User Login Redirects to Portal Instead of Admin Workspace

When SAML authentication is enabled HelpSpot will search the "Black Box/LDAP/AD/SAML Username" field of the staff profiles to find a matching profile. If no matching profile is found, the user will be redirected back to the customer portal.

To correct this issue follow these steps:

  1. Navigate to Admin > Staff  and select the staff member.
  2. Update or add the correct "Black Box/LDAP/AD/SAML Username" value to that account. In most cases this will be the users email address.

5. System Administration

5.1. HelpSpot Command Line Tool

Commands Available

HelpSpot 5 has some new commands available, along with most commands from HelpSpot 4.

HelpSpot includes an hs command that can be used to run or automate certain tasks.

Linux:

The hs command installed with HelpSpot is the command line utility. On Linux servers, you can run it using PHP:

# List the available commands and options:
php hs

Windows:

On Windows, you need to run the hs command using the PHP that comes with HelpSpot using Cmd or PowerShell, and let it know which configuration file to use:

C:\'Program Files (x86)'\helpspot\php\php.exe -c C:\'Program Files (x86)'\helpspot\php\php.ini C:\'Program Files (x86)'\helpspot\helpspot\hs

It might be easier to first "change directory" into the HelpSpot directory so these file paths are shorter:

cd C:\'Program Files (x86)'\helpspot\helpspot
..\php\php.exe -c ..\php\php.ini .\hs

For both Linux and Windows, running hs without any parameters will simply list out the available commands.

Command Details

Each command has a list of options you can pass to it. To see the details of available flags, use the -h flag:

php hs install -h
Description:
  Install HelpSpot.

Usage:
  install [options]

Options:
      --agree                                    Agree to HelpSpots License Terms
      --name[=NAME]                              Full Name (first name last name)
      --admin-email[=ADMIN-EMAIL]                Admin User Email Address
...and so on

Available Commands

Here are the commands available for HelpSpot:

  • install
  • update
  • attachments:tofile
  • automation:rules
  • cache:clear
  • config:convert
  • mail:check
  • portal:migrate
  • request:delete
  • request:delete-spam
  • request:delete-trash
  • report:logs

install

This will guide you through installing HelpSpot. For installing without prompts, you can use the available flags to provide the needed details.

# Interactive
php hs install


# Or prefill some or all options
php hs install --agree --name="Jane Doe" --admin-email="jane@example.com" --password="secret" ...and so on

update

To update between HelpSpot 5 versions (e.g. 5.1.0 to 5.2.0), use the update command.

# Update with prompt
php hs update

# Update with no prompt
php hs update --yes

The update command is safe to run multiple times (don't worry about accidentally running it).

attachments:tofile

This command will allow you to save your file attachments from the database (the default location prior to HelpSpot version 4) to your server file system.

This command will delete file data from your database as it saves it to the disk. We highly suggest backing up your database before running this command.

# Prompted for attachment file path to use
php hs attachments:tofile

# Or provide the file attachment path:
php hs attachments:tofile --path=storage/documents

automation:rules

You can run all Automation Rules, or specific Automation Rules by their ID. Their ID is found within HelpSpot when viewing the list of Automation Rules.

# Run all automation rules
# Except those marked to run on a Custom Schedule
php hs automation:rules

# Run automation rule 1
# regardless of Custom Schedule setting
php hs automation:rules --id=1

# Run automation rule 1 and 2
# regardless of Custom Schedule setting
php hs automation:rules --id=1,2

cache:clear

HelpSpot uses some caching to save certain settings, configuration, and data to reduce database load. To clear the cache, you can run the following command:

php hs cache:clear

config:convert

When updating from HelpSpot 4 to HelpSpot 5, the config.php file can be converted to a .env file using this command:

# Assumes config.php file is present

# Create a .env file from config.php file values
php hs config:convert

# Print the contents of the converted configuration
# but do not create the .env file
php hs config:convert --dump

mail:check

HelpSpot runs this command periodically via it's CRON task (Linux) or Scheduled Tasks (Windows).

This command fires off a queue job, which in turns checks configured/enabled mailboxes for new email.

You can check all Mailboxes, or specific Mailboxes by their ID. Their ID is found within HelpSpot when viewing the list of Email Mailboxes.

# Check all configured/enabled mailboxes
php hs mail:check

# Check mailbox id 1
php hs mail:check --id=1

# Check mailbox id 1 and 2
php hs mail:check --id=1,2

portal:migrate

This command will help move existing portals from the old HelpSpot 4 location to one appropriate for HelpSpot 5.

# Move portals, if it can
php hs portal:migrate

# Report on what changes the command would make
# but don't make the changes
php hs portal:migrate --dry-run

request:delete (-spam,-trash)

You can delete one specific request (and it's related data) by its ID:

# Delete request 1234
php hs request:delete --id=1234

You can delete all Spam as well, without using those requests to train the spam filter:

# Delete all spam, with prompt
php hs request:delete-spam

# Delete without prompting
php hs requets:delete-spam --force

And you can delete requests in the Trash:

# No prompt, deletes trash.
# Does use the Trash Delete Delay setting
php hs request:delete-trash

Report: Logs

The report:logs command will export a CSV file of your helpspot request event logs to your data/documents/ directory.

php hs report:logs
 

5.2. How to Backup HelpSpot

HelpSpot stores all it's data in the database, this makes backing up HelpSpot very easy. To have a complete backup of all your data simply backup the database using standard database backup procedures. These will vary depending on which database system you use, though it's likely your system administrators are already doing it or can have it done easily.

Systems Using an Alternate Attachment Storage Location

For systems that handle many email attachments HelpSpot has a setting (Admin->Settings->System->Attachment Storage Location) to allow attachments to be stored on the servers disks rather than in the database. This is more efficient and makes backup of the database much easier because the size of the database is much smaller.

If your installation uses this feature you'll also need to backup the attachments which are on disk in order to have a complete backup.

HelpSpot Files

It's optional to backup the HelpSpot files themselves. You can always re-download them if you need to, but if you do want to backup the files be sure to do so in a binary safe manner as all the .PHP files in HelpSpot are binary.

Even if you don't backup all the files you may want to keep a backup of config.php which stores the database connection settings as a convenience in case a recovery is needed. This file is in the root HelpSpot folder.

Restoring

To restore your HelpSpot installation follow your databases standard restoration procedure. Restore the HelpSpot files (if necessary), replace config.php or rebuild it (if necessary) and your installation should be up and running.

Some database specific backup resources:

 

5.3. How to Move HelpSpot

How you move a HelpSpot installation is dependent upon how it was initially installed. The instructions differ based on if the installation was first installed manually or via the Windows Installer. Instructions for moving both types of installation methods are provided below.

Moving a Manually Installed Installation

Moving a manual installation is much like doing a backup. These instructions presume you've already setup a proper environment on the new server, PHP, database, web server, etc.

  • Put the old system in maintenance mode (Admin->System Overview) to prevent any requests being created in there via email or portal form.
  • Backup the database: How to Backup HelpSpot
  • Restore the database on the new server (this presumes you're moving the database. If the database is not moving then skip this)
  • Copy the HelpSpot files to the new server, be sure to move in a binary safe manner
  • On the new server edit .env in the root HelpSpot folder to be sure it includes the proper database connection information and correct APP_URL for the new location
  • On the new server setup the queue worker and cron jobs.
Your new installation should now be available. Check that the system is running correctly and you can take the old system offline.

Moving a Windows Installer Installation

The easiest way to move an installation done via the Windows Installer is to use the installer again to re-install on the new server and then move the database.

  • Run the Windows Installer on the new server, allow it to create a new empty database in SQL Server or MySQL. No need to run installer.php when it pops up.
  • Place your old server into maintenance mode.
  • Backup your old servers database
  • Restore your database, overwriting the new one the installer just created
Your new installation should now be working. Be sure to uninstall your old installation or at least turn off the scheduled tasks so that no emails are imported into the old installation.

Other Considerations

Attachments Saved to Disk - If you've configured HelpSpot to save attachments to the file system (Admin->Settings->System->Attachment Storage Location), then you'll need to move those files as well and update the file path to them in the new servers settings.

Upgrading While Moving - If on the new server you're using a newer version of HelpSpot files than the old server was running then after the move you'll need to run installer.php to upgrade the HelpSpot database. This can only be done inside of major versions. You must use the documented upgrade process to move from v3 to v4 or v4 to v5.

5.4. Moving HelpSpot 5 Windows Installations

To move a windows installation from one server to another, first take an assessment of your current system environment.

  • Database Platform: MySQL or SQL Server? - You can determine this by opening the .env file in your current environment and noting the DB_CONNECTION value
  • Database Location: Application server or external? - You can determine this by opening the .env file in your current environment and noting the DB_HOST value. If the value is "localhost" or "127.0.0.1" then the database is co-located with the application server. If you have a connection to an external IP or DNS then the db is most likely external and won't need to be moved along with the application server.
  • Web Server: Apache or IIS? - Determine if you are using IIS or Apache to host your helpspot instance. You may want to open the "IIS Manager" tool in windows to look for a helpspot site and check your helpspot install location to see if Apache has been installed.

Install HelpSpot on Your New Server

  1. Follow the standard windows installation instructions as if you were installing a new server: https://support.helpspot.com/index.php?pg=kb.page&id=648. You can install the latest version of HelpSpot 5 even if your current installation is on an older version of HelpSpot 5. The moving process will also update your instance.
  2. This guide will direct you to install HelpSpot using IIS and Microsoft SQL Server. If you determined above that you are using MySQL, you will need to modify your installation .env to connect to your mysql server. You will also need to enable the mysql extensions in your php.ini file.
  3. It can be good to just login and make sure that you new server is all configured and functional before starting to move your data.

Migrate The Database

  1. Place your old server in maintenance mode. This will prevent the old server from performing database changes during migration.
  2. If you determined that your database location is on the Application server you will need to make a backup of that database and import it into your new database server. Standard MySQL or SQL Server backup and restore tools can be used. This article include links for database backup tool instructions (specific links at bottom): https://support.helpspot.com/index.php?pg=kb.page&id=315
  3. Update the connection information in the .env file on you new server to connect to your migrated database. If your database server location is external your can simply update the connection information in the new server's env file with the parameters from your old server's .env.

Copy The Application Key

  1. Copy the APP_KEY setting located .env file on you old server to your new server. This is needed to decrypt values in the migrated database.

Copy Files

  1. Copy the files in these locations on your old installation to the corresponding location on your new installation. (Locations listed here are relative to the directory your .env file is located in):
    helpspot/storage/*
    helpspot/public/custom_code/*
    helpspot/public/custom_templates/*
    helpspot/helpspot/custom_pages
  2. If you have created a custom language pack you will need to copy that language pack over.
  3. If you have created secondary portals, those portal directories will need to be copied over.

Update HelpSpot

  1. Open a command prompt on your new server and cd to your helpspot directory: cd c:\inetpub\wwwroot\helpspot
  2. Run the helpspot update command: C:\php\php.exe hs update

This will move your HelpSpot installation. You may need to make DNS and webserver binding and certificate changes to direct users to the new location.

5.5. Removing virtual directory in HelpSpot on IIS

By default, HelpSpot will install as a virtual directory in IIS. This means that if you install it into your site example.com, HelpSpot will appear as a virtual directory "/helpspot", making it accessible at example.com/helpspot.

If you want to use HelpSpot in the root of a domain (perhaps support.helpspot.com), you can "move" HelpSpot out of the virtual directory and into a website in IIS.

5.6. Removing /helpspot directory in URL on Windows / Apache

This video tutorial walks through how to remove the /helpspot directory from the HelpSpot application path on a Windows / Apache installation.

5.7. Connecting To A Network File Share For Attachment Storage

HelpSpot installs based on IIS can be configured to store their attachments on a network file share allowing the file storage duties to be offloaded from the application server. IIS needs to be configured properly to allow it to write to network file systems.

  1. Open the IIS Manager
  2. Find your app pool for HelpSpot and open up the advanced settings
  3. Set the identity to a user that has access to the local helpspot install and to the network file share you plan on using

  4. Open up your website in the IIS manager and select the authentication options.
  5. Edit the anonymous authentication settings and select the application pool identity.
  6. Restart IIS
  7. Go your HelpSpot admin screen and click on settings
  8. Edit the attachment file system directory setting to point at the UNC path of your file store
  9. When you save the settings HelpSpot will verify that it can write to that directory
  10. Migrate your existing files to that new file store location.

5.8. Enabling SSL in Apache on Windows

SSL for HelpSpot can be enabled on windows based installations, but it does require some configuration. This document will not cover in detail how to create a CSR or obtain certs in the proper format for Apache as this varies based on the certificate provider. This documents will assume that a Apache compatible cert, certificate chain and key have been obtained. It is intended as a general guide and the exact set up for a specific installation may vary.

Editing the Apache configuration files

  1. Backup your C:\Program Files (x86)\helpspot\apache\conf\ directory.

  2. Place your certificate, certificate chain and key in the C:\Program Files (x86)\helpspot\apache\conf\directory.

  3. Navigate to C:\Program Files (x86)\helpspot\apache\conf\ and edit the httpd.conf file as follows. Uncomment (remove the #) these lines: 
    LoadModule socache_shmcb_module modules/mod_socache_shmcb.so
     

    LoadModule ssl_module modules/mod_ssl.so
     

    Include conf/extra/httpd-ssl.conf

  4. Edit the C:\Program Files (x86)\helpspot\apache\conf\extra\httpd-ssl.conf In the most basic setup you will need to verify / edit these paths:
    SSLCertificateFile "${SRVROOT}/conf/cert.pem"


    SSLCertificateKeyFile "${SRVROOT}/conf/cert.key"
     

    Most certificate will also need a chain file. 

    SSLCertificateChainFile "${SRVROOT}/conf/server-ca.crt"

  5. Now restart your HelpSpot Apache service in the windows services area. If service does not start up, we recommend running C:\Program Files (x86)\helpspot\apache\bin\httpd.exe from the command line to obtain useful error output.

  6. Once you have a working configuration make sure to take a new backup of the  C:\Program Files (x86)\helpspot\apache\conf\  directory. This backup can be used to restore changes after a HelpSpot upgrade.


5.9. HelpSpot Limits

HelpSpot has several built in limits on record counts and various other operations to ensure good performance and prevent mis-configuration from negatively impacting the system operation. Some of these limits can be adjusted on self-hosted instances using configuration variables.

  • Max Note Size - Each not in a request is limited to 70,000 UTF8 characters.
  • Max Request History Records - Each request is limited to 1,500 request history items. When this limit is reached a notice will be displayed staff members alerting them to the issue. This limit is configurable via the cHD_MAX_REQUEST_HISTORY setting in the HS_Settings table.
  • Full Text Searches In Filters - Full text searches in filters are limited to 5,000 results
  • Automation Rule Matches - Automation rule can be run on a individual request for a maximum of 50 times.  This limit is configurable via the cHD_MAX_AUTO_RUNS setting in the HS_Settings table.
  • Custom Field Creation - Creation of custom fields is theoretically limited on MySQL based installations by the maximum column count of the InnoDB storage engine.
  • Filter Date Limit - The Filter Within Previous (days) setting found in Admin > Settings limits the number of days back a filter searches for records. By default this is set to 365. You can change this setting in the settings area or you can add a date criteria to your filter to override the default limit.
  • Max Results to Display - The Max Results to Display setting found in Admin > Settings limits the maximum number of requests shown in filters and search results sets.

5.10. .env Configuration Options

The .env file on self hosted installations controls much of how HelpSpot runs at a global level. The standard settings are setup during installation but there are additional settings that can be configured if needed. All environment variables are entered into the .env file in this format: env_var_name="value"

  • SECURITY_FRAME_OPTIONS - Controls the x-frame-options http header.
    • Default: SAMEORIGIN.
    • Values: SAMEORIGIN, DENY, ""
  • CUSTOM_CSP - inserts custom CSP domains to be allowed in the admin area.
    • Default: null
    • Values: "yoururl.com"
  • FORCE_HTTPS - Forces all URLs to be built using the https protocol
    • Default: false
    • Values: true, false
  •  DISABLE_CSRF - Disable CSRF protection to certain routes, comma separated list of routes.
    • Default: null
    • example .env setting: DISABLE_CSRF_FOR="https://example.org/my-route,https://example.org/index.php?pg=login"\
  • MAIL_CRON_INTERVAL - Set custom timing for how often email mailboxes are checked for mai
    • Default: * * * * *
    • Values: Valid CRON format schedule.
  • AUTO_COLLECT_MAIL - Enable (default) or Disable mail collection
    • Default: true
    • Values: true, false
  • SEND_MAIL_DELAY - Add a delay between mail sends to help with services that throttle sends over time
    • Default: 1
    • Values: Time in seconds
  • SEND_MAIL_BACKOFF - The number of seconds to wait before re-trying an email that failed to send
    • Default: 30
    • Values: Time in seconds
  • SEND_MAIL_RETRIES - The maximum number of times HelpSpot will attempt to resend an email.
    • Default: 5
    • Values: An integer of reties
  • MAINTENANCE_MODE - Put HelpSpot into maintenance mode
    • Default: false
    • Values: true, false
  • SECURITY_CONTENT_TYPE_OPTIONS - Sets the X-Content-Type-Options
    • Default: nosniff
    • Values: nosniff or empty

6. Customizing HelpSpot

6.1. Templates: The Basics

The HelpSpot portal is fully customizable to allow integration with any website or intranet.

PHP and HTML

HelpSpot templates are HTML with PHP, not an esoteric template language. This means PHP can be used within the templates themselves to call user-defined functions, includes, an other PHP constructs. This can make customizing an installation easier to allow the inclusion of templates from a main site, thereby preventing the duplication of code.

Editing Templates

The easiest way to edit the portal templates is by navigating to Admin > Customize > Portal Templates. Here you can view and edit the templates for your primary portal and any secondary portals. HelpSpot automatically versions your changes and allows you to roll them back if needed.

If you with to edit the files on the server directly, templates are located in the folder: /helpspot/templates. While it's possible to modify the files there directly it is not recommended. Instead it is recommended that the files be copied and placed in: /custom_templates. HelpSpot's template system will automatically check the /custom_templates folder and use the template from there instead of from /helpspot/templates. Using a custom templates folder prevents customizations from being overwritten during future version upgrades.

Common Files to Modify

These files are included on each page of the portal. For a basic level of integration (ie: standardizing 'look and feel), modifying only these files, in most cases, would be enough.

  • header.tpl.php
  • footer.tpl.php
  • navigation.tpl.php
  • css.tpl.php

List of All Templates

Each template contains specific documentation inside it, so please see the templates themselves for more details

Template Description
captcha.tpl.php HTML elements for the CAPTCHA system
css.blue.tpl.php (Blue) CSS styles used in the portal
css.clean.tpl.php (Clean) CSS styles used in the portal
css.grey.tpl.php (Grey) CSS styles used in the portal
css.tpl.php (Classic) CSS styles used in the portal
footer.tpl.php HTML footer used across all portal pages
header.tpl.php The HTML header is stored in this file as well as the 'container' DIV that holds all other page elements. Often just adding your organizations standard header to this file is enough to provide a consistent feel across the sites.
home.tpl.php The portals homepage
ie.css.blue.tpl.php (Blue) Special IE specific CSS styles used in the portal
ie.css.clean.tpl.php (Clean) Special IE specific CSS styles used in the portal
ie.css.grey.tpl.php (Grey) Special IE specific CSS styles used in the portal
ie.css.tpl.php (Classic) Special IE specific CSS styles used in the portal
index.tpl.php A special page that includes the correct template. All pages pass through the index template.
js.tpl.php Javascript required for the portal
kb.book.tpl.php Books table of contents page
kb.chapter.tpl.php Chapter with list of chapter pages
kb.page.tpl.php Knowledge book page
kb.printer.friendly.tpl.php All a knowledge books pages on one page for easy printing.
kb.tpl.php List of available knowledge books
login.create.tpl.php Customer account creation page
login.forgot.tpl.php Customer forgot password page
login.reset.tpl.php Customer reset password page
loginbar.tpl.php The menu bar at the top of the request check pages when a user is logged in.
maintenance.tpl.php A page which is shown to visitors when the system is in maintenance mode
navigation.tpl.php HTML for side bar navigation used across all portal pages
request.check.tpl.php Page where customers check their requests
request.history.tpl.php List of requests visitors see when logged into the portal
request.tpl.php Submit a request form
search.tpl.php Search results page
searchbox.tpl.php HTML for search box used across all portal pages
tag.search.tpl.php List of pages/topics matching a knowledge tag
terms.tpl.php HTML Elements for agreeing to the terms and privacy policy.

6.2. Admin Themes

AS OF HELPSPOT 5.0 ADMIN THEMES ARE NO LONGER USED

Admin themes have been replaced with custom javascript and css settings.

Admin themes allow you to customize the look and feel of your staff pages in HelpSpot. A few simple uses include:

  • Changing the header to your company colors
  • Adjusting text sizes more to your liking
  • Adding or removing UI elements

Theme Structure

HelpSpot ships with several built in themes. The code for these /themes/ with a subfolder for each specific theme. So the blue theme is in /themes/blue/. Inside the folder is the css for that theme and optionally an image folder and custom javascript file. So a theme folder with everything would look like this:

Creating a Custom Theme

It's often useful to start with one of the built in themes as those contain the most common elements you want to modify. To do so simply copy one of the folders like /themes/blue to your own folder such as /themes/pink. In this case you'd then change blue.css to pink.css and you're all set. From there you can modify pink.css to match your design.

You can find all the built in CSS elements in /static_#HelpSpot_Version#/css/base.css and any of those styles can be overridden by your custom CSS.

Using Custom Javascript

If you'd like to add your own javascript logic to HelpSpot you can do so by adding a theme_name.js file to your theme folder, such as /themes/pink/pink.js. HelpSpot will automatically include that file in the head of every page. jQuery is currently also available, however, it uses a custom shorthand of $jq instead of the more familiar $. Of course jQuery() can be used as well. For most things you'll also probably want to wait for the page to load using:

$jq(document).ready(function(){
     //Your jQuery here
});

6.3. Portal Privacy Policy and Terms of Service

The HelpSpot portal allows for the display and agreement to a Privacy Policy and Terms of Service before a customer request can be submitted. These settings are found in Admin > Settings > Portal. These two settings allow you to set a URL for where your Privacy Policy and Terms of Service are hosted. If you don’t have these externally hosted you can create them as KB pages and then link to them.

After adding one or both of these URLs a checkbox will be displayed on your portal forms asking your customers to agree to the terms and privacy policy before proceeding. 



If you are using a customized request.tpl.php template from a version of HelpSpot prior to 4.8.0, you will need to update that template in order to allow the checkbox to be properly displayed. This new code needs to be added immediately following the captcha include:


<?php include $this->loadTemplate('terms.tpl.php'); ?>



6.4. Language Files - Modifying Language Packs

Every word and phrase used in HelpSpot is stored in a language file located in:

/helpspot/lang/english-us/

Customizing your language pack may be necessary if HelpSpot doesn't come with your desired language or if you would like to make changes to the default phrases in HelpSpot

Prevent Overwriting During Updates

If you directly modify a HelpSpot language pack your changes will be lost during the next update because the file will be overwritten. To protect your changes follow these steps.

  1. Duplicate the original language pack and give it a new unique name. For example copy /english-us/ to /english-mycompany/
  2. Next go to Admin->Settings and change the "Language:" options to your newly created language pack
  3. That's it. You may now safely modify your custom language pack.

6.5. Populating Customer Information via Links

Creating links to the admin

Some customers find it convenient to add an HTML link to their other customer data systems, which allows them to open a new HelpSpot request. The URL you should use for this is below:

http://your-helpspot-url/admin.php?pg=request

In addition, it's possible to pass in customer information so that the customer information form fields will be pre-filled in. You may pass in the following fields via the URL.

URL Variable Description
sUserId Unique customer ID
sEmail Email address
sFirstName First name
sLastName Last name
sPhone Phone number
tBody The text for the note field
xCategory Put the ID of the category to be selected
xStatus Put the ID of the status to be selected

An example:

http://your-helpspot-url/admin.php?pg=request&sUserId=12345&sEmail=tsmith@company.com&sFirstName=Tim&sLastName=Smith&sPhone=8451234567

Creating links to the portal

The portal's request form may also be populated with data via links. In addition to the above variables that can be passed in, the following are valid for the portal form.

URL Variable Description
fullname A persons full name: "Todd Smith"
sEmail An email address
simple The textarea when using the simple format for the form (the default format)
Custom# A custom field value where # is
fUrgent Set urgency. 1 for urgent, 0 for not.
additional Populates a hidden field that will be submitted with the request and appended to note.

An example:

http://your-helpspot-url/index.php?pg=request&fullname=todd%20jones

6.6. Category Management

Categories are the primary way of grouping requests inside of HelpSpot. When HelpSpot is installed it will come with pre-populated categories to get you started. Using these categories is completely optional. 

To customize the categories available in your helpspot instance navigate to Admin > Categories.

Adding a New Category

Use the add category form to add a new category to HelpSpot.

Settings in Depth:

Category Name: The name of the category that will appear in the user interface of helpspot.

Category Grouping: Sets of categories can be grouped together for easier navigation. 

Visibility: This setting will control whether a category is available on public request forms. Allowing request categorization also needs to be enabled at the portal level.

Category Staff Member: The option allows you to select staff members who are available for work requests in this category. This setting works in conjunction with the Auto Assign Requests setting to define the pool of staff used for auto assignment rules.

Default Staff Contact: This setting defines the default staff member that will be assigned requests in this category. It can be left blank. 

Auto Assign Requests: This dropdown allows an auto assignment rule to be defined for a category. The options are as follows:

  • To Default Contact - Automatically assigned requests to the Default Staff Contact
  • Random Category Staffer - This will randomly select a staff member from the Category Staff Member's pool.
  • Random Category Staffer (No Administrators) - This will randomly select a staff member from the Category Staff Member's pool, but staff that are administrators will be excluded.
  • Category Staffer With The Least Requests - This will assign requests to the category staff member with the least number of open requests in Helpspot.
  • Category Staffer With The Least Requests (No Administrators) - This will assign requests to the category staff member with the least number of open requests in Helpspot, but staff that are administrators will be excluded.
  • Round Robin (Even Distribution) - Category staff members will be rotated through in order (i.e. staff 1 - receives request 1, staff 2 - receives request 2, staff 3 - receives request 3, staff 1 - receives  request 4 and so on.)
  • Round Robin (Even Distribution, No Administrators) - The same round robin methodology as the previous setting, but excluding administrators.

Reporting Tags: Report tags provide another level of organization beyond categories themselves. Reporting tags are unique in that more than one reporting tag can be selected at a time. 

Custom Fields: Custom fields for a specific category can be specified here. Custom fields that are checked will be included in the side bar of the request window. If the category and custom fields are marked as public they will also be visible on the customer portal form. 

Editing Categories

Each category can be edited by clicking on the category name in the categories listing. All of the settings available when creating a new category are also available when editing.

Deleting Categories 

Categories can not be deleted, but they can be made inactive. To make a category inactive, edit the category and then click on the "Make Category Inactive" button in the lower right hand corner. Once a category is made inactive, it can be accessed by clicking on the "Show Inactive Categories" button in the main categories setting page. Inactive categories can be reactivated by editing the category and then clicking on the "Restore" button.

6.7. Time Tracking

To enable time tracking go to Admin->Settings and click the Time Tracking bar. Set enabled to Yes and save the settings. Each request (after it's created) will now have a time tracking bar at the top for managing that requests time.

Other Time Tracking Tips

  • Time can be entered in normal time format hh:mm or in decimal form 1.5, 4.25
  • You can add a time column to your custom filters to see how much time was spent on each request right from the workspace.
  • After enabling time tracking 2 new reports will be available under the reports tab which allow for time reporting by customer and staff.
  • There is a preference in each users settings to default the time tracker box to open.

6.8. Formatted Text Syntax (Markdown)

HelpSpot uses the text formatting language Markdown to support building HTML documents from text.

Markdown also accepts HTML, so you can intermingle HTML tags with the Markdown syntax.

Phrase Emphasis

*italic*   **bold**
_italic_   __bold__

Links

Inline:

An [example](http://url.com/ "Title")

Reference-style labels (titles are optional):

An [example][id]. Then, anywhere
else in the doc, define the link:

[id]: http://example.com/  "Title"

Images

Inline (titles are optional):

![alt text](/path/img.jpg "Title")

Reference-style:

![alt text][id]

[id]: /url/to/img.jpg "Title"

Headers

Setext-style:

Header 1
========
Header 2
--------

atx-style (closing #'s are optional):

# Header 1 #
## Header 2 ##
###### Header 6

Lists

Ordered, without paragraphs:

1.  Foo
2.  Bar

Unordered, with paragraphs:

*   A list item.
    With multiple paragraphs.
*   Bar

You can nest them:

*   Bus
  * Yellow
*   Cars
  1.  Dodge
  2.  Honda
    * Civic
  3. Trucks
*   Cunning

Manual Line Breaks

End a line with two or more spaces:

Roses are red,
Violets are blue.

Tables

A simple table

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

A table with the right columned aligned (note the : at the end of the header line)

| Item      | Value |
| --------- | -----:|
| Computer  | $1600 |
| Phone     |   $12 |
| Pipe      |    $1 |

Formatting can be used within the table

First Header  | Second Header
------------- | -------------
Content Cell  | **Content Cell**
*Content Cell*  | Content Cell

Blockquotes

> Email-style angle brackets
> are used for blockquotes.
> > And, they can be nested.
> #### Headers in blockquotes
> 
> * You can quote a list.
> * Etc.

Code Spans

`<code>` spans are delimited
by backticks.
You can include literal backticks
like `` `this` ``.

Preformatted Code Blocks

Indent every line of a code block by at least 4 spaces or 1 tab.

This is a normal paragraph.
  This is a preformatted
  code block.

Horizontal Rules

Three or more dashes or asterisks:

---

* * *

- - - -

6.9. Widget Tab Setup

The widget tab allows you to gather questions/feedback from any page on your website or even multiple websites. With just a few lines of javascript the tab can be included on any web page.

The widget is completely configurable for seamless integration with your website, even the image used for the tab itself can be changed.

Basic Setup:

<style type="text/css">@import url('http://www.YOURDOMAIN.com/helpdesk/widgets/widgets.css');</style>
<script type="text/javascript" src="http://www.YOURDOMAIN.com/helpdesk/widgets/widgets.js"></script>
<script type="text/javascript">
HelpSpotWidget.Tab.show({ 
	// Nearly every aspect of the widget is customizable, complete documentation here:
	// http://www.helpspot.com/helpdesk/index.php?pg=kb.page&id=323
	host: 'http://www.YOURDOMAIN.com/helpdesk'
});
</script>

Where to Place the Code:

The inclusion code should be placed on every page where you want the tab to appear. For performance it's best to place the code at the bottom of your HTML page just inside the closing </body> tag.

Complete Example:

This example shows every configuration option in use.

<style type="text/css">@import url('http://www.YOURDOMAIN.com/helpdesk/widgets/widgets.css');</style>
<script type="text/javascript" src="http://www.YOURDOMAIN.com/helpdesk/widgets/widgets.js"></script>
<script type="text/javascript">
HelpSpotWidget.Tab.show({ 
	host: 'http://www.YOURDOMAIN.com/helpdesk',
	alignment: 'left',
	tabtype: 'questions',
	tabtype_custom_img: '',
	top: '30%',
	width: 600, 
	color: 'white',
	background_color: '#222222',
	hover_color: '#222222',
	popup_background_color: '#fff',
	popup_border_color: '#ccc',
	popup_border_size: '10px',
	overlay_color: '#000',
	default_note: '',
	default_name: '',
	default_email: '',
	use_field_name: true,
	text_header: 'How can we help?',
	text_intro: 'Submit your question/comment for a member of our team.',
	text_note: 'Question',
	text_note_er: 'Please provide some information on your request',
	text_email: 'Your Email',
	text_email_er: 'Please provide your email address',
	text_name: 'Your Name',
	text_name_er: 'Please provide your name',
	text_submit: 'Submit',
	text_msg_submit: 'Message sent, thank you.',
	text_msg_submit_error: 'Sorry, there was an error.',
	text_msg_submit_error_link: 'Please try this form',
	text_msg_submit_error_url: 'http://www.YOURDOMAIN.com/helpdesk',
	text_loading: 'Loading...',
	text_special: ''
	//,onLoad: function(){ alert('open'); },
	//onClose: function(){ alert('close'); }
});
</script>

CSS Customizations:

The options above allow you to control the look of the tab, but the form itself can be customized via CSS. To do so put a file named widget_tab.css inside your /custom_code folder. If the system detects this file it will include it on the tabs form page automatically.

Option Descriptions:

host The root URL of your HelpSpot installation
alignment The tab can be aligned left or right on the page
tabtype Image that's shown in the tab. Options are: questions, contact, support, feedback, help
tabtype_custom_img Full URL to an image to use for the tab other than one of the defaults
top % or PX for how far from the top of the screen the tab should be positioned
width How wide the popup window will be
color Color of the tab image to use: white or black
background_color Background color of the tab
hover_color Color used when the tab is hovered over
popup_background_color Color for the background of the popup box
popup_border_color: Color used in the popup box border
popup_border_size Thickness of the popup border
overlay_color Color of the background overlay behind the popup
default_note Text to be inserted in the note field by default
default_name Text to be inserted in the name field by default (if being used)
default_email Text to be inserted in the email field by default
use_field_name Show the name field to be filled in by the visitor (true/false), defaults to false
text_header Large text shown at top of popup
text_intro Subheading text
text_note Label for the note field
text_note_er Error text when the note field is not filled in
text_email Label for the email field
text_email_er Error text when the email field is not filled in
text_name Label for the name field
text_name_er Error text when the name field is not filled in
text_submit Submit button text
text_msg_submit Shown when a request is successfully submitted
text_msg_submit_error Shown if there is an error sending in the request
text_msg_submit_error_link When there is an error a link is provided to a secondary form to try (if an error link URL is set)
text_msg_submit_error_url URL to link to if an error occurs when submitting the request from the tab
text_loading Text to use while the widget loads
text_special Text that sits below the text_intro which has a special style applied. Good for unique notes or temporary messages.
onLoad A javascript function that will executed when the popup box opens
onClose A javascript function that will be executed after the popup closes

6.10. Email Templates

Customizing Email Templates

The default email templates can be customized by navigating to Admin > Customize > Email Templates. Each template can be both edited and viewed from this page. Once edits have been made, be sure to save them with the save button at the bottom of the page. Email templates can be formatted with html and can include template tags. These can be selected from the dropdown or typed into the editor.

Most templates contain three separate tabs, HTML, Text, and Subject. The HTML template will send for those that can receive HTML emails. The text version is a plain text version of the same email for those that do not accept HTML email. When editing make sure to update both of these tabs. The subject tab allows you to adjust the subject line of the email. You can also use template tags in this area to personalize the subject line.

Per Mailbox Templates

Email templates can also be specified at the Mailbox level for Auto Reply, Public Notes to Customer, External Notes and Requests Created by Portal Form. These settings can be found in Admin > Email Mailboxes. Once a mailbox is selected the templates can be edited at the bottom of the mailbox's setup page.

When defined, these templates will override the default templates that are set up in the Email Templates page. The "Request Created by Portal Form" template will only override the main template only if the mailbox is defined as the "Send Emails From" mailbox for a secondary portal. 

6.11. Email Template Tags Reference

Email templates can process a variety of template tags. These tags can be typed directly into the template or they can be selected from the tag selector dropdown below the template editor box. Below is a reference to all the available tags. See the Email Templates document for more information on how to edit email templates. The tags below are available for the current version of HelpSpot. Note that HelpSpot versions less than 5.0.0 use a different syntax.

{{ $requestcheckurl }} The URL to check the request.
{{ $accesskey }} Access key. This is the key that is used by a customer to access tickets in the portal. 
{{ $message }} The note body of the current note.
{{ $fullpublichistoryex }} Outputs the full public history of notes not including the current note.
{{ $fullpublichistory }} Outputs the full public history of notes including the current note.
{{ $lastcustomernote }} Outputs the last note by the customer.
{{ $requestid }} The Request ID generated by HelpSpot for this request.
{{ $replyabove }} This outputs the "Reply Above" Text that is defined in the Replay Above template.
{{ $portal_email }} The email address the customer can use to login to the portal to view their request.
{{ $portal_password }} The password the customer can use to login to the portal to view their request.
{{ $customerfirst }} Customer first name
{{ $customerlast }} Customer last name
{{ $customerid }} Customer ID
{{ $customeremail }} Customer email
{{ $customerphone }} Customer phone
{{ $status }} The current status of the request.
{{ $category }} The category assigned to the request.
{{ $urgent }} Returns if the request is marked as urgent.
{{ $open_closed }} Returns if the ticket is currently open or closed.
{{ $date_opened }} Date Opened
{{ $date_now }} The current date/time
{{ $assigned_first }} Assigned staff member: first name
{{ $assigned_last }} Assigned staff member: last name
{{ $assigned_email }} Assigned staff member: email
{{ $assigned_phone }} Assigned staff member: phone
{{ $logged_in_first }} Logged in staff member: first name
{{ $logged_in_last }} Logged in staff member: last name
{{ $logged_in_email }} Logged in staff member: email
{{ $logged_in_phone }} Logged in staff member: phone
{{ $subject }} Original mail subject line
{{ $initialrequest }} This returns the initial (first) request note.
{{ $orgname }} The organization name for the helpspot instance as defined in the Admin area.
{{ $helpdeskurl }} Help Desk URL
{{ $requestformurl }} Request Form URL
{{ $requestcheckurl }} Request Check URL
{{ $knowledgebookurl }} Knowledge Book URL
{{ $custom1 }} Each custom field can be referenced by it's ID in the format "{{ $CustomID }}" where ID is the actual ID number.
@if ($customerid == 12938)
    Company A
@elseif ($customerid == 12938)
    Company B
@else
    Unknown Company
@endif
Conditional statements can be structured as demonstrated to the left. You may construct if statements using the @if, @elseif, @else, and @endif directives. 

6.12. Custom Pages

Custom pages allow you to add navigation/pages to HelpSpot's workspace. They're useful for adding content which is protected by HelpSpot's authentication. The uses are practically limitless, here's a few ideas:
  • A page simply listing links to other help desk resources elsewhere for staff
  • A report from an external system
  • A redirect to an external system
  • A page for AJAX based tools

Naming and Location

Custom pages are located in the custom_pages directory in your HelpSpot application server. To access custom pages on HelpSpot Cloud please contact customer service. Sample page is provided in that directory.

Naming Convention

  • Letters, numbers, underscores and dashes only (no spaces)
  • Must end in .php
  • Navigation link will show underscores as spaces and capitalize the first letter of each word

LIMITS/ACCESS

Custom pages do not have access to HelpSpot's PHP functions, however, they can make use of jQuery and HelpSpot's CSS.


6.13. Filter Color Tags

Filter color tags allow easy visual sorting of requests. Color tags are set on the Predefined List custom field type. To add color tags, navigate to Admin → Custom Fields. Then select an existing predefined list or add an new one. Once you have the predefined list setup open you can set the color options for each list item. The color can be selected by clicking on the color code box.

Once the color options are selected in the custom field setup, you can add the custom field to filters using the column selector under the filter editor. 

After saving these changes, color labels will appear in the filter grid.

 

7. Automated Actions

7.1. Triggers, Mail Rules and Automations

There are three types of automated actions in HelpSpot that can be created. The main difference between them is when a request is checked to see if it matches the conditions defined by an automation rule.

Mail Rules

Mail Rules are run when an incoming email is read and a new request is created. This is only run when the request is first created - so it can only be applied once per request. Subsequent responses to a request, even if received through email, are not run against Mail Rules.

Triggers

Triggers are run anytime a request is created or updated. This can check if some conditions are present, or if they've changed. For example, an action can be taken if a category of a request was changed specifically from "technical" to "sales".

Automation Rules

The last category of automation rules is also called "Automation Rules". These are run periodically. How often these run is configurable in the automation settings.

Automation rules are useful for time-dependent tasks. For example, if you wish to escalate a request or send an email notification if a request has not been answered within a certain time period.

 

8. Automation Rules

8.1. Overview

Automation Rules (Admin->Triggers and Rules->Automation Rules) provide a means to preform actions on a set of requests that meet a specific set of conditions. With highly flexible rules-based logic, Administrators have the power to create rules that allow for improved management of support requests.

Automation rules are commonly used for:

  • Request escalation
  • Workflow creation
  • Staff/Management notification
  • Customer notification
  • Setting/changing request detail values

 

Designing Rules

With such flexibility, and varied uses, Automation Rules allows for tasks to be accomplished in a number of ways.

While there might not always be one set way to design a rule, the following should always be considered to ensure the rules accomplishes the desired end result.

  • Which conditions should be used to pull the appropriate requests?
  • What actions should be preformed?
  • How frequently should this rule run?
  • Should this request be allowed to run more than once per request?

Subsequent pages in this chapter well show the creation and running of automation rules as well as specific examples.

8.2. Rule Creation: Defining Conditions

Automation Rule conditions, just like Filter conditions, are based on individual elements of the request, Customer, or actions taken on a request. Administrators must define if the requests should match any or all conditions defined for the rule.

For each condition there is a means to define the value, via either a drop-down or text field. Each condition provides an additional drop-down for selecting the operator(s) to define how the specified value is applied.

Sample operators include:

  • greater than
  • less than
  • is not
  • is

Using category and email as a very simple example, it can be seen how Administrators would work through defining these conditions. Conditions are added and removed by using the plus and minus signs to the right of the condition definition.

A complete list of all conditions, defined, can be found in the attached file found at the bottom of this page.

Testing Conditions

Automation Rules require the defined conditions be tested prior to saving. Because the subsequent actions that are applied can make unreversible changes to requests, testing allows Administrators to verify the conditions defined truly meet the business need.

8.3. Rule Creation: Defining Actions

Once conditions are tested and defined, Administrators can move on to defining the subsequent action(s) to be preformed.

Actions can be divided into two types:

  • Actions that change information within the request.
  • Actions that notify specified individuals.

Important to remember: the actions defined in a rule will apply to all requests that meet the condition(s). Since some actions result in changes to the request, it's critical Administrators verify the conditions prior to making rules live.

Many times the 'change' and 'notify' actions must be used together within a rule to complete the automated process.

For example, a rule can have actions that notify two staffers and change a category; three individual actions working together to complete the automated process.

8.4. Preventing Reoccurring Matches

Special Note: As of HelpSpot v4.9.0 new automation rules will only run once per request by default. The actions below are only needed if the "Run Once" checkbox is deselected in an automation rule.

Beyond the creation of conditions and actions to define the rule, Administrators must also consider how to use conditions and actions to prevent the rule from continually pulling the same requests as matches.

Rule matches the same requests over and over when it shouldn't?!

This is a common question when first creating rules. To understand why this happens, let's quickly review how rules work.

When a rule runs (details on rule scheduling can be found via the links below) requests are identified, via conditions, and the defined actions are taken.

The next time the rule is run the same requests will be picked up and action taken unless an action is set that makes a change to the request. This change will be the indicator that the request(s) has already been processed.

In practical terms, when creating a rule Administrators need to ask themselves:

  • What component of the request do I have to change? (set applicable action)
  • Do I have a condition that will look for something outside of what I changed in action? (verify conditions)

Let's work through an example. To support internal procedures, a rule is created to notify Sally Smith (help desk supervisor) when a request hasn't been updated in 4 hours.

To ensure Sally isn't notified continually on the same requests, there needs to be an indicator in the rule that changes. In this example we choose status as the indicator.

So, when creating this rule we must:

  • have a condition that looks for those NOT in the Escalated status.
  • have an action that changes the status to Escalated. Depending on installation configuration, custom fields or category could also be used.

Below is a look at how the conditions and actions of this rule would be configured.


8.5. Custom Scheduling Automation Rules

automation:rules

You can run all Automation Rules, or specific Automation Rules by their ID. Their ID is found within HelpSpot when viewing the list of Automation Rules.

# Run all automation rules
# Except those marked to run on a Custom Schedule php 
hs automation:rules 

# Run automation rule 1 
# regardless of Custom Schedule setting 
php hs automation:rules --id=1 

# Run automation rule 1 and 2 
# regardless of Custom Schedule setting 
php hs automation:rules --id=1,2

8.6. Examples

Now let's look at how to create Automation Rules that support specific business needs. When reviewing these examples, keep in mind:

  • Different combinations of conditions/actions may be used; we attempted to use the most direct way of accomplishing each.
  • When considering how to apply to your business, conditions and/or actions may need to be added/taken away.

Escalation: No update to customer after 24 hours

Scenario: XYZ support desk has a policy that all requests falling in the Account Inquires category must be responded to within 24 hours. For those that aren't, the escalation should be a reassignment to Sally Smith and, to create transparency for the customer, an email is sent to the customer stating their inquiry is in process.
Here's how this need would be translated into an Automation Rule.
Important to Notice
  • To prevent the same requests from matching over and over we changed the assignment to Sally and have a condition that looks for requests not assigned to Sally.
  • In addition to update timeframe, we used category as one of the conditions for reassignment; keep in mind status, custom fields, etc. could have been used as well.
  • In our customer email we used the placeholder for the assigned staffers first name. Given the company wants to create transparency on the process for the customer, this was an appropriate addition. The choice to use the placeholder, over typing a name, simplifies the process if reassignment moves away from Sally and to another.

Notification: Request due tomorrow

Scenario: ABC support desk wants to notify staff (via SMS notification) of requests that are due tomorrow (a custom field). Due date is only tracked for those requiring off-site work, specifically hardware installation.

Here's how this need would be translated into an Automation Rule.
Important to Notice
  • Conditions depend on the existence of:
    • a custom field for completion date, and
    • category/reporting tag for Hardware, Installation.
  • Required Completion Date (custom field) set to tomorrow will prevent multiple notifications from being sent for the same request. This is assuming the rule is run at the default once per day.
  • Staff must have a mobile number in their preferences in order to be selected to receive a message.
  • While SMS was used in this example email notification is another notification option. Configuration is similar to as shown in the first example.

Email Results Set: Creating daily management reports

Scenario: Department managers in the company are expected to have an understanding of the types of issues the support desk is handling on behalf of the areas they manage. To facilitate this, the support manager wants to create a report that shows all each departments requests, opened in the past 24 hours. For ease this report should be emailed daily to each manager.

Here's how this need would be translated, for one of the departments, into an Automation Rule.

A sample results set, as it will be emailed to each manager, is shown below.
Important to Notice
  • Conditions are:
    • categories since it's related to each department in the company, and
    • relative date opened, so the manager can see all new requested worked in the past day.
  • The results set will be sent every day when the rule is run (using default, once per day).
  • Recipients must have a HelpSpot account.
  • A rule would have to be created for each manager in the company.

 

9. Secondary Portals

9.1. Secondary Portal Overview and Limitations

HelpSpot's secondary portal system provides the unique ability to create multiple portal instances, all of which feed into a single installation. Secondary portals are ideal for HelpSpot installations that need to support distinct website domains or require custom portals for different departments, groups or brands.

How it Works

All secondary portals are initially based on the primary portal (default, built-in portal), however can be customized to meet the needs of the target customers. As such, Administrators can choose to exclude/include:

  • Knowledge Books and Forums
  • Public Categories
  • Public Custom fields

Because each secondary portal has it's own set of templates, Administrators have full control over giving each their own look and feel.

Limitations

Given the current design of secondary portals, Administrators should be aware of the following limitations / considerations prior to implementing.

* Secondary portals currently all share logins with the primary portal. For departments this is likely fine. If you're using it across websites this may be an issue if you expect customers to use both websites. In that case you could disabling logins or use Black Box logins to enforce your own login logic.

* Secondary portals cannot show requests that were manually created by staff. Only requests created by the customer via email or the secondary portal can be shown to customers when logged in.

* All secondary portals must be on the same server as the main HelpSpot installation or at least available across a network drive. Secondary portals must be able to read files from the main HelpSpot installation.

* Several settings are currently not able to be overridden and default to what the primary portal is set for in Admin->Settings->Portals. Examples include which captcha to use and if the request form should use the simple or detailed format.

* The reCaptcha keys (for installations using reCaptcha) are shared across all portals so a global reCaptcha key must be used.

* Public components (knowledge books and forums) created for secondary portals will be shown on the primary portal. If this is not desired, a secondary portal must be created to override the default primary portal. Details on that process are here.

In the subsequent pages we'll look at the creation process, including file placement, and how to address special considerations.

 

9.2. Adding a Secondary Portal

There are two main steps to adding a Secondary Portal:

  1. Configuring the portal within HelpSpot
  2. Creating the Secondary Portal files as instructed from HelpSpot (If you are using HelpSpot Cloud please contact support)

Configuring a Secondary Portal

To configure a new Secondary Portal, head to Admin > Customize > Secondary Portal. There you can edit an existing or create a new Secondary Portal. For details on the configuration options available, see the section Explanation of Each Portal Setting.

Once you create a new Secondary Portal, you'll be provided with a set of instructions on setting up the portal.

Create the Secondary Portal files

HelpSpot will attempt to setup your portal files system and URL automatically (If you are using HelpSpot Cloud please contact support):

If HelpSpot is unable to automatically setup your portal, there is a View Instructions link available at the Admin > Customize > Secondary Portal page (the same page which lists existing Secondary Portal).

9.3. Explanation of Each Portal Setting

Administrators should go to Admin area->Tools->Manage Secondary Portals. It is from here the process begins. The following fields, described below, are the first phase of two phases in the creation process.

Remember: Because every secondary portal is based on the primary portal, settings not described here use the values in Admin->Settings->Portal.

Portal Name - This overrides the organization name that is used in the Primary portal. This name will be shown in the header of the secondary portal and is also used as a label when reference is made to this portal in the request history, workspace, filters, and reports.

Portal URL - The URL of the secondary portal. This may be an alternate domain or a subfolder of where HelpSpot is currently installed. For instance, if HelpSpot is installed at:

http://www.mydomain.com/helpdesk

and this secondary portal is going to support a different website at www.cookies.com then you would set this URL to be:

http://www.cookies.com/helpdesk

Note that there should be no trailing slash at the end of the URL.

File System Directory Path - The file path to the URL. This path need to be on the same server as the main HelpSpot installation or a network accessible path. This path is used to reach the /custom_templates folder for this secondary portal and include an override files in that folder.

Note that there should be no trailing slash at the end of the file path.

Categories to Display - This is a list of all the public categories created in Admin->Categories. Any categories checked will be available in the category drop down of the secondary portals submit a request form.

This allows flexibility in customizing the request form for this portal. For example, if this secondary portal is for another department only categories related to that department would be checked.

Checking no categories will prevent the category selection drop down from being visible on the request form for this portal.

Custom Fields to Display - This is a list of all public custom fields created in Admin->Tools->Custom Request Fields. Any custom fields checked will be available on the secondary portals submit a request form.

Note that they will still be restricted to whatever visibility has been specified for them so if the custom field only shows up for particular categories you'll want to make sure those categories are checked in "Categories to Display" as described above.

Knowledge Books to Display - A list of all public knowledge books. Selected books will be available on this secondary portal.

Forums to Display - A list of all public Forums. Selected forums will be available on this secondary portal.

Remember that all public categories, custom fields, books and forums are always visible on the primary portal (built in portal). If this is not desirable in your situation you should read this page on how to change that.

Send Emails From When an email is generated from this portal (ie: auto reply for when a request is created or User/Staff replies to requests) this is the mailbox that will show as the FROM. This is an important setting if you're supporting a secondary website where you want the email domain to match the portals domain.

Customer Log-in View - Mailboxes selected allow requests created via those mailboxes for a logged in portal visitor to be shown in the request history for that customer. So, logging into this secondary portal will allow customers to see all requests they created via the portal form as well as requests emailed in to any of the mailboxes selected in this setting.

Portal Phone - Show a phone number for this secondary portal in the portals left navigation.

Portal Homepage Message - Override the default portal message that's in Admin->Settings->Portal. This message appears on the portals homepage. It can include HTML.

The second phase of the creation process requires directories be created and files be moved to specified locations. Each step of the process is outlined on screen and should be followed to completion.

9.4. How Portal Templates Work in Secondary Portals

When a secondary portal is created a /custom_templates folder is created for the portal. Having it's own /custom_templates folder allows the secondary portal to be modified to match the look of an existing website or have a look of it's own.

The location and procedure for editing templates in a secondary portal is the same as the primary portal (information here), the only difference is that the edited templates should be placed in the secondary portals /custom_templates folder instead of the primary portals /custom_templates folder which is in the root HelpSpot directory.

Important to Remember: Secondary portal templates are stored in it's own /custom_templates folder. Any template changes for a secondary portal should be saved to this location.

9.5. The Primary Portal as a Secondary Portal

By default the primary portal shows every public category, custom field, knowledge book and forum created in the system. In most installations this is the desired behavior, however, in some installations (typically those using secondary portals) some of those items may not be appropriate for the primary portal. For example, a knowledge book may be created which is only for the secondary portal and should not be shown on the primary portal.

For these instances, a simple way to control what appears on the primary portal is to create a secondary portal to be used to override the primary portal. Technically and functionally, the primary portal becomes a secondary portal that can be customized with the desired components.

Because the creation process assumes the secondary portal will exist along side the primary portal, the following process should be used to override the primary portal.

Procedure

  1. Create a secondary portal which will override the primary portal. This portal should use the primary portals URL for it's URL and have the same file path as the HelpSpot installation itself.
  2. Check the checkbox in the secondary portal for "Use as Primary Portal."

Your primary portal is now overridden by the newly created secondary portal and should conform to the settings specified.

9.6. Adding a Secondary Portal within Microsoft IIS

There are two ways in which Secondary Portals are typically used.

  1. As a sub-directory so your site. This will create a Secondary Portal under the same domain as your HelpSpot installation, but under a different directory. For example, if HelpSpot is located at http://support.example.com, and you would like a secondary portal at http://support.example.com/portal, the /portal portion of the URL if the sub-directory under which the Secondary Portal will be installed.
  2. As a different domain or subdomain. This will create a Secondary Portal under a domain or sub-domain which is different from your HelpSpot installation. For example, this describes if HelpSpot is located at http://support.example.com, but you'd like the secondary portal to be a different subdomain such as http://portal.example.com OR if you would like the secondary portal to be at a different domain altogether such as http://another-example.com.

Here we will cover how to accomplish either situation.

Assumptions

In both situations, we will cover these basic steps:

  1. Creating a secondary portal within the HelpSpot Admin configuration.
  2. Configuration the secondary portal location within the system (via IIS Manager)
  3. Configuring PHP to be used within the secondary portal.
  4. Create needed PHP files

Note: We're using IIS7 for this configuration and are basing these instructions off of a default installation of a new HelpSpot instance.

Create a Secondary Portal

The first task to complete in either case (sub-directory or additional domain name) is to create a Secondary Portal within HelpSpot's Admin area.

  1. Click to Admin > Customize > Secondary Portal.
  2. Fill out the appropriate forms:
    • Portal Name - This will be the name that portal users see when they visit it. It can be anything you'd like.
    • Portal URL - This will be the full URL for the portal. If you are using a sub-directory, include the directory path. For example, a subdirectory for this field may be http://example.com/portal. If you are using a subdomain or domain, fill that in. An example of a domain would be http://portal.example.com or http://new-example.com.
    • File Directory Path - This should be the full file path for your portal files. If your HelpSpot web files are located in it's default install location of C:\Program Files (x86)\helpspot\helpspot, we recommend putting your Secondary Portal files alongside them. For example, C:\Program Files (x86)\helpspot\new-portal. If this directory does not already exist, you can create it
    • The remaining settings you can set up as you wish. You can find more information on them in the documentation here.
  3. Once you save, you'll be give content to copy and paste into two files, an index.php file and a config.php file. Create these two files in the file location specified (in this example, create C:\Program Files (x86)\helpspot\new-portal\index.php and C:\Program Files (x86)\helpspot\new-portal\config.php) at this time.
    • Ensure that you also create an empty custom_templates directory.

Note that the URL settings in the new Secondary Portal need to match the Virtual Directory or Domain created in the next steps.

Secondary Portal as a Sub-Directory

If you are installing HelpSpot's Secondary Portal in a sub-directory, continue on with these instructions. Otherwise, you can skip to the next section "Secondary Portal as an Additional Domain".

This assumes you have followed the steps above under "Create a Secondary Portal".

By default, HelpSpot installs under a "site", usually the "Default Web Site". Within the Default Web Site, it creates a Virtual Directory named "helpspot" and configures it to work with PHP via the PHP_FastCGI module mapping.

These are the same configurations used to create a Secondary Portal under a new Virtual Directory.

1. Create a New Virtual Directory

Under the same website HelpSpot is under (usually Default Web Site), create a new Virtual Directory by right-clicking Default Web Site (or the name of your site) and choosing "Add Virtual Directory".

Fill out the fields as follows:

  • Alias - This will be the subdirectory of the url. If you fill in new-portal, the sub-directory will then be http://example.com/new-portal.
  • Physical Path - This will be the same path used when creating the new Secondary Portal within HelpSpot. Select the directory you created above when creating a Secondary Portal within HelpSpot. In this example, that path is C:\Program Files (x86)\helpspot\new-portal



2. Configure PHP

Next and lastly, the virtual directory will need to be told to use PHP FastCGI to interpret the PHP files. There are two steps to this.

First, set a Default Document. This tells IIS to search for a document (such as index.php) if no document is specified. A url such as http://example.com/my-portal has no document specified, while http://example.com/my-portal/index.php does.

The document index.php needs to be added as a default document. Click on the new Virtual Directory "new-portal" and then double-click on the Default Document icon. If you do not see index.php listed as a default document, then you can choose the 'Add...' link on the right-hand menu in order to add it as shown.

Next, enable PHP to be run by adding a Handler Mapping. Once again, click on the new-portal Virtual Directory and then double click on the Handler Mappings icon.

PHP FastCGI needs to be added as a handler. Click on the "Add Module Mapping" link on the right-hand menu. The fields are as follows:

  1. Request Path - Let IIS know which documents to use FastCGI with. HelpSpot needs to run any PHP file through Fast CGI, so a wildcard path *.php should be used.
  2. Module - The HelpSpot installer ensures that the FastCGI Module is already available to use. Here we can use that module for this Virtual Directory. Choose "FastCgiModule" from the list of available Modules.
  3. Executable Path - This is the path to the php-cgi.exe file installed by HelpSpot to run PHP. This is installed with HelpSpot and can be found in it's install location. By default, this is "C:\Program Files (x86)\helpspot\php\php-cgi.exe". Note that use of quotes, to account for the space within the file path. Lastly, note that when you check the file path, you may need to set the file type from *.dll to *.exe as pictured below in order to make the php-cgi.exe file visible.
  4. Name - The name is arbitrary. We recommend naming it "PHP FastCGI".
  5. Click OK and then choose Yes to make it an application.


 

Now when you enter http://example.com/my-portal (adjusting the domain as appropriate), you should see the newly created Secondary Portal home page.

Secondary Portal as an Additional Domain

Adding a secondary portal under an additional domain is very similar to adding a new Virtual Directory.

1. Create a New Site

This assumes you have followed the steps above under "Create a Secondary Portal".

In order to use a different domain for the Secondary Portal, create a new Site within IIS. In this example, we'll assume the additional domain will be portal.example.com.

Right-click on Sites and choose "Add Web Site". Fill out the fields as follows:

  1. Site Name - This is arbitrary. In this example, we'll use "Example Portal".
  2. Physical Path - This is the path to the directory created when adding a new Secondary Portal. In this example, we created the "new-portal" directory alongside the main HelpSpot files at C:\Program Files (x86)\helpspot\new-portal.
  3. Type/Binding/Port - These can remain as default in most cases. If you are using an SSL certificate with this additional domain, you may need to change the Type to "https".
  4. Host Name - This is the domain used, in our example portal.example.com.

Configure PHP

In many cases, because HelpSpot is already installed, PHP will already be configured for new sites created within IIS. The settings will often be the same as the Default Web Site.

However, to make sure PHP is properly configured, ensure the following two configurations are set:

Default Document - Ensure the Default Document includes index.php. Within the IIS manager, click on the newly created web site, then double-click the Default Document icon. Ensure that index.php is listed there.

If index.php is not listed, choose the 'Add...' link on the right-hand menu in order to add it as shown.

PHP FastCGI - Ensure that the FastCGI Module is set to run for any PHP file. Once again, click on the newly created web site and double-click the Handler Mappings icon. The setting "PHP FastCGI" should be enabled for the path *.php.

If "PHP FastCGI" is not listed, then it needs to be added as a handler. Click on the "Add Module Mapping" link on the right-hand menu. The fields to complete are as follows:

  1. Request Path - Let IIS know which documents to use FastCGI with. HelpSpot needs to run any PHP file through Fast CGI, so a wildcard path *.php should be used.
  2. Module - The HelpSpot installer ensures that the FastCGI Module is already available to use. Here we can use that module for this Virtual Directory. Choose "FastCgiModule" from the list of available Modules.
  3. Executable Path - This is the path to the php-cgi.exe file installed by HelpSpot to run PHP. This is installed with HelpSpot and can be found in it's install location. By default, this is "C:\Program Files (x86)\helpspot\php\php-cgi.exe". Note that use of quotes, to account for the space within the file path. Lastly, note that when you check the file path, you may need to set the file type from *.dll to *.exe as pictured below in order to make the php-cgi.exe file visible.
  4. Name - The name is arbitrary. We recommend naming it "PHP FastCGI".
  5. Click OK and then choose Yes to make it an application.


 

Now when you enter http://portal.example.com/ (adjusting the domain as appropriate and assuming the DNS settings for the domain are set), you should see the newly created Secondary Portal home page.

10. In-depth: Admin Settings

10.1. Time Tracker

HelpSpot's time tracker feature allows Users to log time spent working individual requests, right within the request page.

To enable this feature, navigate to Admin > Settings > Time Tracker.

Once this is done, Users will see the time tracker module at the top of the request page for every request.

For more on how the time tracker is used by Staff, see the Users Manual.

10.2. License Information

The Admin area contains the details of the installation such as: customer ID, number of users, version, and support contract information.



Below all the installation information, Administrators will find an file upload area for the license key. Upon initial installation a license file must be uploaded. Any subsequent changes to the installation such as the purchase of additional licenses or a support renewal will also require uploading a new license file, which will be emailed to the primary contact on file with UserScape.

10.3. Maintenance Mode

Maintenance mode allows Administrators to suspends the creation and updating of requests while upgrades or other maintenance is being completed.

Maintenance mode suspends:

  • Email integration. All emails will remain on the mail server until maintenance mode is disabled, at which time all emails sent during the maintenance period will be pulled.
  • Portal submission. Customers will not have access to the portal during maintenance mode periods. Subsequent sections discuss on this page discuss how this looks to the customer.
  • API integration. Those creating/updating requests via an automated process (API) will find during a maintenance period that an error to the application calling the API.

To put the installation in maintenance mode, Administrators must click the Enable Maintenance Mode button. Immediately the maintenance page will be presented to all attempting to access HelpSpot or the portal. Only Administrators have the ability to disable using the disable button on the maintenance page presented to Users (as shown below).

 

Maintenance Mode for Users

Below shows the maintenance page as presented to Users attempting to access HelpSpot. During maintenance mode, Users will not be able to log into HelpSpot.

 

Customizing Maintenance Mode for Portal

HelpSpot will display the default message, as shown below, to customers attempting to access the portal while the site is in maintenance mode.

 


 

However, Administrators can customize this message by editing the appropriate portal template (maintenance.tpl.php).

For details on how to customize portal templates, see the Portal Template chapter referenced below.

10.4. Status Types

HelpSpot offers the flexibility of creating customized status type which are typically used to denote the current progress made on a request.

By default, HelpSpot provides 5 status types. These can be edited or set to inactive and replaced by those created by an Administrator. To add a status type, Administrators simply type the name of the status in the Add a New Status box. Hitting Save at the bottom of the Settings page will create the status and set it as active.

 

While the use of status is required, it's important to note that the status must be changed to something other than Active to close a request.

Status Types in Use

Beyond using as an indicator of where on the continuum of resolution an issue sits, Administrators may opt to have status serve as milestones in a process to resolution. When status types are used as milestones, they can be coupled with automation/mail rules or even filters to create specific workflows.

10.5. Custom Fields

HelpSpot custom fields allow for the creation of user-defined fields that store data on a given request. Custom fields are full-fledged data items in HelpSpot. They can be filtered on, modified with automation, used in templates, etc.

Custom Field Types and Creation

Custom fields are created and modified in Admin > Custom Fields. Below is a list of the available custom field types.

  • Predefined List - Creates a dropdown list of options that a user can select.
  • Drill Down List - Creates multiple levels of dropdown lists that are dependent on the parent selection.
  • Text Field - Stores text data on a single line.
  • Large Text Field - Store multiline text data.
  • Date Field - Stores date data and presents a calendar date-picker for date entry.
  • Date and Time Field - Stores date and time data and presents a date and time picker for entry.
  • Regular Expression Field - Validates text data against a regular expression before allowing data entry.
  • AJAX Selection Field - A programmatic field that dynamically populates options. More info here: Ajax Fields
  • Checkbox - Creates a single checkbox fields
  • Numeric Field - Stores whole number data.
  • Decimal Field - Stores decimal number data.

Custom Field Options

When creating a custom field you can attach the custom field to particular categories. The requests in the categories selected will be the only requests that present those custom fields. You can also choose to make custom fields public which will show them on the public customer portal.

You can also choose to make a custom field required. If a custom field is required. Users will not be able to update / create a request without providing a value.

10.6. Permission Groups

Permission Groups in HelpSpot allow administrator to define the rights for helpspot staff members. Permission groups also serve a secondary function in controlling access to resources like shared filters and responses. Permission groups are defined in Admin > Organize > Permission Groups. HelpSpot comes with several predefined permission groups each of these can be edited or deleted with the exception of the Administrator group. To edit a permission group simple select it from the list. Permission groups can also be copied by choosing the clone link. Below is a summary of the available permission group options.

Permission Description
Module Permissions - Reports Controls if reports are available to users in this permission group
Module Permissions - Manage Knowledge Books Controls the ability to create, edit and delete knowledge books. Users without this permission can still view knowledge books. Note, there are also granular permissions available on the knowledge book level to control editing.
Module Permissions - Manage Forums Controls the ability to create, edit and delete forums. Users without this permission can still view forums and interact with them.
Access Permissions - Batch Respond to Requests Controls access to the batch response tools in the workspace.
Access Permissions - Merge Requests Controls the ability to merge requests in the workspace.
Access Permissions - Access the advanced search page Controls access to advanced search. Without this permission, only quick search is possible.
Access Permissions - Manage Spam Controls access to being able to mark items as spam and delete spam items.
Access Permissions - Manage Trash Controls access to being able to mark items as trash.
Access Permissions - View Private KB's Controls access to KB books that are marked private. If this permission is unchecked, staff will only be able to see public books.
Access Permissions - View Private Forum Controls access to forums that are marked private. If this permission is unchecked, staff will only be able to see public forums.
Access Permissions - Workspace Inbox Controls whether the inbox will be visible to staff members.
Can view own requests ONLY This is a very limiting permission allowing a user to only view their own requests as well as limiting searching and filtering.
Limit to assigned categories ONLY
The user can only see other users and assign to other users in the same categories they are in.

Assigning Staff to Permission Groups

Administrators can assign staff members to a permission group on the Staff page inside of the Admin panel. Only one permission group can be selected per individual.

Using Permission Groups in Filters and Responses

When setting up a filter or response, permission groups can be selected as a criteria for sharing the item. Multiple permission groups can be selected for sharing in the filter or response. 

10.7. System

The Systems box within the Settings page contains the general system configurations for the installation. Each group of settings are described below.

Keep in mind: any changes to these settings will take effect once the Save button is hit at the bottom of the page.

Help Desk Name

The name provided here will be used throughout the installation where the name of the desk is referenced. For example: the top left corner of the HelpSpot for logged in Users, the display name in placeholders, and on the portal.

Default Send From

HelpSpot will look to the mailboxes for populating the drop-down for selecting the default send from account, therefore email integration is required prior to setting this default.

The default selected here will be used as the default 'From' in the recipients mail client. IAN: what happens if I'm not using email integration?

Language

By default, HelpSpot ships with one language file, English-US. You can however create additional language files for HelpSpot to use (seeLanguage Files - Modifying Language Packs). If additional language files have been created they will appear within this drop down field.

Default Contact Method in Request Form

Administrators can set the default contact method on the drop-down when Users use the Create Request form. Contact methods include: phone, email, walk-in, mail, other, forum, instant message, fax, and voicemail. Administrators can also opt to set no default which will force the User to select the contact method prior to initially saving.

Allow Batch Closing of Requests

Enabling batch closing gives all Users the ablity to change the status and close multiple requests, without going into each individual request.

See the Quick Actions section of the Users Manual for more detailed information on how batch processing is preformed.

Allow Batch Responding/Editing of Requests

Selecting 'Yes' for this will allow Administrators and Help Desk Staff level Users to preform a batch updating/editing. Similar to batch closing, batching responding/editing allows for responding and/or editing any field within the request details without entering the request page for each request.

See the Quick Actions section of the Users Manual for more detailed information on how batch processing is preformed.

Guest and Level 2 Limited Access Modes

Guest/Level 2 level Users will be limited to seeing, working, and assigning only within the categories to which they are assigned. Requests outside of those categories will not be accessible to these level Users while this mode is active.

This mode is most often used when an installation allows access to multiple organizations, such as external vendors, for the purpose of working Customer requests.

IP's authorized to call tasks.php and tasks2.php

Tasks.php and tasks2.php are the files resposible for mail integration and the excuation of all automation and mail rules. Administrators that wish to create an level of security around these files should list the IPs in the box provided that are authorized to run the files. When IPs are provided, no other IP will be able to run either file. If the field is left blank, the files will be accessible by any IP.

RSS Feeds Enabled and RSS Feeds Copyright Notice

The simple 'Yes/No' drop-down sets if the installation will offer RSS feeds for any of the filtered views. For those that opt to allow RSS feeds, they many also wish to specify a copyright/usage notice to all readers.

Delete requests after this many days in the trash

HelpSpot will hold all request that have been put into Trash for the amount of time designated within this drop-down. Administrators can choose from 1 day-never. HelpSpot defaults to 30 days, however Administrators should be aware that no matter the time frame selected, deleted items are in no way accessible.

Request Note Draft Save Frequency

HelpSpot has a built in draft save function that periodically saves a Users note and with one click allows them to apply any saved version of a note. The default frequency is every 30 seconds, however this can be changed by using the field provided to type (in seconds) the desired save frequency.

Request History Rendering

Administrators can set how the request history is rendered for Users on the request page. HTML can be displayed, escaped, or removed. HTML is the default and recommended for most installations.

10.8. Date and Time

HelpSpot provides Administrators the ability to configure date/time display to conform to local preference.

Each setting within this box relates to a date/time format used within the installation.

System Time Zone

As part of the installation process, Administrators are asked to provide the time zone. This time zone will be used to display all dates in the system.

Date Format

This long date format can include: month, day, date, year, and time and can be configured in a number of ways. For example: DD, MM YYYY, TT:TT or Day DD, MM YYYY, TT:TT.

The provided drop-down is a quick way to select format or Administrators can type the desired PHP date format.

Short Date Format

The primary difference between the short date and long date, above, is the exclusion of time in the short date. A sample use of short date includes the check request page on the portal.

Configuring short date functionally is the same as the long date, as described above.

Popup Calendar Date Format

To ensure the date/time used by the popup calendar conforms to all other date formats, Administrators can configure the format through the use of the drop-down provided.

Popup Calendar Short Date Format

As with short date configuration, this setting option allows Administrators to set the short date format for the popup calendar.

10.9. Business Hours

Business hours allow you to configure your helpdesk's hours of operation. These settings are accessed in Admin > Settings > Business Hours. Business hours are important to configure because HelpSpot uses these settings for calculations such as First Response Speed and Resolution Speed. In addition these settings can be used to control when triggers and automations are in effect.

The first area of the business hours page allows the configuration of HelpSpot's default business hours. The lower area of the screen allows you to configure holiday hours. These hours override the default settings. Holidays can be configured to block off an entire day or to modify the hours of operation.

Video Tutorial

10.10. Email Integration

This email integration area allows Administrators to configure outbound messaging, as well as general mail preferences.

Administrators should keep in mind that to properly integrate an existing email support account with HelpSpot, they must set up email integration and create a Mailbox. For more on creating a mailbox, see the Mailboxes page referenced below.

Outbound Email Configuration

Note: HelpSpot will use this configuration for all outbound emails (User notices and outbound customer messages), however these settings can be overridden (if configured as such) by the creation of a mailbox.

Notification Email Address

In order to send notifications and replies, HelpSpot must have a 'reply to' email address designated. For the recipient of these messages, this email will be the 'From' in the mail client.

For Administrators using email integration this will simply be an account specified when creating mailboxes. By selecting an existing integrated account, they ensure all message sent to the notification email are integrated into HelpSpot.

For those not using email integration, keep in mind the notification email is for outbound use only and no messages sent to this address will be captured by HelpSpot.

Notification Email Address Name

In addition to specifying the notification, or outbound, email address, Administrators must set the name of the account as it will display in the recipients mail client.

Send Outbound Email Via

If you have already set up a mailbox with an API integration or SMTP configuration you can select that mailbox to send your outbound email via. This is the best option in most cases.

A separate SMTP configuration can also be configured on this screen if desired.

Administrators can opt to use PHP mail function or an SMTP server to send all outbound messages. Note that PHP mail is limited in use to only non-Windows installations.

SMTP Mail Settings

When SMTP is used, the following settings must be provided:

  • SMTP Security Protocol. Most installations will not have to configure this and can leave the default, none. Those running servers requiring a security protocol, can configure as such.
  • SMTP Host. Provide the host name. Multiple names should be listed without any spaces and separated by a semicolon.
  • SMTP Port. The standard port is usually 25, secure is 465. These can vary by server, so check with mail provider.
  • SMTP Authentication. Indicate if your mail server requires username/password for authentication.
  • SMTP Username/password. If required, and Yes is selected above, provide account username and password.
  • SMTP Helo. Most installation will not require this, however those that do can provide it here.


Notification Email Address

This is the email address HelpSpot uses as the "reply to" when sending notifications. Using a mailbox integrated into HelpSpot will allow for continued tracking of all exchanges.

Notification Email Address Name

This is the displayed name shown in emails sent from this account.

Request ID Prefix

This is used only for those attempting to send requests between HelpSpot installations. For example, the IT and maintance departement have seperate installations but have the need to send requests to each other. So no installations requests are overwritten, they can proceed each request ID with letters to identify their installlation.

The balance of the settings on this page apply to all INBOUND messages, regardless of the mailbox the message entered in from.

Allow Email Attachments

This simple yes/no drop-down allows Administrators to specify if attachments are imported with incoming email messages. If no attachments are permitted, HelpSpot will strip the attachment prior to importing the message.

Because HelpSpot deletes all messages from the mail server after importing, it is recommended that this be left at the default of yes to ensure no important attachment are lost.

Do Not Allow Attachments with These Extensions

To prevent potentially malicious files from entering HelpSpot, Administrators can specify file types that will be stripped from imported messages. By default HelpSpot lists: exe and vbs. Additional file extensions can be provided in a comma separated list.

Max Attachment Size

The default maximum file size for attachments is 50MB; providing a reasonable balance between sharing of critical files and conserving database space. This can be increased/decreased based on individual organization need.

Reopening Closed Requests

By design, HelpSpot will re-open a request if an update is sent in within 30 days of closing. Administrators have the option of specifying the number of days or setting to 0, which will always force HelpSpot to re-open closed requests when updated. 

Using the default setting helps in keeping new issues from being lost among those that are newly submitted, but done using an old request.

Maximum Emails to Retrieve at Once

To prevent the system from attempting to pull in more emails that in can handle, and run the risk of timing out before messages are retrieved, HelpSpot allows Administrators to limit the number of messages pulled in, per mailbox, for each run of tasks.php. The default provided is 10. It's not recommended that you ever set this to higher than 30.

Duplicate Email Protection

When installations use auto-replies for inbound messages and a message is sent to a customer that has an auto-responses set for their account, a 'loop' will occur where the same messages are continually being sent and new requests created. To prevent this from occurring, HelpSpot has a setting that defines the number of previous message that will be compared to the current (for exact body and subject) to determine if a request will be created.

HelpSpot provides 600 as a default, however changing to 0 will disable this feature.

Enable tasks.php Debugging Output

When setting up your email integrations or if a problem arises you may want to turn this on. Once enabled, when you visit tasks.php via your browser to manually run the process debugging information will be show (it can be useful to 'view source' in the browser for a cleaner view).

10.11. Email Mailboxes

Mailbox Settings

Admin > Email Mailboxes

Mailboxes are how HelpSpot imports new emails from customers and converts them into requests or request updates. A mailbox in Helpspot establishes a POP3 or IMAP connection with the mailbox on your email server. It then imports messages found in the inbox and processes them for inclusion in Helpspot.

Account Name —Name shown in emails sent from this account. You can use placeholders in this field to dynamically insert data like the acting agent's name.

Account Name — The email account that maps to this box ie: support@mydomain.com.

Mailbox — Normally INBOX but can be any folder within the account. This can be used to retrieve email from a different IMAP folder if desired.

Archive Mail — With this enabled mail will be moved to a "helpspot_archive_folder" instead of deleting the email. This only works with imap. Note: HelpSpot deletes emails from the mailbox if this is disabled.

Host Name — This is the hostname of the IMAP or POP3 server you wish to retrieve email from. You will obtain this information from your email provider.

Username — The username used for IMAP or POP3 authentication.

Password — The password used for IMAP or POP3 authentication.

Account Type — The protocol of the account your are connecting to. Options are:

  • POP3
  • POP3s
  • IMAP
  • IMAPs
  • NNTP
  • NNTPS

Port — The port that you wish to establish a connection with your email server on. Usually 110 for POP3, 143 - IMAP, 995 - POP3S, 993 - IMAPS

Security Type — If you are establishing a secure connection you will need to select the correct security type for your email provider.

Default Category — Email to this mailbox will automatically be assigned to the selected category.

Enable Auto Reply — This setting will send an automatic reply to a customer when they create a new request through this mailbox.

SMTP Setting to Use — You can set this to use the system default settings that are found in Admin > Settings > Email Integration or you can specify custom settings here. This is especially important if your SMTP provider requires that the reply-to address match the sending account credentials.

Email Templates —Templates here will override versions found in system email templates (Admin > Customize > Email Templates) when emails are sent from this mailbox. If you do not specify a custom template the default will be used.

 

 

10.12. Customer Tools

HelpSpot Customer Tools allow for the export and deletion of customer data. You will find the customer tools in the Admin area of HelpSpot.

Export

The export option in the customer tools will export all request details and public notes as well as public attachments for the entered customer email address. This export is generated as a zip file that can be downloaded and sent to the customer.

Deletion

Customer information deletion has a few more options as it can be used with GDPR requests, purging passwords, PHI, and payment information that accidentally makes its way into HelpSpot. All of the deletions done through this screen are permanent so it is important to make sure that you select the right data to delete.

Request Note Deletion

Customer information can be deleted at the individual request note level. Request note IDs can be retrieved by using the request note menu next to each note. When you delete a request note that individual note along with any attachments in that note will be deleted from HelpSpot.


Request Deletion

Moving one level up. An entire request ID can be deleted from HelpSpot by providing the request id. All notes, history events and attachments will be deleted in this case.

Customer Deletion

Finally, customer information can be deleted based on Customer ID or Customer Email address. This will delete all requests and attachments found for this customer in HelpSpot. 

 

11. Troubleshooting Guides

11.1. Turn On Debugging and Logging In HelpSpot 5

There are two debugging / logging settings in HelpSpot 5 that can be enabled. Both of these settings are found in the .env settings file in the root of your HelpSpot install directory.

HelpSpot Cloud customers, please contact customer support for debugging assistance.

The first setting that can be enabled is:

  • APP_DEBUG=true


This setting will enabled the display of errors and stack traces in the browser when they are encountered. It is set to false by default.

The second setting is not included in the .env file by default. To enable it you will need to add this string:

  • LOG_LEVEL=debug


This setting will cause more details on certain processes in helpspot to be written to the helpspot.log file located in helpspot/storage/logs/helpspot.log.

Note, that when changing these settings you will need to restart supervisor or windows helpspot services in order for them to take effect for logging items like mail retrieval and sending queue jobs.

11.2. HelpSpot Speed and Performance

If you are noticing speed or performance issues within your HelpSpot installation, here are a few places to check on.

Note that these apply to HelpSpot Cloud installations as well.

Updating Requests are Slow (only applies to HelpSpot v4 and below)

If HelpSpot hangs / is slow when updating a request, this is most often related to HelpSpot sending emails when updating the request. This usually happens when a request update sends multiple emails

Multiple email notifications may be sent under a few different conditions:

  • Triggers may add an email notification if a condition is met when updating a request
  • Any staff who are subscribed to a request will generate an additional email send
  • Any staff being notified on a Private or External request update will generate an additional email send

However, some Exchange mail servers intentionally cause delays between sending multiple requests.

Slow Workspace

Sometimes staff see slowness when navigating around the Workspace section of HelpSpot.

This is often related to having many filters defined, or having a filter that results in a "heavy" database query.

Often filters have a count of found requests next to them. HelpSpot has to run the filter in order to get this number, so in some conditions, many filters are being run all at once as users click around the Workspace. This can result in a pile up of expensive database queries.

The filter result count is saved (cached) for up to 5 minutes, however depending on how HelpSpot is used, the cached count may get invalidated often enough to cause slowness within HelpSpot.

HelpSpot admins can check on what filters may be causing issues in Admin > System > Filter Management. Problem filters will often be highlighted in red. These are ones whose database queries take over 1 second to complete.

The query time is an average, so seeing something take over 1 second often means many queries are taking longer. Query time may vary depending on the current load against the HelpSpot database.

To reduce issues caused by filters, you can:

  1. Delete unused or rarely-used filters
  2. Remove the option to show the request count next the filter ("Display count in Workspace" option)
  3. Reduce the number of people who can see a filter
  4. Reduce filters to only query within certain times or filter down to more specific sets of requests (this often helps but has potential to make the queries take longer! Test your filters with the "Run Filter" button before saving them).

 

 

 

11.3. Microsoft SQL Server

Connecting to a Named Instance

In order to connect to a named instance of SQL Server you will need to configure an alias for that instance as described here: http://support.microsoft.com/kb/265808

That will allow a direct connection to that alias from the HelpSpot Windows installer.

Connection Troubles

  • ntwdblib.dll - The most common issue is that you do not have the ntwdblib.dll file installed in your PHP directory (where php.exe is, or sometimes placing it in the ext directory works as well). This library can be found with your Enterprise Manager dll's or in your SQL servers system32 folder. It's generally best to take the file from the server where SQL Server is installed.

    Related forum post: Unable to connect to the database

    PHP.net: Information on the PHP MSSQL extension, lots of good tips in the user comments

  • ntwdblib.dll Version - On some systems the ntwdblib.dll version is too old to work correctly with PHP. If your version does not end in 80.194.0 it's probably too old. You can download the 80.194 version here.

  • SQL Client Tools - On some servers you will need to install the SQL Server client tools. This is especially true if your SQL Server is on a different server than your web server.

  • (local) Registration - If your SQL Servers registered name is (local) you'll need to delete that registration and change the registration to the machine name. You should then be able to set the cDBHOSTNAME in config.php to 'localhost' and be able to connect.

  • SQL Authentication - The SQL Server must be setup to use both SQL Server authentication and windows authentication. Both for the user as well as the server as a whole. This setting is in SERVER_NAME->Properties->Security

  • privileges - The HelpSpot database user must have sufficient privileges to access the database. Making them the database owner will work, though other configurations may also be effective. The database user will also usually need to have public access enabled.

  • port number - On some PHP/SQL Server installations you'll need to provide the port number your SQL Server listens for requests on. You can do this by adding a comma and the port number to the cDBHOSTNAME variable like this: "db.mycompany.com,1433"

  • TCP/IP in SQL Server 2005 - In order to connect by IP you may need to specifically allow that protocol by going to the SQL Server Configuration Manager, go to protocals and then enabled TCP/IP.

  • Registry key - In rare cases an edit to the registry may help.
    [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSSQLServer\Client\ConnectTo]
    "DSQUERY"="DBNETLIB"

Error: "The statement has been terminated."

In extremely rare cases SQL Server can lose seeding on the HS_Request table or another tables, primary key. If this occurs inserts to the database will fail with this error. You can check if this is the case by running the following in management studio:

DBCC CHECKIDENT ('HS_Request');

If the current seed value doesn't match the current column value (it will be less) than there's a problem. You can reseed the tables primary key with this command:

DBCC CHECKIDENT ('HS_Request',RESEED,######);

where ###### is the new ID value. Make this a few higher than the current highest value in the table. That should resolve the issue.

Moving from local SQL Server to SQL Server on RDS

Use SQL Server Management Studio and select the database that will be used as the source. Right click on the database and select the generate scripts task. Select advanced, scroll to types of data to script and select Schema and Data. Once the file is saved, open it to make some minor changes for Amazon RDS compatibility.  Change the path in the FileName section of the script to be D:\RDSDBDATA\DATA\ instead of the default C:\Program Files\..... . Save the script. Next, run the script to import the data and the schema. The last step is to open security on the newly created database and ensure that the user created in the script has db_owner rights to the database.
 
Performing the above steps, allowed the user to copy the schema and the data from a SQL Server 2008R2 instance on a traditional Windows Server 2008 R2 instance and migrate it intact to an Amazon RDS instance.

11.4. Microsoft Exchange Server

Exchange 2010 Slow Delivery / Request Duplication

Exchange 2010 has a new tarpit feature that forces a 5+ second delay between each email sent on a connection. This is designed to help combat spammers, however, it's often necessary for HelpSpot to send a group of emails at once and this feature of Exchange can cause problems. At the very least it slows down email sending causing the request screen to feel slow on updates. More significant issues can be seen if your installation does a lot of notification emails to staff on import as each email will have a 5 second delay between them meaning importing a single email could take a minute or more. In such cases the scheduled tasks which pull in email may end up duplicating some requests as one running of tasks.php is still going (due to the delay) while a second is initiated.

The setting in Exchange can be checked with this command:

Get-ReceiveConnector "connectorname" | select tarpitinterval

The setting can be turned off with:

Set-ReceiveConnector "connectorname" –TarpitInterval 00:00:00

Make sure to run the command for each connector name your installation has.

Acknowledgement Delay

Sometimes Exchange 2010 still has delays in sending multiple messages. Exchange may be making HelpSpot wait until it has received confirmation that a sent email was received by the recipient mail server. This is called "acknowledgement delay".

To eliminate the acknowledgement delay, run the following command:

Set-ReceiveConnector "SMTP Application relay" -MaxAcknowledgementDelay 0

Exchange 2010 Rate Limit Exceeded

The setting in Exchange can be checked with this command:

Set-recieveconnector "Server Name\Client Connector" -Messageratelimit 500

Connection Troubles

  • Pop3/IMAP - Make sure Pop and/or IMAP is enabled on your Exchange server. These options are often off by default.
  • Password - If your POP or IMAP password contains a backslash (ex: \ ) this will break the connection. Remove the backslash from your Exchange password and the connection should work.
  • NOTLS - On Exchange 2007 it is sometimes necessary to choose the NOTLS security option.

Kerberos Error

"Kerberos error: Credentials cache file '/tmp/krb5cc_33' not found (try running kinit)" Note that the number appended to the cache file may be different.

This error can occur if the number of simultaneous connections exceed the limit. The Exchange error log should show the errors. Restarting Exchange usually clears the issue.

Using IMAP or IMAPS instead of POP/POPS within HelpSpot's Email Mailbox configurations can also alleviate this issue if the error is seen.

Routing through IIS

It can sometimes be useful to route email via IIS's built in SMTP relay system. Note, that in some configurations you may want to set this up to forward the email to Exchange from IIS. The basics on setting it up can be found in this article: http://www.geeksengine.com/article/php-microsoft-smtp.html

PHP Bug 33500

There is some evidence that Microsoft Exchange Rollup 7 fixes the issues below. Please upgrade to rollup 7 before trying any of the below procedures.

Items below relate to PHP bug: http://bugs.php.net/bug.php?id=33500 which affects Exchange 2007.

Note, that the first thing to check before doing the below is that your Exchange server is set for

"Plain text logon (Basic authentication) No TLS connection is required for the client to authenticate to the server"

and NOT

"Plain text authentication logon (integrated windows authentication) No TLS connection is required for the client to authenticate to the server"

If you have multiple front end Exchange server be sure all are setup for basic plain text login.

Also be sure you don't have any # in your mailbox passwords.

Authentication Trouble on Exchange 2007 - Kerberos

Under certain configurations in Exchange 2007 having Kerberos setup is required in order to connect to the Exchange server. A customer contributed these steps on how to set that up in a Linux environment.

Step 1:
Edit the krb5.conf file to match your domain environment.

Step 2:
Create a script to check the mail that creates the ticket if it does not exist already then checks the mail. This script should be called via cron instead of tasks.php directly:

/usr/kerberos/bin/klist -c /var/tmp/apache | grep -q krbtgt || echo <mailboxusename> |
/usr/kerberos/bin/kinit -c /var/tmp/apache <mailboxusename>
export KRB5CCNAME=/var/tmp/apache

/usr/bin/php /var/www/html/helpspot/tasks.php

Step 3:
Add another crontab entry that renews the kerberos ticket every hour:

/usr/kerberos/bin/kinit -R -c /var/tmp/apache

Alternative: Recompile PHP with IMAP Adjustment

On Linux based installations recompiling PHP and making an adjustment to the IMAP source is also a possible solution. This method was tested on CentOS 5.1 and is still needed at least up to PHP 5.2.9.

  1. Download the latest IMAP Toolkit release at ftp://ftp.cac.washington.edu/mail/imap.tar.Z
  2. Extract the files, then open up imap-2007/src/osdep/unix/Makefile and go to line 1002. Comment out the following section:
    ckpgss: # Kerberos V (must have gss EXTRAAUTHENTICATOR as well)
            @echo Kerberos V password authentication
            $(LN) ckp_gss.c osdepckp.c
    
  3. Save the file and exit. Change dirs back to the imap-2007 directory and build with the following: 
    make slx SSLINCLUDE=/usr/include/openssl SSLTYPE=nopwd
  4. Once complete, download the latest PHP from php.net. Extract the files, then run configure with the following options (you may need to adjust these options as needed for your setup):
    ./configure --without-kerberos --with-zlib --with-curl=/usr/lib --enable-dba --with-gd --enable-gd-native-ttf --with-jpeg-dir=/usr/lib --with-png-dir=/usr/lib --with-zlib-dir=/usr/lib --with-imap=/PATH-TO/imap-2007 --with-imap-ssl --enable-mbstring --with-mysql=/usr/lib/mysql --with-mysql-sock --with-mysqli --enable-soap --enable-sockets --with-pear --with-mcrypt --with-openssl --with-xml --with-apxs2=/PATH-TO/apxs --enable-memory-limit --enable-track-vars --enable-wddx --enable-ftp --enable-sysvmsg --enable-sysvem --enable-sysvshm --enable-transid --enable-cli --enable-cgi --with-ldap
  5. There may be a bunch of package dependencies (like libmcrypt, libmcrypt-devel, openssl, openssl-devel, httpd-devel, etc.) that I won't go into here. Basically, if configure errs out and complains about a package not being installed, then install it and go from there.
  6. Then run make, make test, and finally sudo make install.
  7. Once it's installed, you'll need to add the following to /etc/httpd/conf/httpd.conf if you don't have it already:
    LoadModule php5_module /usr/lib/httpd/modules/libphp5.so
    AddType application/x-httpd-php .php
    AddType application/x-httpd-php .phtml

  8. Restart Apache and you should be all set.

11.5. MySQL

How to Repair a MySQL Table on Windows

If you've used our Windows Installer and need to rebuild a table this is how to do it. If you're experiencing odd behavior such as filters with counts not actually showing the requests when entered this could be the case.

Steps to repair the table:

 

  1. Open the command prompt
  2. enter: cd "c:\program files\helpspot\mysql\bin"
  3. enter: mysql -u HELPSOT_USER -p
  4. enter your password when asked
  5. enter: use HELPSPOT_DATABASE;
  6. enter: repair table HELPSPOT_TABLE;
If you need to find the HelpSpot username, database, or password you can find them in config.php in the root HelpSpot directory.

 

Table Creation Errors

On some MySQL servers during installation only some of the tables will be created. Normally when this error occurs it's about 19 tables that are created. When this occurs the screen of the installer will often turn blank white while trying to complete installation.

This error is caused by MySQL being set in STRICT mode. Your my.cnf or my.ini file probably has a line similar to this:

sql-mode="STRICT_TRANS_TABLES"

Removing the strict restriction should allow installation to complete normally.

11.6. MySQL - Convert Lowercase Windows Table Names to Mixed Case for Linux/Unix

When converting a MySQL database from Windows to Linux/Unix the Windows server will often export the database table names in all lowercase. HelpSpot on Linux/Unix requires mixed case table names.

This script will convert the lowercase names into proper mixed case names.

There are separate scripts for V2 and V3

Usage:

 

  1. Place this file in the same directory as config.php
  2. Visit the script in your browser
  3. Delete the script

11.7. Microsoft IIS

PHP CGI Error in IIS

On some PHP installations running as a CGI on Windows IIS a CGI 502 error is received at random. This is a bug in the interaction between PHP and IIS and is not HelpSpot specific. It appears to happen most on fast servers which are under low load. One options is to run PHP as an ISAPI module. However, if you would prefer to keep it as a CGI there appears to be an effective workaround for the issue.

The workaround works by telling Windows to optimize for foreground applications instead of background services. This appears to slow down the processing enough so that IIS doesn't throw an error. Please be aware that this is a system wide setting and will affect the overall speed of your server to some degree. If you change this setting it is highly recommended that you keep close watch on the server afterwards to make sure none of your applications have been adversely affected.

On Windows Server 2003 go to: Start -> Control Panel -> System -> Advanced (tab) -> Performance (settings) -> Advanced (tab) -> and switch "adjust for best performance of" to "Programs". Apply the change and the effect should be immediate.

On Windows 2000 go to: Start -> Settings -> Control Panel -> System -> Advanced (tab) -> Performance (performance options) -> Select "applications". The change should be immediate.

This solution was discovered in the discourse of this PHP bug history: http://bugs.php.net/bug.php?id=9852

Note: that this solution does not always work when PHP is used with the MS SQL extension. When this solution fails while using the MS SQL extension the only solutions appear to be to switch PHP to ISAPI or switch to using MySQL or PostgreSQL.

IIS Crashes every few hours or more, tasks.php takes a significant time to run

An upgrade to .net version 3.0 can partially cause this issue. Note that .net is not used by HelpSpot, but the upgrade causes permission issues which cause IIS to be unstable. This situation can be fixed following the information in this article: http://support.microsoft.com/kb/918041.

If the situation persists after the fix uninstalling .net v2 may be needed using aspnet_regiis.exe -u followed by aspnet_regiis.exe -u started from: C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727

Live Lookup fails to load

This can sometimes be happen when using IIS due to it's low maxQueryString setting. Resources and details on how to adjust that:

Process:
  • Control Panel > Administrative Tools > Internet Information Services (IIS) Manager
  • In the Connections pane, drill down to the relevant site you want to modify. Something Like SERVER > Sites > Default Web Site.
  • In the Home pane for Default Web Site, open Request Filtering.
  • In the Action pane, click Edit Features Settings.
  • Maximum query string defaults to 2048; set it to 10240 and click OK.
  • Close IIS Manager, and restart the World Wide Web Publishing Service.

Attachments Do Not Upload to a Network Drive

HelpSpot allows the Attachment Storage System to optionally save to the file system, rather than the database. If you have set the file path to a network drive (typically a path such as "\\path\to\shared\directory") and attachments are not successfully being saved, it is important to ensure proper credentials are set. If the IIS worker processes runs under a user who has permission to write to the network drive and attachments still are not saved correctly, then the Application Default settings may need to be set with the username and password of the user with permission to write to the network drive.

Process:

  1. Within the IIS Manager, select your site from the Connections pane on the left by clicking on it. This is typically labeled "Default Web Site".
  2. Click the "View Applications" link in the Actions pane on the right.
  3. Options within the Actions pane will change. Click "Set Application Defaults" with the Actions pane.
  4. Next to "PhysicalPathCredentials", click the empty field with the smaller button containing three dots(...). This will open a new window labeled "Connect As"
  5. Choose "Specific User", Click the "Set" button, and enter the username and password of the user who has permission to write to the shared drive.

A. Pictured: Click the "View Applications" link in the Actions pane on the right.

B. Pictured: Set Application Defaults, Choose Physical Path Credentials, Select Specific User, Enter Credentials

11.8. IIS: WSUS (Windows Server Update Services) And HelpSpot - 500 error

If you are using Microsoft IIS and install WSUS (Windows Server Update Services), you may receive an 500 error post-installation when viewing HelpSpot. This usually says there is an issue with the web.conf file, however that is a generic error message.

If you see the Module in question in the error message is the CompressionModule, this is a known issue. (You'll have to access HelpSpot locally on a browser within the web server to see the full error message).

This issue is outlined and resolved here: http://forums.iis.net/t/1149768.aspx?500+19+Error+When+Enabling+32+bit+Application+Pool

WSUS enables a CompressionModule, which is not compatible with HelpSpot's installation. To resolve this issue, you must disable the CompressionModule. TO do so, run the following command (taken from the previous linked article) and run it in the CMD prompt. This command will not work within PowerShell:

%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/httpCompression /-[name='xpress']

 

 

11.9. Portal Pages Sometimes Return Blank

This error is sometimes found on servers running Apache 1.3 and using the mod_gzip module. To fix this error create a .htaccess file in the base directory of your HelpSpot installation. Within the .htaccess file add the following line:

mod_gzip_item_exclude file .*

Save the file and the blank pages should stop appearing.

11.10. Month names are not translated

You can adjust the date and time that HelpSpot displays by going to "admin -> settings -> date and time" and then selecting the proper format from the drop-down lists. This setting will only adjust the way it's formatted and if you would like to have the month names translated then you can edit the lg.charset.php file and adjust the setlocale line: 

setlocale(LC_ALL, 'en-us','english');

For example to have month names displayed in Swedish you could use: 

setlocale(LC_ALL, 'sv_SE', 'Swedish', 'swedish');

If you've made that change and the month names are still in English then your server may not have the locale installed. 

You can verify a list of installed locales on Unix/Linux servers by running: 

locale -a

If yours is not displayed in the list, you can utilize the locale-gen command to install additional: 

locale-gen de_DE de_DE.utf8

11.11. fPinned Duplicate Column Error

Note: This error has been fixed in the latest version 4.5.4+ of HelpSpot. Please download the latest installer.

Some customers have run into an error when installing the 4.5 update that indicates there is a duplicate column named fPinned on the HS_Request_History table. This error can be fixed by following the steps below.

  1. Open up your helpspot database in the database editor of your choice.
  2. Run this query: Select * from HS_Migrations;
  3. Look at the last migration listed in the results and note the number in the "batch" column
  4. Run this insert query to add the needed migration history to the database
INSERT INTO `HS_Migrations` (`migration`, `batch`)
VALUES
	('2016_02_18_211111_add_pinned_to_request_history', 2);
Edit the batch value to reflect the value that you noted above. After running this insert query you can return to the installer page and continue with the installation.

11.12. LDAP connections with Self-Signed SSL

If an LDAP server being utilized with HelpSpot does not a have a publicly trusted cert the PHP LDAP DLL needs to be configured with the proper settings to allow it to connect.

There are two options:

Note: The windows PHP libraries are hard-coded to look for an open ldap config file (ldap.conf) in C:\openldap\sysconf\ldap.conf. On linux you should be able to find it in /etc/openldap/ldap.conf

  1. Create the ldap.conf text file mentioned above - this is where you point to your certificate store. Once you create this file, in the needed location you can begin to edit it.
  2. The first options is to put in TLS_REQCERT never … but this means no certs are verified and all are trusted automatically.
  3. Instead of the TLS_REQCERT never option we can also create a cert file that contains the certificate hashes
  4. Edit the ldap.conf file and add a line for the command TLS_CACERT like TLS_CACERT C:\path\to\my\cert.pem
  5. To add a certificate as a trusted in the cacert.pem file, simply get a copy of the public key of the certificate in question (this needs to be exported in base64 format).
  6. After making such changes, you will need to restart your web server.


11.13. Blackbox ADLAD Error on PHP 7.4+

When using the adldap library for blackbox authentication with php 7.4+ the adLDAPUsers.php file needs to be updated for compatibility. In custom_code\classes\adLDAPUsers.php find this line:

        for ($i=0; $i <strlen($password); $i++){ $encoded.="{$password{$i}}\000"; }

and change it to:

        for ($i=0; $i <strlen($password); $i++){ $encoded.="{$password[$i]}\000"; }

12. Installation Troubleshooting

12.1. APP_URL is invalid

Error Description:

APP_URL is invalid.

Causes:

.env File is not configured correctly

The .env file needs to have an APP_URL defined. The APP_URL is the url that resolves to the public folder of your helpspot installation. It should be in standard http URL format.

Examples:

Secure Subdomain DNS

APP_URL=https://helpspot.company.com

URL with port

APP_URL=http://myinternalapp:8080

IP address

APP_URL=http://192.168.0.1

DNS or Webserver Configured Incorrectly

Proper DNS configuration and web server configuration is required in addition to an accurate APP_URL setting. The APP_URL only controls how HelpSpot builds URLs. If your DNS is not pointing to the server or if you web server is not configured to receive connections and direct the browser to the public folder the APP_URL will not work properly.

Invalid or misconfigured SSL certificate

If your server has an invalid or misconfigured SSL certificate you may receive this error along with details on the nature of the issue.

12.2. APP_KEY Missing during installation

Error Description:

APP_KEY is not defined.

Causes:

.env File is not configured correctly

The .env file needs to have an APP_KEY defined. APP_KEY is used for encryption inside of HelpSpot. To generate your app key run this command using the HelpSpot command like tool.

php hs install:key

12.3. Database Connection Error During Installation

Error Description:

HelpSpot can not connect to the database. Please check your database settings in the .env file.

Causes:

.env File is not configured correctly

This error could be caused by having improper information in your .env configuration file. The follow variables need the correct values before the installer can continue:

DB_CONNECTION - one of mysql or sqlsrv.
DB_HOST - The hostname or ip of your database server
DB_PORT - For SQL Server the default for this is 1433. For mysql the default port is 3306.
DB_DATABASE - This is the name of your HelpSpot database. This database needs to be created prior to starting the HelpSpot installation.
DB_USERNAME - The username to use when connecting to the database. This user needs to be configured with full rights to the DB_DATABASE defined.
DB_PASSWORD - The password for the DB_USERNAME defined.

Firewall Configuration

Configured firewalls may block connections to your database server if you are using an external database server. A good way to test connectivity is to telnet to the DB_HOST and DB_PORT you have defined.

telnet my.db.server.com 3306

12.4. Incorrect PHP Version

Error Description:

If you receive an error that your php version is incorrect during installation there are a couple of possible issues.

Causes:

Wrong PHP Version Installed

First, it could be that your have an incompatible version of PHP installed and you need to switch the version of PHP installed. The directions for your OS will include instructions on how to install the appropriate version.

Wrong Command Line PHP version being used

You can have a different version of command line PHP running (which the installer uses) that what is linked to your web server. HelpSpot uses command line PHP for the install process and well as for background processes after installation. You will need to make sure that your command line version of PHP is compatiable.

12.5. HelpSpot's 'storage' dir is not writable

Error Description:

If you receive an error that your HelpSpot's 'storage' directory is not writable there are a couple of possible issues.

Causes:

File Permissions and Ownership

File permissions and ownership need to allow reading, writing and modifying of files in the storage directory of HelpSpot.

Windows with IIS

On windows with IIS the iUSR user should be granted full control of the storage directory and all subdirectories.

Ubuntu

On Ubuntu the web server will by default be running under the user www-data. So running sudo chown -R www-data:www-data storage/ on the storage directory should solve most permissions issues.

CentOS / Redhat

On CentOS / Redhat the web server will by default be running under the user apache. So running sudo chown -R apache:apache storage/ on the storage directory should solve most permissions issues.

 

13. HelpSpot Hacks

13.1. Converting Attachments from Database Storage to File System

HelpSpot allows the option to save all request file attachments in the database. This makes for easy backups. However, on some high volume installations or installations which deal in many large attachments it's better to save the attachments to disk to prevent the database from becoming unwieldy.

Moving to File System Storage

  1. Create a directory to store attachments in. This directory should be outside the web root and writable by the web server.
  2. In Admin->Settings->System change Attachment Storage Location to "Server File System"
  3. In the box that appears (Attachment File System Directory) put the full path to the directory you created
  4. Save the settings

Converting Database Stored Attachments to the File System

HelpSpot 4.0+

By default, after the change above HelpSpot will store new attachments to the file system, but old attachments will continue to be stored and served from the database. On version 4 and greater you can use the HelpSpot command attachments:tofile 

HelpSpot 3

If you'd like to convert these old attachments on HelpSpot version 3 to the file system you can use the script linked below do to so. To use the script:

  1. Download the script below, move it to the root HelpSpot folder. This is the one with config.php in it. If using FTP to move the file be sure to force binary mode.
  2. Backup your database (seriously)
  3. Place HelpSpot in maintenance mode to prevent new requests while the script runs (Admin->Settings)
  4. From the command line do "/path/do/php -f /path/to/convert_attach_from_db_to_file.php"
You can run it from the browser if you have no choice, though you may have to restart it from time to time if the web server times out. Note that the file may take hours to run if you have a lot of attachments.
 
Link to script on github https://github.com/helpspot/HelpSpot-Convert-Attachments-to-File-System
 

13.2. Changing Custom Field Lengths

Custom field lengths at the database level are only editable on creation within the user interface. If changes to field size need to be made after creation, these changes must be made at the database level. These instructions are specific to the Text Field type. Note that the following instructions can be destructive (resulting in the truncation of data) if you are reducing field lengths. Because of this, it is recommend to make a database backup before performing these operations.

MySQL

  1. Change the size of text field in the user interface via the custom field setup area (Admin > Custom Fields)
  2. Note custom field ID in this interface.
  3. Access your helpspot database and run this query to change your field size. 
// Replace 'Custom1' with the associated ID for your custom field and replace VARCHAR(25) with the appropriate length.
ALTER TABLE HS_Request MODIFY Custom1 VARCHAR(25); 

SQLServer

  1. Change the size of text field in the user interface via the custom field setup area (Admin > Custom Fields)
  2. Note custom field ID in this interface.
  3. Access your helpspot database and run this query to change your field size. 
/****** Drop the current index on the custom field ******/
DROP INDEX [hs_request_custom1_index] ON [dbo].[HS_Request] GO
/****** Alter the column length ******/
ALTER TABLE [dbo].[HS_Request]
ALTER COLUMN [Custom1] [nvarchar](80) NULL
/****** Rebuild index on the custom field ******/
CREATE NONCLUSTERED INDEX [hs_request_custom1_index] ON [dbo].[HS_Request]
(
	[Custom1] ASC
)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON)
GO

13.3. Search Request History by Customer Email

This template adds the ability for customers to search for their past requests by entering their email address rather than an access key. Searching by email will give them a complete list of all requests ever submitted by that email address. Note that this is completely insecure by default. However, it would be possible to tie the search into an active directory login or LDAP user in order to make it secure, though this template does not provide the code for that integration.

 

13.4. Delete SPAM Without Training Filter

Some customers have very high SPAM counts and cannot delete it all conveniently via the web interface. They no longer need to train the SPAM filter with every SPAM since it's already catching them.

This script will delete all references to any requests currently marked as SPAM without training the SPAM filter. This is a destructive script. It will permanently delete requests and if any real requests are accidentally marked as SPAM when this script runs they will also be deleted.

Instructions for V4 and above

  1. Follow these instructions to access the helpspot command line tool
  2. Use the command: php hs request:delete-spam

Instructions for V3.2.12 and below

  1. Download the delete_spam.php script below
  2. Place the script on your server. It's recommended you run it from the command line and place the script outside the web root so that outsiders cannot run it
  3. Make sure the 2 includes() at the top of the file have the correct paths to the files they're including
  4. Run the script, usually something like: /usr/local/bin/php -f /path/to/delete_spam.php

13.5. Hidden Settings

Several settings are available in HelpSpot that are not part of the user interface in the admin area. These settings are advanced and should only be used if you know they are needed.

Config.php Settings

  • Secure MySQL Connections - Some MySQL setups, especially on remote servers, require a secure client connection. Adding the line below to you config.php file will force HelpSpot to connect securely. Should be used only if you know it's necessary.

    define('cMYSQL_CLIENT_SSL',true);

  • Additional SMTP Security Settings (Version 4.6+) — Some SMTP connections require a specific version of TLS in order to connection properly. Adding this setting will enable additional options on the SMTP setup screens in the admin area.

    define('cEXTRASECURITYOPTIONS', true);

HS_Settings Table

In the HS_Settings table, the items below relate to rows in the sSetting column. Updating the tValue column in rows where sSetting matches the values described below.

  • cHD_BAYESIAN_PROB_SPAM and cHD_PORTAL_BAYESIAN_PROB_SPAM - The probability value an email or portal post must be above to be considered spam.
  • cHD_LIVEREFRESH_TIME - How often in seconds the Live Refresh of the Workspace refreshes the filter currently being viewed.
  • cHD_SAVE_DRAFTS_EVERY - How often in seconds to save drafts of requests notes while on the request screen.
  • cHD_IMAGE_THUMB_SIZE - Size in pixels of image thumbnails created for the request history.
  • cHD_DISABLESHORTCUTS - Change to 1 to disable shortcut commands from being replaced in notes (these are r: k: f: which create shortcuts to requests, KB's and forums respectively)
  • cHD_IMAGE_THUMB_MAXBYTES - The number of bytes an image can be before HelpSpot will stop attempting to create a thumbnail version of the image in the request history.
  • cHD_TAKEIT_DOCHECK - The "Take It" button column in filters by default will check to see if a request is already assigned and if it is, show an error not allowing the clicking user to take the request. This setting allows a change in this behavior where the clicking user will always be assigned the request, no check will be done.
  • cHD_SAVE_LAST_SEARCH - The number of seconds a search done in the search tab is saved for so that when you return it's still there ready to be modified. Defaults to 1200 seconds (20 minutes).
  • cHD_FILTER_COUNT_CACHE - The number of seconds to cache the counts for each filter on the workspace screen. Defaults to 300 (5 minutes). Lowering this value is not recommended. If you need to exclude a particular filter from the cache that can be done under the advanced options for that filter.
  • cFORCE_MERGE_LOCKING - (MySQL ONLY) - force the database to lock all request related tables while merging requests. You should only enable this if you have a good performing server stack for HelpSpot (and plan to keep it that way as HelpSpot grows). If you're on shared hosting or running a large installation on a small server configuration turning this on can cause performance issues due to database contention.
  • cHD_DISABLE_GRAVATAR - Disable gravatar images and always fall back to the default supplied by HelpSpot.
  • cHD_MAX_REQUEST_HISTORY  Set the max number of request history entries that is allowed for any one request. Default is 1500.

13.6. Redirect HTTP Requests to HTTPS

IIS

Note you must have an SSL certificate properly installed and https bindings set up properly in IIS before completing these steps. In addition be sure to edit the APP_URL variable in your .env configuration file for HelpSpot to reflect the https:// url. 

  1. Install the rewrite module in IIS following these directions http://www.iis.net/downloads/microsoft/url-rewrite
  2. Open the IIS Manager and navigate to the site that your helpspot instance is installed on.
  3. Select URL Rewrite and add a new rule.
  4. For the pattern to match input the regular expression.*
  5. Add a new condition that checks if {HTTPS} is off

  1. For the action choose to redirect to https://{HTTP_HOST}/{R:0}

You site should now redirect urls that are http:// to https://

HelpSpot 4 - Installation & Setup

1. HelpSpot 4 Overview

Quick Links

From a server administration point of view, HelpSpot 4 has some new important features:

  • CLI commands available for installing, updating and some specifically for upgrading from version 3 to 4
  • Support for UTF-8 (no longer just the latin alphabet)
  • New "data" directory that contains logs and generated files such as email attachment
  • New variables for the config.php file

Windows

Installing HelpSpot 4 and Updating to HelpSpot 4 requires the provided windows installer file, which installs all dependencies and HelpSpot.

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. Current and past versions of HelpSpot are available for download in the HelpSpot Store.

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

Windows Requirements

Windows users must use the provided HelpSpot installer, which installs all required software, and required PHP modules.

Windows users have the following system requirements as of HelpSpot version 4: Requirements

Linux

Installation

Installing HelpSpot 4 from scratch can now be handled by our installers scripts for linux. Details instructions are provided at https://install.helpspot.com.

Updating

To update from to HelpSpot 4 from previous versions, please see our documentation on Updating to HelpSpot 4.

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. A download of version 3.2.12 will be made available to all customers.

Linux Requirements

Linux server requirement can be found here: Requirements

 

2. 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:

  • If you have not already, you must update to version 3.2.12 before updating to version 4+
  • Downloading the latest version
  • Making the new "data" directory writable by the web server
  • Updating config.php
  • Creating a new database
  • Running a migration from old to new database
  • Installing Sphinx Search (Optional)

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:

  • All files of any Secondary Portal configured
  • All files within the custom_templates directory
  • All files within the custom_pages directory (minus the included "example.php" file)
  • All files within the custom_code directory (except any example code that comes with HelpSpot, "-base.php" files)
  • Any customizations to the themes directories and files found within

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:

  • cDBCHARSET
  • cDBCOLLATION
  • cSEARCHHOST
  • cSEARCHPORT
  • cDATADIR
  • cDEBUG
  • SEARCH_ENGINE (HS v4.6.7 and greater)

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":

  • latin1 - ISO-8859-1. This is the default and does not need defining
  • latin2 - ISO-8859-2 - Central European
  • latin5 - ISO-8859-9 - Turkish
  • latin7 - ISO-8859-13 - Baltic
  • greek - ISO-8859-7 - Greek

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

  • HS_Errors - A log of all errors trapped. The older the errors are, the less relevant they may be. This table can get large during periods where HelpSpot has issues connecting to email systems and similar short-lived events. Truncating older entries in this table can help the conversion process.
  • HS_Filter_Performance - This table tracks the performance of filters in terms of how long a query to the database for the filter takes. This table often has old information in it which can also be truncated.
  • HS_Search_Queries - This table tracks search queries made. Entries in this table may also not be of interest and old data can safely be 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.

3. Installing a New HelpSpot 4

HelpSpot 4 is no longer the current version. Please Refer to HelpSpot 5 Install Documentation.

Quick Start 

Use our installers to get up and running quickly without worrying about the details. Care about the details? Read the full details section farther down on the page.

Windows

You must use the provided windows installer file, which installs all dependencies and HelpSpot itself. Easy!

Linux/Unix/OSX

Use the installation bash script which handles installation of everything other than MySQL and PHP.

 

Full Details: Installing From Scratch

The HelpSpot 4 Overview page shows a general overview for both installing a new HelpSpot version 4 and updating an older HelpSpot to version 4.

Here, we'll dig into the steps to install HelpSpot 4 from scratch. Here are the steps to install HelpSpot 4 from scratch:

Windows

Windows Requirements

Windows users must use the provided HelpSpot installer, which installs all required software and required PHP modules.

Windows users have the following system requirements as of HelpSpot version 4: Requirements

Linux

Linux Requirements

Linux

Linux servers requirements can be found here: Requirements

1. Server Setup

Linux users can start by setting up their server. We have the steps provided to do so in our guides to configuring:

In general, any "LAMP stack" (Linux Apache MySQL PHP) will do for HelpSpot. However the server must have IonCube Loader installed, and you should have the ability to install extra software, such as the SphinxSearch engine.

2. Download HelpSpot and Install:

You can download and install HelpSpot from our HelpSpot store in the Downloads section of your account.

Once the server setup portion is complete (see above), you can download the files in the appropriate section of your web server.

Once the files are installed onto the web server, Linux users can create HelpSpot's "config.php" file by copying the "config-empty.php" file and filling in the necessary information (database credentials, etc) into the new "config.php" file.

Once that's created and edited, you can run HelpSpot's installer, which will install and configure HelpSpot's database. This can be run in two ways:

To install HelpSpot via Web:

Run the "installer.php" web installer in your browser (e.g. http://my-helpspot-site.com/installler.php)

To install HelpSpot via the new "install" cli command.

3. Automated Tasks

HelpSpot has 2 scripts which should be run once per minute.

  • tasks.php - Checks for new messages in each configured Email Mailbox
  • tasks2.php - Checks any configured Automation Rule and runs applicable rules

Windows users will find these already setup via Windows Task scheduler.

Linux users can create 2 new crontasks:

* * * * * /usr/bin/php /path/to/helpspot/tasks.php

* * * * * /usr/bin/php /path/to/helpspot/tasks2.php

Note: Here are links for more detailed information about tasks and tasks2, including how to setup multiple cronjobs for the primary task, in order to check specific Email Mailboxes - useful for high-volume installations!

 

4. HelpSpot Server Setup: RedHat/CentOS

RedHat (RHEL) and CentOS have additional security and configuration that you may not find on Debian/Ubuntu servers. This guide will help you setup a Server on RedHat/CentOS servers that may be missing some PHP modules HelpSpot requires, along with some setup for ensuring HelpSpot will work in environments where SELinux is enabled.

We'll cover setting up an RedHat/CentOS server for use with HelpSpot.

This will install PHP, Apache and MariaDB (a MySQL drop-in replacement). PostgreSQL can alternatively be used.

As of CentOS 7/RedHat 7, MariaDB is the default "MySQL" database available. HelpSpot will work fine with MariaDB and it's replacement of the InnoDB storage engine, ExtraDB.

If you with to use MySQL over MariaDB, however, you can find the appropriate RPMs available for MySQL 5.6 here.

Install Apache & PHP

First we'll install Apache and PHP.

As of CentOS/RedHat 6, a required PHP package "php-imap" (and other optional ones) are not available with the standard repositories. We suggest getting the Fedora EPEL package repository if you are able to. This can be done with one command:

sudo rpm -Uvh \
    http://dl.fedoraproject.org/pub/epel/7/x86_64/e/epel-release-7-5.noarch.rpm

 

Note: If you are using the Amazon AWS RHEL7 image, you may need to enable the Extras and Optional repositories.
To do so, run the following:

# ONLY IF USING AMAZON AWS'S RHEL7 IMAGE
sudo yum-config-manager --enable rhui-REGION-rhel-server-extras rhui-REGION-rhel-server-optional

 

Once that's done, we can install all of the needed Apache and PHP packages:

# Install Apache + PHP
sudo yum install httpd php php-pdo php-mysql php-gd php-mcrypt php-curl php-imap php-xml

# Set Apache to start on boot:
sudo systemctl enable httpd.service

# Start Apache:
sudo service httpd start

Users of SELinux can also ensure that Apache has permission to use the network to connect to MySQL/MariaDB (essentially connect over 127.0.0.1 rather than via hostname "localhost"):

sudo setsebool -P httpd_can_network_connect_db on
sudo service httpd restart

Next we need to edit the PHP.ini configuration file for one needed adjustment: Setting the timezone. Newer PHP often throws off errors if the timezone isn't set, which can cause issues with HelpSpot's error reporter.

Edit /etc/php.ini and set the "date.timezone" setting to any valid timezone, such as UTC. HelpSpot will use the correct timezone within the application despite this setting, but this will prevent PHP from throwing "warning" and "notice" type errors about the timezone not being set.

Timezone:

Change this from:

;date.timezone =

to:

date.timezone = UTC

(Note that it is no longer commented out with the preceding ";" character)

Memory Limits:

We also suggest setting PHP memory limits up from the stock settings. What you need depends on your use case, typically if there are larger files being sent in as attachments. We recommend 128M or 256M as a memory limit.

memory_limit = 256M

Once this is done, restart Apache for the change to take affect:

sudo service httpd restart

Lastly we'll create an Apache VirtualHost for use with HelpSpot. You can skip this and add HelpSpot into the default /var/www/html directory, but this is more useful to add some extra security.

We'll make a few assumptions:

  • The site is hosted at url http://support.example.com
  • The site files will be on the server in directory /var/www/support.example.com

Create or edit file /etc/httpd/conf.d/vhosts.conf. The following VirtualHost is recommended for HelpSpot:

<VirtualHost *:80>
    ServerName support.example.com
    DocumentRoot /var/www/support.example.com

    <Directory /var/www/support.example.com>
        Options -Indexes +FollowSymLinks +MultiViews 
        # Disallow .htaccess file usage: 
        AllowOverride None 
        Require all granted
    </Directory>

    <Directory /var/www/support.example.com/data>
        # Disallow web access to "data" directory:
        Deny from all
    </Directory>
    
    ErrorLog /var/log/httpd/support.example.com-error.log
    # Possible values include: debug, info, notice, warn, error, crit, 
    # alert, emerg. LogLevel warn
    CustomLog /var/log/httpd/support.example.com-access.log combined
</VirtualHost>

This configuration will be read automatically by Apache. Once that's saved, you can ensure your configuration is OK:

sudo service httpd configtest

If everything checks out, reload Apache to load in the new config:

sudo service httpd reload

Install MariaDB

We'll next install MariaDB, the drop-in replace for MySQL which CentOS7/RedHat7 now come with.

sudo yum install mariadb-server
sudo systemctl enable mariadb.service
sudo service mariadb start
sudo mysql_secure_installation

Once that's installed and you've run through the steps to secure the installation (remove test databases and anything but local root access), you can optionally setup MariaDB to be listen on the localhost network 127.0.0.1. (Otherwise you will only be able to connect to it with hostname "localhost"). Use this in conjunction with the SELinux setsebool above, if you are using SELinux.

Edit the /etc/my.cnf.d/server.cnf and append the following under [mysqld]:

[mysqld]
bind-address = 127.0.0.1

Then restart MariaDB:

sudo service mariadb restart

Once that's done, we can create a new database for HelpSpot. Run the following SQL after logging into the mysql command:

Log in:

# This will prompt you for the root password:
mysql -u root -p

Then use the following to create a new database:

CREATE DATABASE helpspot_db
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

This will create a database. The last step is to create a user that can connect to the HelpSpot database locally. We'll use "localhost" For the host that the user can connect from. You should create additional users with other hosts or IP addresses defined if connecting to a remote MySQL server.

Still within the MySQL command prompt, run the following two commands. Note I'm assuming you created a database named "helpspot_db" and want a user named "helpspot_user". Also use a more secure password than the example here:

CREATE USER 'helpspot_user'@'localhost' IDENTIFIED BY 'some_secure_password';
GRANT ALL PRIVILEGES on helpspot_db.* TO 'helpspot_user'@'localhost';

Once that's done, edit your HelpSpot's config.php file to use the database and password you created above.

IonCube Loader

We recommend using the IonCube loader to read HelpSpot code files. In future HelpSpot versions, we may do away with Zend Loader support do to issues in building HelpSpot with the Zend Loader.

IonCube loader can be downloaded from here. You'll likely need the Linux 64bit version. Downloading the Uploader file of the appropriate version will download the Loader files and an HTML wizard which will inform you of how to install the IonCube loader. Downloading these files and running the wizard can be done by:

  • Downloading the files to your server, using curl or wget (e.g. "wget http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.zip")
  • Unzipping the file (e.g. "unzip ioncube_loaders_lin_x86-64.zip")
  • Moving the files to your /var/www/support.example.com site and heading to the included .html file in the wizard directory from your browser.

An example vide of this process of installing IonCube loader via the wizard can be seen here.

A list of command which should work for the latest CentOS/IonCube (assuming they install php version 5.4):

curl -o ioncube_loaders_lin_x86-64.tar.gz \
     http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz

# Uncompress .tar.gz file
tar -xvf ioncube_loaders_lin_x86-64.tar.gz

# Change into the new ioncube files
cd ioncube

# Add the ioncube loader for php 5.4, assuming that is what's installed
sudo cp ioncube_loader_lin_5.4.so /usr/lib64/php/modules/ioncube_loader_lin_5.4.so

# If you are using SELinux, give this file the proper owner and SELinux contenx:
sudo chown root:root /usr/lib64/php/modules/ioncube_loader_lin_5.4.so
sudo chcon -v --user=system_u --role=object_r --type=lib_t \
     /usr/lib64/php/modules/ioncube_loader_lin_5.4.so

# Edit/create the php module to load IonCube:
sudo vi /etc/php.d/00-ioncube.ini

Make the 00-ioncube.ini file look like this:

; Enable ioncube extension module
zend_extension=/usr/lib64/php/modules/ioncube_loader_lin_5.4.so

Then restart Apache:

sudo service httpd restart

HelpSpot Files & SELinux

If you are using SELinux, and assuming your HelpSpot installation is found at /var/www/support.example.com, make sure that your HelpSpot has the proper SELinux settings. We'll also ensure the "data" can be written to, as needed by HelpSpot.

# Set file ownership for HelpSpot files
sudo chown -R apache:apache /var/www/support.example.com

# Check current SELinux settings for HelpSpot files:
cd /var/www/support.example.com
ls -Z

# Set SELinux context for Apache files:
sudo chcon -Rv --user=system_u --role=object_r --type=httpd_sys_content_t \
    /var/www/support.example.com

# Set write ability to "data" directory:
sudo chmod -R gu+rw /var/www/support.example.com/data

# Ensure SELinux allows Apache has permission to write to the data directory:
sudo chcon -Rv --type=httpd_sys_content_rw_t /var/www/support.example.com/data

Wrapping Up

Once these steps are done, you can include your HelpSpot files in the /var/www/support.example.com directory, copy the config-empty.php file to config.php, edit that config.php file as needed (database configuration + cHOST variables) and then run the installer.php file from your web browser e.g. http://support.example.com/installer.php.

If you experience errors, check for PHP errors at the configured Apache error log. In this example, that log location is /var/log/httpd/support.example.com-error.log.

You may also wish to edit the /etc/php.ini file to change PHP configuration. For example, you may wish to enable display_errors and set the error_reporting to the example "development" setting to see more errors and debug potential issues during HelpSpot installation.

If you edit the php.ini file, be sure to restart Apache after configuration changes:

sudo service httpd restart

Assuming everything else is setup, you are now ready to run HelpSpot's installer. This is usually done in the web browser, using "installer.php" (e.g. http://your-helpspot-site.com/installer.php), but you can also run the installer using HelpSpot's new "install" CLI command as well.

5. HelpSpot Server Setup: Debian/Ubuntu

We'll cover setting up an Debian/Ubuntu server for use with HelpSpot.

This will install PHP, Apache and MySQL.

Note that this guide will assume you're using Ubuntu 18.04 LTS. Steps should be similar for other recent Debian/Ubuntu versions.

Apache & PHP

We'll begin by installing Apache and PHP.

sudo apt-get install -y apache2 libapache2-mod-php php php-cli \
php-mysql php-curl php-gd php-memcached php-intl php-imap \
php-tidy php-ldap php-xml

Once that's complete, Apache will be running with PHP support, including the basic and recommended modules needed by HelpSpot to function.

Let's edit the PHP.ini configuration file for one needed adjustment: Setting the timezone. Newer PHP often throws off errors if the timezone isn't set, which can cause issues with HelpSpot's error reporter.

Edit edit php.ini in /etc/php/7.2/apache2/php.ini and set the "date.timezone" setting to any valid timezone, such as UTC. HelpSpot will use the correct timezone within the application despite this setting, but this will prevent PHP from throwing "warning" and "notice" type errors about the timezone not being set.

Timezone:

Change this from:

;date.timezone =

to:

date.timezone = UTC

(Note that it is no longer commented out with the preceding ";" character)

Memory Limits:

We also suggest setting PHP memory limits up from the stock settings. What you need depends on your use case, typically if there are larger files being sent in as attachments. We recommend 128M or 256M as a memory limit.

memory_limit = 256M

Once this is done, restart Apache for the change to take affect:

sudo service apache2 restart

Next you should create an Apache VirtualHost for the HelpSpot site. We'll make a few assumptions:

  • The site is hosted at url http://support.example.com
  • The site files will be on the server in directory /var/www/support.example.com

Here is a VirtualHost file suitable for HelpSpot

<VirtualHost *:80>
    ServerName support.example.com
    DocumentRoot /var/www/support.example.com

    <Directory /var/www/support.example.com>
        Options -Indexes +FollowSymLinks +MultiViews 
        # Disallow .htaccess file usage: 
        AllowOverride None 
        Require all granted
    </Directory>

    <Directory /var/www/support.example.com/data>
        # Disallow web access to "data" directory:
        Deny from all
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/support.example.com-error.log
    # Possible values include: debug, info, notice, warn, error, crit, 
    # alert, emerg. LogLevel warn
    CustomLog ${APACHE_LOG_DIR}/support.example.com-access.log combined
</VirtualHost>

Note that if you're using HelpSpot with an SSL certificate, you'll need to add a <VirtualHost *:443> configuration block and add the necessary SSL certificate directives.

Create the virtualhost in the /etc/apache2/sites-available directory, in any file name. I typically name files similar to the hostname, such as "support.example.com.conf".

Once the VirtualHost file is created (I'll assuming at /etc/apache2/sites-available/support.example.com.conf" for this example), you can enable it with the following commands:

sudo a2ensite support.example.com
sudo service apache2 reload

The first command creates a symlink for the support.example.com.conf file between the /etc/apache2/sites-available and /etc/apache2/sites-enabled directories. The second command tells Apache to reload it's configuration so it will see the new VirtualHost now found in the sites-enabled directory thanks to the symlink created in the first command.

MySQL

Next we'll install and create the MySQL database.

sudo apt-get install mysql-server-5.7

That will likely ask you to create a password for your root user during installation. Optionally after the installation, run the script to clean up and secure some portions of MySQL:

sudo mysql_secure_installation

Run through the options it gives you, choosing "yes" to remove remote connections and test databases.

Once that's done, we can create a new database for HelpSpot. Run the following SQL after logging into the mysql command:

Log in:

sudo mysql

Then use the following to create a new database:

CREATE DATABASE helpspot_db
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

This will create a database. The last step is to create a user that can connect to the HelpSpot database locally. We'll use "localhost" For the host that the user can connect from. You should create additional users with other hosts or IP addresses defined if connecting to a remote MySQL server.

Still within the MySQL command prompt, run the following two commands. Note I'm assuming you created a database named "helpspot_db" and want a user named "helpspot_user". Also use a more secure password than the example here:

CREATE USER 'helpspot_user'@'localhost' IDENTIFIED BY 'some_secure_password';
GRANT ALL PRIVILEGES on helpspot_db.* TO 'helpspot_user'@'localhost';

Once that's done, edit your HelpSpot's config.php file to use the database and password you created above.

IonCube Loader

HelpSpot requires the use of IonCube loader to read HelpSpot code files.

IonCube loader can be downloaded from here. You'll most likely use the Linux 64bit version, but will vary depending on the server in which HelpSpot will be hosted.

To install IonCube using their wizard, download the "Uploader" file of the appropriate version. This will download the Loader files and an HTML wizard which will inform you of how to install the IonCube loader. Downloading these files and running the wizard can be done by:

  • Downloading the files to your server, using curl or wget (e.g. "wget http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.zip")
  • Unzipping the file (e.g. "unzip ioncube_loaders_lin_x86-64.zip")
  • Moving the files to your /var/www/support.example.com site and heading to the included .html file in the wizard directory from your browser.

An example video of this process of installing IonCube loader via the wizard can be seen here.

A list of command which should work for the latest Debian/Ubuntu (assuming they install php version 7.2):

curl -o ioncube_loaders_lin_x86-64.tar.gz \
     http://downloads3.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz

# Uncompress .tar.gz file
tar -xvf ioncube_loaders_lin_x86-64.tar.gz

# Change into the new ioncube files
cd ioncube

# Add the ioncube loader for php 5.6, assuming that is what's installed
# NOTE that this file path will change depending on the PHP version installed sudo cp ioncube_loader_lin_7.2.so /usr/lib/php/20170718/ioncube_loader_lin_7.2.so # Edit/create the php module to load IonCube: sudo vim /etc/php5/mods-available/ioncube.ini

Make the 00-ioncube.ini file look like this:

; Enable IonCube
;priority=00
zend_extension=/usr/lib/php/20170718/ioncube_loader_lin_7.2.so 

Then enable that for all PHP SAPI's (CLI, Apache and/or FPM):

sudo phpenmod -s ALL ioncube

Then restart Apache:

sudo service apache2 restart

Note the phpenmod ALL command will enable ioncube for all SAPIs. You can double check this by confirming that the configuration file for IonCube exists in /etc/php/7.2/mods-available/ and is symlinked in /etc/php/7.2/cli/conf.d and /etc/php/7.2/apache/conf.d or /etc/php/7.2/fpm/conf.d.

HelpSpot Files

At this point you are ready download and transfer the HelpSpot install directory to your previously defined web directory.

sudo mv ~/helpspot_4.8.18/* /var/www/support.example.com/    

HelpSpot needs to be able to write to the "data" directory included. Let's make sure the HelpSpot files have the correct ownership, and then set the the data directory to be writable.

# Set ownership to default web user "www-data":
sudo chown -R www-data:www-data /var/www/support.example.com

# Ensure user/group "www-data" can write to the data directory:
sudo chmod -R gu+rw /var/www/support.example.com/data

Wrapping Up

Copy the /var/www/support.example.com/config-empty.php file to /var/www/support.example.com/config.php, edit that config.php file as needed (database configuration + cHOST variables) and then run the installer.php file from your web browser e.g. http://support.example.com/installer.php.

If you experience errors, check for PHP errors at the configured Apache error log. In this example, that log location is /var/log/apache2/support.example.com-error.log.

You may also wish to edit the /etc/php/72/apache2/php.ini file to change PHP configuration. For example, you may wish to enable display_errors and set the error_reporting to the example "development" setting to see more errors and debug potential issues during HelpSpot installation.

If you edit the php.ini file, be sure to restart Apache after configuration changes:

sudo service apache2 restart

Assuming everything else is setup, you are now ready to run HelpSpot's installer. This is usually done in the web browser, using "installer.php" (e.g. http://your-helpspot-site.com/installer.php), but you can also run the installer using HelpSpot's new "install" CLI command as well.

6. Creating a UTF-8 Database

MySQL

MySQL databases for HelpSpot version 4 should default to the InnoDB storage engine and to a UTF-8mb4 character set and collation.

For MySQL 5.5.3+, we can use the character set utf8mb4, which is a more complete implementation of UTF-8.

CREATE DATABASE helpspot_db2
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

Note that you should change the database name (helpspot_db) as needed for your use case. You may also need to assign a specific user to the database.

SqlServer

SqlServer uses UTF16 by default and likely needs no further instructions on using a UTF-8 friendly database when creating a new database for use with HelpSpot. Users of the Windows Installer will find the new database is created for you, and so most users will not need to worry about creating a new database.

The conversion process will be required to convert existing database data, which may not be saved in UTF-8 encoding.

7. HelpSpot 4 Server Security

Linux Apache

Make Data Directory Writable

The data directory must be writable by the web server (and PHP). This can be done by assign group ownership/permissions of the directory as appropriate for your system.

RedHat/CentOS:

sudo chgrp -R httpd /path/to/helpspot/data
sudo chmod -R g+rw /path/to/helpspot/data

Debian/Ubuntu:

sudo chgrp -R www-data /path/to/helpspot/data
sudo chmod -R g+rw /path/to/helpspot/data

Protect Data Directory

The data directory should not be served to publicly to your audience.

We've included an .htaccess file in the data directory which denies public web-based access to that directory:

File /path/to/helpspot/data/.htaccess:

Deny from all

If your Apache installation does not allow the use of .htaccess files, you can enable them in the VirtualHost configuration for HelpSpot:

<VirtualHost *:80>
    # Other directives omitted

    <Directory /path/to/helpspot>
        AllowOverride All  # this allows .htaccess file usage

        # Other directives omitted
    </Directory>
</VirtualHost>

Alternatively, you can keep disallowing .htaccess file usage and set the permissions within the VirtualHost configuration:

<VirtualHost *:80>
    # Items omitted

    <Directory /path/to/helpspot>
        AllowOverride None

        # Other items omitted
    </Directory>

    <Directory /path/to/helpspot/data>
        Deny from all
    </Directory>
</VirtualHost>

Windows

Make Data directory writable

This is configured for you if you install HelpSpot using the Windows Installer.

Apache

This is configured for you if you install HelpSpot using the Windows Installer.

Apache installed on Windows can accomplish the same. Near the bottom of the C:\Program Files (x32)\helpspot\apache\conf\httpd.conf file, you can append a Directory configuration to the bottom:

<Directory "C:\Program Files (x32)\helpspot\helpspot\data">
    Deny from all
</Directory>

IIS

This is configured for you if you install HelpSpot using the Windows Installer.

The web.config XML file found in C:\Program Files (x32)\helpspot\helpspot\web.config file requires the addition of some security configuration.

Add the following as appropriate:

<configuration>
   <system.webServer>
       <security>
          <requestFiltering>
               <hiddenSegments>
                   <add segment="data" />
               </hiddenSegments>
           </requestFiltering>
       </security>
   </system.webServer>
</configuration>

File Permissions

IIS needs to be able to write to HelpSpot's "data" directory. This usually means user IUSR needs permission to modify/write this directory. The Windows installer will handle this for you. However, users who install HelpSpot in non-default locations will need to set security settings on the "data" directory so IUSR can modify/write to that directory.

Nginx

HelpSpot can also work with the Nginx web server.

You can restrict access to the data directory in Nginx with the following "location" block:

server {
    # Other directives omitted

    location /data {
        deny all;
    }
}

MySQL SSL

HelpSpot version 4.0.17+ can connect to MySQL over an SSL connection.

To use an SSL configuration, add the following two items to HelpSpot's config.php file:

define('cMYSQL_CLIENT_SSL', true);
define('cMYSQL_INI_PATH', '/etc/mysql/my.cnf');

Note that the path to the my.cnf file may be different on your system.

Within the my.cnf file referenced, we need to tell MySQL that clients should connect using the SSL certificate. To do so, append the relevant lines of the following under the [client] section of the MySQL my.cnf file. The certificate file paths and names will be different for you:

ssl-ca=/path/to/your/ca-cert.pem
ssl-cert=/path/to/your/client-cert.pem
ssl-key=/path/to/your/client-key.pem
ssl-verify-server-cert=1

Note: The MySQL configuration for supporting SSL connections is out of scope of HelpSpot, but generally involves:

  1. Creating an SSL certificate (key, certificate and possibly certificate authority files)
  2. Setting the my.cnf file to use the certificate files under the [mysqld] heading

8. Installing A New License File

Your license file needs to be updated when you change the number of agent licenses on your account or renew your subscription. For HelpSpot Cloud customers, this process happens automatically. Self-hosted customers will receive an email with a new license file and will also be able to download the new license by logging into https://store.helpspot.com. After downloading the license file the license can be updated through the HelpSpot admin screen.

  1. Login to your HelpSpot instance.
  2. Select Admin from the top menu.
  3. Select Choose File in the Upload a New License box.
  4. Upload select your downloaded license file from the file picker.

The license will be updated to reflect the latest subscription information.

9. Database Based Full Text Search

AS OF HELPSPOT 5.0.X SPHINX SEARCH HAS BEEN COMPLETELY REMOVED

As of version 4.6.7 HelpSpot allows the use of either built in database full-text search of the use of the external Sphinx search indexer. New installations will default to the database search search option. To switch an existing sphinx based installation to database search you simply need to add the define('SEARCH_ENGINE', 'database'); variable to your config.php file.

Opting For Sphinx Search:
Most installations will be well served by the default, database Full Text search option. However, if there is a need for advanced full text search parameters or a need to reduce the database load query load, Sphinx search can be setup. On linux bases installs, the sphinx setup requires additional steps that are documented here: for Ubuntu/Debian and RedHat/CentOS. New windows installations will default to database search but can be converted to sphinx search by changing the config.php
variable for the search engine to define('SEARCH_ENGINE', 'sphinx');

10. HelpSpot Commands

HelpSpot 4.0.0 now comes with a command-line tool, which has some tools to help you automate a few things. The functionality of this is limited for now, but will likely expand with added features.

General

Linux:

The hs command installed with HelpSpot is the command line utility. On Linux servers, you can run it using PHP:

# List the available commands and options:
$ php hs

Windows:

On Windows, you need to run the hs command using the PHP that comes with HelpSpot using Cmd or PowerShell, and let it know which configuration file to use:

> C:\'Program Files (x86)'\helpspot\php\php.exe -c C:\'Program Files (x86)'\helpspot\php\php.ini C:\'Program Files (x86)'\helpspot\helpspot\hs

It might be easier to first "change directory" into the HelpSpot directory so these file paths are shorter:

> cd C:\'Program Files (x86)'\helpspot\helpspot
> ..\php\php.exe -c ..\php\php.ini .\hs

For both Linux and Windows, running hs without any parameters will simply list out the available commands.

Here are the commands available for HelpSpot:

  • install - A command to install/configure HelpSpot
  • update - A command to run updates for HelpSpot from 4.0.0+
  • attachments:tofile - A command to convert attachments from the database to the filesystem
  • convert:base - A command to start the update HelpSpot from version 3 to 4
  • convert:request - A command to complete the update from HelpSpot version 3 to 4
  • recover:requests - If the conversion of requests fail silently and there are missing requests, this command can be used to recover them
  • db:exists - Check if a HelpSpot database exists
  • search:config - Generate a Sphinx Search configuration file
  • request:delete - Delete a single request by ID
  • request:delete-spam - Delete all requests marked as spam ithout training the spam filter.
  • report:logs - Export a CSV file of your Helpspot request event logs to your data/documents/ directory.
  • spam:clean - optimize the Bayesian filter database to improve spam filtering performance.

Install

HelpSpot can be installed via the command line instead of using the web interface. This might be useful for automating the install of HelpSpot.

The simplest way to use this command is to download the HelpSpot files, and then run the "install" command. This will ask you for the information it needs to complete the installation.

php hs install

This asks you all the information needed to install HelpSpot. You can also pass the command all the needed information directly, allowing the install to be automated. The following are the flags/options you can set:

Note that you can run `php hs install -h`, which will show you the available flags/options to use for the install command.

  • --agree=yes - "Yes" to say you agree to the terms and conditions
  • --name='Your Full Name' - The administrator user's full name (first and last)
  • --admin-email=admin@email.com - The administrator user's email address
  • --password=your_password - The administrator user's passwor
  • --company='Your Company' - The company as displayed publicly
  • --timezone='America/New_York' - The timezone to use within HelpSpot
  • --customer-id=123456 - Your customer ID
  • --license-file=/path/to/license-file.txt - The path to the license file, which should be saved to the server before running the server
  • --notification-email=notification@email.com - The email used for sending notifications
  • --ask-smtp=yes - Add in your outgoing email settings, using the following "smtp" options. Use "no" to configure this later, the smtp configuration is optional
  • --smtp-host=somehostname - (Conditional on "--ask-smtp") The outgoing email server
  • --smtp-port=1234 - (Conditional on "--ask-smtp") The outgoing email port
  • --smtp-user=some@user.com - (Conditional on "--ask-smtp") The outgoing email user name
  • --smtp-password=some_password - (Conditional on "--ask-smtp") The outgoing email password
  • --smtp-protocol=none - (Conditional on "--ask-smtp") The connection protocol. One of "none" (no security), "ssl" or "tls"

Update

You can use this tool to update HelpSpot as well. This will be useful when versions greater than 4.0.0 is released. For example, you can run this command when updating from version 4.0.0 to 4.0.1.

Once you update the HelpSpot files on your server, you can run the update command:

php hs update

This will gather the old version and new version of HelpSpot and run any scripted or database updates needed. This will not install the latest HelpSpot file - that step must still be done outside of this command line tool.

  • --language=english.us - Defaults to the "english.us" language

This command is much simpler than the install command, as it will determine the needed information from available system information.

Attachments

This command will allow you to save your file attachments from the database (the default location prior to HelpSpot version 4) to your server file system. This command can only be used after you convert your database from version 3 to version 4, due to differences in the database structure.

This command will delete file attachment data from your database. We highly suggest backing up your database before running this command.

To begin saving database attachments to the filesystem, run the following command.

php hs attachments:tofile

This will ask you the file path to save your attachments. The default value is the data/documents directory, which HelpSpot 4 comes with for this purpose.

Note that you can run `php hs attachments:tofile -h`, which will show you the available flags/options to use for the install command.

  • --path=data/documents - The path (relative to the "hs" command location or absolute) where the files should be saved to. This location must be writable by the user running the command.

This command may take a considerable amount of time, depending on the size of your database. The command can safely be run multiple times, including if it stops on failure or timeout.

Convert

The convert commands are used specifically to update HelpSpot from Version 3 to Version 4. HelpSpot requires a conversion of the current data from its current character set to UTF-8 (in order to support multiple language alphabets and characters properly). This process can take a relatively long time and should be run via the command-line, which has no time limit like an update from within the browser may have.

Before updating from Version 3 to Version 4, you must create a new, empty database that is setup for UTF-8 character sets. The new database credentials should be added into the config.php file. However, keep a note of the old credentials, as the conversion process requires access to both databases.

There are two commands for conversion:

  • convert:base - Creates the database tables in the new database, and converts the "base" (not Request-related) data into the new database from the old database.
  • convert:requests - Converts Requests and all related data from the old database to the new database. This can go back in time a specific amount of days, or do all requests. This command can be run more than once without fear of duplicating data.

Because the conversion requires two databases, it's useful to set the terms used:

  • source database - the old database from which data will be converted and copied into the new, UTF8-Capable database
  • destination database - the new, UTF8-Capable database which data will be converted and copied into.

The destination database credentials must be set in the config.php file, while the source database credentials will be asked for in while using the convert commands.

convert:base

The convert:base command should be run first. This command will do two things:

  1. Create the needed database schema for HelpSpot version 4 in the new database
  2. Copy all database data, except for that related to Requests, into the new database

Running this command will ask you for the necessary input.

php hs convert:base

You can also provide it the needed information head of time:

  • --db-type=mysql - The source database type you are using. Note that this is the old database, not the new UTF-8 capable database. The default is "mysql". Valid types are: mysql, mssql, or postgres_helpspot
  • --db-host=localhost - The hostname to use to access the source database. The default is "localhost".
  • --db-user=some_username - The username used to access the source database
  • --db-pass=some_password - The password used to access the source database
  • --db-name=some_db_name - The name of the source database
  • --from-encoding=iso-8859-1 - Optional parameter, the character encoding used to convert data from. Character set encoders need to know what character set they are encoding from in order to properly encode to other character sets such as UTF-8. The default for HelpSpot prior to version 4 was "iso-8859-1", which is also commonly referred to as "latin1"
    • This script will guess the character set if it's not explicitly set via the --from-encoding parameter. It gets the character set from the cHD_CHARSET variable in the HS_Settings table in the source database.
  • --schema-only=yes - Set the database schema only, don't copy and data
  • --data-only=yes - Copy data only, assuming the schema is already in place (via --schema-only=yes complete previously)

This script takes about 10 minutes to run on a 2GB database. See the "Speed Tips" section within the Overview chapter for more information.

Custom Database Schema

Some HelpSpot customers add new tables or adjust the schema of the standard HelpSpot database. For those customers, the convert:base command needs to be handled in a way that allows you to add custom tables, columns or schema adjustments before database data is copied to the new database.

To accomplish this, the convert:base command can be run in two parts via the --schema-only and --data-only options. The workflow will look like this:

  1. Run convert:base --schema-only, which will update the new database with the new schema, but won't copy and data
  2. Add any new tables, columns, or schema adjustments as needed
  3. Run convert:base --data-only, which will copy data from the old database to the new database. This should copy custom columns and handle data from adjusted existing columns. However, it will not copy new tables that are not part of HelpSpot standard database installation. Copying of any additional custom tables created will need to be done by the system administrator.

convert:requests

The convert:requests command is used to convert Requests and all related data. Requests have a lot of related data, so each request is converted and copied one by one from the source database to the destination database.

php hs convert:requests

This command will save requests starting with the newest first. This let's you quickly get up and running by converting the latest requests (for example, the last 90 days worth of requests). Then, if HelpSpot support is critical enough, your staff can continue working within HelpSpot while the command is run again to complete the remaining requests in the system.

Since many systems have been up and running for years, some systems will have hundreds of thousands of database rows of requests and request history. The use case above (copying the last 90 days of requests and then the remaining in the background while the system is in active use) is for such cases.

On a database of about 2GB of size with about 30,000 requests and 285,000 items of request history, the conversion process took about 20-30 minutes.

The options for this command are similar to the convert:base:

  • --db-type=mysql - The source database type you are using. Note that this is the old database, not the new UTF-8 capable database. The default is "mysql". Valid types are: mysql, mssql, or postgres_helpspot
  • --db-host=localhost - The hostname to use to access the source database. The default is "localhost".
  • --db-user=some_username - The username used to access the source database
  • --db-pass=some_password - The password used to access the source database
  • --db-name=some_db_name - The name of the source database
  • --from-encoding=iso-8859-1 - Optional parameter, the character encoding used to convert data from. Character set encoders need to know what character set they are encoding from in order to properly encode to other character sets such as UTF-8. The default for HelpSpot prior to version 4 was "iso-8859-1", which is also commonly referred to as "latin1"
    • This script will guess the character set if it's not explicitly set via the --from-encoding parameter. It gets the character set from the cHD_CHARSET variable in the HS_Settings table in the source database.
  • --days-back=90 - The number of days of requests to go back in time. The default is 90 days. Use "all" to copy all requests. Note that HelpSpot will not be usable until this command completes running at least once, upon which it updates HelpSpot's internal setting to the correct version, making HelpSpot able to reach the admin login page.

This command tracks requests that have been successfully copied to the new database. This means you can run the command multiple times safely. Note that the --days-back option is relative to "now", the time when you run the command. If you run the command "now", going back 90 days, it will copy the last 90 days of requests. Running the identical request immediately a second time will result in no requests being copied, as the last 90 days worth of requests have already been copied. To go back further than 90 days, increase the number of days set, or use "all": --days-back=all

php hs convert:requests --days-back=all

Recover Requests

The recover:requests command is only used on a v3 to v4 upgrade when the database is being converted. If the conversion of requests fail silently and there are missing requests, this command can be used to recover them. This command is limited to 2100 requests on SQLServer because of SQLServer's bind limit.

Database Exists

The db:exist command determines if a populated HelpSpot database already exists based on the credentials used in the config.php file. This is a utility function, used by the Windows installer primarily, but available to all customers. This command may be useful to those automating an install or update of HelpSpot.

php hs db:exists

Search Configuration

The search:config command will generate a configuration file for SphinxSearch to use. It takes the database credentials and information such as custom fields from the database (using the database credentials set in config.php) and generates the configuration file. This configuration file contains the needed information to index Customer data, Requests, Knowledge Books and Forums into the Sphinx Search engine index.

This command will save the sphinx.conf file to the server-writable "data" directory found within the HelpSpot installation.

php hs search:config

There is a single option for this command that allows you to specify the location where the sphinx index files reside.

  • --data-path — The path where the sphinx index files will be generated.

For details on how to use this generated sphinx.conf file, see our extended documentation on installing Sphinx Search on Debian/Ubuntu servers or installing Sphinx Search on RedHat/CentOS servers.

Request: Delete

The request:delete command deletes a request by ID. You pass it the --id= option with your request ID.

php hs request:delete --id=12400

Request: Delete Spam

The request:delete-spam command deletes all requests in HelpSpot's spam queue. It will not train the spam filter. By default it asks for confirmation, you can bypass this with the --force flag.

php hs request:delete-spam

Report: Logs

The report:logs command will export a CSV file of your helpspot request event logs to your data/documents/ directory.

 

php hs report:logs

Spam: Clean

The spam:clean command optimize the Bayesian filter database to improve spam filtering performance. Running this every 7 days is recommended for larger installations.

 

php hs spam:clean

hs config:convert

Converts the config.php file to a .env file. The default action will overwrite any existing .env. --dump Displays the result of processing the config.php file instead of overwriting the .env.

php hs config:convert

11. Tasks.php Explained

AS OF HELPSPOT 5.0 TASKS.PHP IS NO LONGER USED

See documentation here on the new cron jobs and and queuing system

What does tasks.php do?

The tasks.php script has 3 main functions in HelpSpot:

  1. Check email accounts and convert emails into requests
  2. Send out reminders
  3. Delete requests marked as trash

Running tasks.php on a regular basis is critical to using HelpSpot. Major functionality will not work properly without this script running.

Where is it located?

The tasks.php file is in the root HelpSpot folder. The same one which contains admin.php and index.php.

How often should tasks.php run?

Every 1-5 minutes, however every 1-2 is recommended.

How do I run the script?

On Linux/Unix the script should be run via Cron. On Windows Scheduled Tasks should be used. Windows users note that if you've installed using our Windows Installer a scheduled task has already been setup for you.

Configuration for Windows:
If you've used the HelpSpot Windows Installer this has already been done for you.

Configuration for Linux/Unix/OSX:
tasks.php can be called directly through PHP on the command line or via an HTTP call. Several examples are below, but be sure to replace the generic paths with the ones for your installation:

Direct command line method for every minute (preferred):

* * * * * /usr/bin/php /path/to/helpspot/tasks.php

Using HTTP with curl:

* * * * * curl http://www.domain.com/tasks.php

Tips and Tricks

Direct access
You can manually run the tasks.php file in your browser to force it to pull in email (and it's other actions). This is often useful for testing purposes. Just visit the script in your browser at http://www.domain.com/tasks.php. Note that it is normal for the output to be a blank white screen.

Tasks.php debugging
If you're having problems with an email account it can be useful to turn on tasks.php debugging in Admin->Settings->Email Integration. Once this is on if you visit the tasks.php file in your browser (as described above) you'll see debugging output. It's often useful to do "view source" in your browser to see the output in a nicer format.

Additional security
If you want to prevent people from outside being able to access tasks.php via HTTP you can set the IP's that are allowed to call it in Admin->Settings->System.

Check just one mailbox
Normally each time tasks.php is run it checks all mailboxes you've configured in Admin->Mailboxes. If you'd like to run mailboxes on their own checking schedules though it's possible to have HelpSpot only check one mailbox when tasks.php is run. To do so you need to pass in the ID of the mailbox which you can find in Admin->Mailboxes.

If you were using the HTTP method you would change the URL to:

http://www.domain.com/tasks.php?id=4

If you were using the command line method you would do this:

* * * * * /usr/bin/php /path/to/helpspot/tasks.php --id=4

 

New in HelpSpot version 4: Check multiple mailboxes

Customers with many Email Mailboxes (or a few which usually contain large attachments) may want to divide mailboxes out to separate scheduled tasks. This allows you to stagger when they are called, or to separate email mailbox checking to multiple PHP calls. This reduces the change of hitting an error due to meeting memory limits while checking for new email.

For example, if you have 6 Email Mailboxes (of id 1, 2, 3, 4, 5, and 6) configured and want to check 3 at a time, you can create two tasks. 

If you were using the HTTP method you would make 2 separate calls like so:

http://www.domain.com/tasks.php?id[]=1&id[]=2&id[]=3
http://www.domain.com/tasks.php?id[]=4&id[]=5&id[]=6

If you were using the command line method you make 2 separate crontasks like so:

* * * * * /usr/bin/php /path/to/helpspot/tasks.php --id=1,2,3
* * * * * /usr/bin/php /path/to/helpspot/tasks.php --id=4,5,6

 

12. Version 4 Language File Changes

The following outlines changes (additions, modifications and deletions) from the HelpSpot language files between version 3 and 4.

Note that some values are truncated for brevity. Please check the files on your HelpSpot installation to find their current values. For example: define('lg_ajax_valid_wysiwyg_values’,’…’);

helpspot/lang/english-us/lg.charset.php

This files is significantly shorter, the only content is:

// SECURITY: Don't allow direct calls to this file outside the context of HelpSpot
if (!defined('cBASEPATH')) die();

//Set the language/region time is formatted in. More details here: http://www.php.net/setlocale
setlocale(LC_ALL, 'en-us','english');

helpspot/lang/english-us/lg.general.php

Removed:

define('lg_mobilehs','Mobile Login');
define('lg_share','Share');
define('lg_placeholderspopup_mobilereqpage','Mobile Request URL');

Added/Modified:

define('lg_documentation','Help');
define('lg_forums','Join us on the forums!');
define('lg_academy','Training');
define('lg_social','Social');
define('lg_lookup_mobile','HelpSpot Mobile App');
define('lg_lookup_filter_lastupdateby','Latest Update By');
define('lg_noresults_with_fulltext','Note: Request history is not searched from the sidebar when Sphinx Search is not enabled.');
define('lg_noresults_alt11','These pretzels are making me thirsty.');
define('lg_noresults_alt12','You\'re a lean, mean, inbox clearing machine.');
define('lg_noresults_alt16','https://www.youtube.com/embed/zpN00-UTrY0');
define('lg_noresults_alt_lunch','Lunch is for wimps.');
define('lg_noresults_alt_latenight',"I'll sleep when I'm dead.");
define('lg_search_history','Search History');

helpspot/lang/english-us/lg.pg.admin.rules.php

Added/Modified:

define('lg_admin_rules_note','Rules apply only to new request emails; any follow-ups to existing requests will not be impacted.');

helpspot/lang/english-us/lg.pg.admin.settings.php

Removed:

define('lg_admin_settings_spellchecking','Spellchecking');
define('lg_admin_settings_spellchecking_note','<strong>Note:</strong> Using an in browser spellchecker in many cases will be most effective and provide the best experience. FireFox and Safari have spellcheckers built in. IE users can download free spellcheckers here: <a href="http://www.ie7pro.com/" target="_blank">IE7</a> or <a href="http://www.iespell.com/" target="_blank">IE6</a>');
define('lg_admin_settings_sppath','Spellchecking - Path to Aspell');
define('lg_admin_settings_sppathnote','The full path to the Aspell binary on your server. Leave blank to disable spellchecking.');
define('lg_admin_settings_spchar','Spellchecking - Character Encoding');
define('lg_admin_settings_spcharnote','In the format of: iso8859-1');
define('lg_admin_settings_splang','Spellchecking - Language Dictionary');
define('lg_admin_settings_spgecko','Allow FireFox Native Spellchecking in WYSIWYG Editor');
define('lg_admin_settings_spgeckoex','Enabling this may interfere with staff using the Microsoft Internet Explorer browser');

Added/Modified:

define('lg_admin_settings_captcharedesc','reCAPTCHA is a free service of Google. It is an image/audio captcha which is more secure than the standard text captcha. To use it you need to <a href="https://www.google.com/recaptcha" target="_blank">sign up for a free API KEY</a>.');
define('lg_admin_settings_captcharepublic','Site Key');
define('lg_admin_settings_captchareprivate','Secret Key');
define('lg_admin_settings_reply_as_public','Replies to notification emails are public');
define('lg_admin_settings_reply_as_publicex','When staff reply to an email notification about a request the reply will be forwarded through HelpSpot as a public note to the customer.');

helpspot/lang/english-us/lg.pg.admin.users.php

Removed:

define('lg_admin_users_mobsig','Mobile Version');

Added/Modified:

define('lg_admin_users_sidebarsearch','Search History by Default in Sidebar');
define('lg_admin_users_sidebarsearchtitle','Sidebar Search');

helpspot/lang/english-us/lg.pg.ajax_gateway.php

Added/Modified:

define('lg_ajax_valid_wysiwyg_values’,’…’);
define('lg_ajax_valid_wysiwyg_values’,’…’);
define('lg_ajax_valid_wysiwyg_values’,’…’);

 

helpspot/lang/english-us/lg.pg.conditional.ui.php

Added/Modified:

define('lg_conditional_ftwarning','Full text searches in a filter should be used with caution; they have the potential to be database intensive. If you are using Sphinx Search (now standard with HelpSpot), this is less likely to be an issue.');
define('lg_conditional_at_webhook','POST a webhook to this URL:');
define('lg_conditional_tr_webhook','POST a webhook to this URL:');

 

helpspot/lang/english-us/lg.pg.installer.php

Removed:

define('lg_inst_cat_def','Default Category');
define('lg_inst_cat_reptags','Computer,Printer,Software,User Account,Access Request,Password'); //leave comma's

Added/Modified:

define('lg_inst_must_agree','You must accept the license terms to continue');
define('lg_inst_checkphp','PHP version 5.4 or higher');
define('lg_inst_checknotphp','HelpSpot requires PHP version 5.4.0 or higher to run');
define('lg_inst_permwarning','Your HelpSpot source files (some or all) have permissions which make them w
ritable by the web server (777). HelpSpot does not write to its source files in anyway. Please change your file permissions to be less open.');
define('lg_inst_datadir', 'Data Directory Permissions');
define('lg_inst_datadirnowrite', 'The "data" directory or subdirectories are not writable');
define('lg_inst_licensefile_cli','Path To Your License File');
// Default Categories
define('lg_inst_cat_number_cats', 6); // Number of default categories to install
// Default setup for internal facing support
define('lg_inst_cat_def','Software');
define('lg_inst_cat_reptags','Operating System, Mac, Windows, Linux, MS Office, Browser'); //leave commas
define('lg_inst_cat2_def','Hardware');
define('lg_inst_cat2_reptags','Desktop, Laptop, Monitor, Peripheral, Projector, TV, Phone'); //leave commas
define('lg_inst_cat3_def','Server');
define('lg_inst_cat3_reptags','Offline, Performance, Linux, Windows, RAM, Storage, Networking'); //leave commas
define('lg_inst_cat4_def','Human Resources');
define('lg_inst_cat4_reptags','New Hire, Benefits, Policy, Time Off'); //leave commas
define('lg_inst_cat5_def','Maintenance');
define('lg_inst_cat5_reptags','Grounds, Buildings, Electric, Plumbing, Furniture'); //leave commas
define('lg_inst_cat6_def','Other');
define('lg_inst_cat6_reptags','Wrong Email, Notification'); //leave commas
// Default setup for external facing support
define('lg_inst_cat_def_external','Account Question');
define('lg_inst_cat_reptags_external','Status, Renewal, Rewards, Cancel'); //leave commas
define('lg_inst_cat2_def_external','Technical Issue');
define('lg_inst_cat2_reptags_external','Installation, On-boarding, Browser, Feature, Bug'); //leave commas
define('lg_inst_cat3_def_external','Development');
define('lg_inst_cat3_reptags_external','Software Bug, Feature Request'); //leave commas
define('lg_inst_cat4_def_external','Sales');
define('lg_inst_cat4_reptags_external','Pricing, Demo, Discount, Upgrade, Downgrade, Pre-Sales'); //leave commas
define('lg_inst_cat5_def_external','How To');
define('lg_inst_cat5_reptags_external','User Management, Features, Configuration, Optimization'); //leave commas
define('lg_inst_cat6_def_external','Other');
define('lg_inst_cat6_reptags_external','Wrong Email, Notification');
define('lg_inst_status2','Escalated');
define('lg_inst_status3','Waiting for Reply');
define('lg_inst_status5','Customer Unreachable');
define('lg_inst_settings_smtpprotocol','SMTP Protocol (none, ssl, tls)');
define('lg_inst_et_external', '...');
define('lg_inst_et_portal_reqcreated_html','...');
define('lg_inst_et_external_html','...');
define('lg_inst_et_staff_html','...');
define('lg_inst_et_ccstaff_html','...');
define('lg_inst_et_public_html','...');
define('lg_inst_et_reminder_html','...');

 

helpspot/lang/english-us/lg.pg.mobile.php

File Deleted

 

helpspot/lang/english-us/lg.pg.reports.php

Added/Modified:

define('lg_reports_grouping_customerid','Customer ID');
define('lg_reports_grouping_customer_email','Customer Email');

 

helpspot/lang/english-us/lg.pg.request.php

Removed:

define('lg_request_er_resumeedit','Please resume editing in the spellchecker before submitting');

Added/Modified:

define('lg_request_timehrmin','hh:mm:ss');
define('lg_request_create_close','Create and Close');
define('lg_request_sidebar','Customer Search');

helpspot/lang/english-us/lg.pg.search.php

Added/Modified:

// Added for SphinxSearch
define('lg_search_sphinx_tip1','Use * as a wildcard: print*');
define('lg_search_sphinx_tip2','Use - or ! for must not contain: -printer, -password, !printer, !password');
define('lg_search_sphinx_tip3','Use = for must exact form: lost all =passwords (ensures passwords is plural)');
define('lg_search_sphinx_tip4','Use @ to search specific fields: @sEmail ian@userscape.com, @(sEmail,sTitle) *userscape');
define('lg_search_sphinx_tip5','Valid fields: sFirstName, sLastName, fOpenedVia, sEmail, sPhone, sUserId (for Customer ID), tNote, Custom# (e.g. Custom5)');
define('lg_search_sphinx_tip6','More search modifiers for <a href="http://sphinxsearch.com/docs/current.html#extended-syntax" target="_blank">SphinxSearch are explained here</a>.');

 

helpspot/lang/english-us/lg.portal.php

Added/Modified:

define('lg_portal_er_validrecaptcha','Please check off that you are not a robot');

 

13. HelpSpot 4.8.0 Language File Changes

lg.general.php

//additions
define('lg_lookup_filter_thermostat_score','Thermostat NPS Score');
define('lg_admin_customer_tools','Customer Tools');

lg.pg.admin.integrations.php

//additions
define('lg_admin_thermostat_header','Send NPS surveys to your customers with ');
define('lg_admin_thermostat_connect','Save Thermostat API Token');
define('lg_admin_thermostat_learn_about','Learn About Thermostat');
define('lg_admin_thermostat_get_token', 'Get an API Token');
define('lg_admin_thermostat_label_api_token', 'Thermostat API Token');
define('lg_admin_thermostat_token_value', 'placeholder="<token hidden> Enter a new (or empty) token to update (or remove) the Thermostat API token."');

lg.pg.admin.settings.php

//additions
define('lg_admin_settings_terms_enable','Ask customer to accept privacy policy and terms');
define('lg_admin_settings_portalterms','URL of terms of service');
define('lg_admin_settings_portalprivacy','URL of privacy policy');
define('lg_admin_settings_portalterms_info','If you enter a URL, then the users must accept before submitting a request');

lg.pg.admin.tools.customer.php (new file)

<?php

// SECURITY: Don't allow direct calls to this file outside the context of HelpSpot
if (!defined('cBASEPATH')) die();

/* EDITING NOTES
1. Some strings contain %s symbols, these must be maintained
2. Any single quotes must be preceded by a slash like this:  \'  ex: there\'s
3. If you modify this file, be sure to back it up in case you overwrite it during an upgrade by accident
*/

define('lg_admin_tools_customer_title','Customer Tools');
define('lg_admin_tools_customer_manage_data','Manage Customer Data');
define('lg_admin_tools_customer_export_data','Export Customer Data');
define('lg_admin_tools_customer_export_email','Export by Email');
define('lg_admin_tools_customer_email','Email');
define('lg_admin_tools_customer_email_address','Email Address');
define('lg_admin_tools_customer_export','Export');
define('lg_admin_tools_customer_delete_data','Delete Customer Data');
define('lg_admin_tools_customer_delete_request','Delete a request');
define('lg_admin_tools_customer_delete_request_note','Delete a request note');
define('lg_admin_tools_customer_delete_request_note_id','Note ID');
define('lg_admin_tools_customer_delete_request_note_info','This will permanently delete a single request history item along with any associated attachments.');
define('lg_admin_tools_customer_delete','Delete');
define('lg_admin_tools_customer_request_id','Request ID');
define('lg_admin_tools_customer_request_id_note','This will permanently delete a single request');
define('lg_admin_tools_customer_delete_by_email','Delete by Email');
define('lg_admin_tools_customer_delete_by_email_note','This will permanently delete anything in the database related to an email address.');
define('lg_admin_tools_customer_delete_by_id','Delete by Customer ID');
define('lg_admin_tools_customer_delete_by_id_note','This will permanently delete anything in the database related to a customer ID.');
define('lg_admin_tools_customer_sure','Are you sure you want to delete this?');
define('lg_admin_tools_customer_agree','You must type "I AGREE" to confirm.');
define('lg_admin_tools_customer_mutli_found','We found %s requests for %s. Are you sure you want to delete these?');
define('lg_admin_tools_customer_one_found','Are you sure you want to delete this?');
define('lg_admin_tools_customer_warning','<b>WARNING:</b> This operation is immediate and will <b>permanently delete</b>. Type "I AGREE" below to delete.');
define('lg_admin_tools_customer_confirm','Confirm');
define('lg_admin_tools_customer_finished','The request(s) have been deleted.');
?>

lg.pg.admin.tools.portals.php

//additions
define('lg_admin_portals_terms_enable','Ask customer to accept privacy policy and terms');
define('lg_admin_portals_portalterms','URL of terms of service');
define('lg_admin_portals_portalprivacy','URL of privacy policy');
define('lg_admin_portals_portalterms_info','If you enter a URL, then the users must accept before submitting a request');

lg.pg.admin.tools.templates.php

//additions
define('lg_admin_portaltemplates_temp_terms','HTML Elements for agreeing to the terms and privacy policy.');

lg.pg.conditional.ui.php

//additions
define('lg_conditional_at_thermostat_send','Send a Thermostat Survey');
define('lg_conditional_at_thermostat_add_email','Add Email to Survey Campaign');
define('lg_conditional_at_thermostat_score', 'Thermostat NPS Score');
define('lg_conditional_at_thermostat_promoter', 'promoter');
define('lg_conditional_at_thermostat_passive', 'passive');
define('lg_conditional_at_thermostat_detractor', 'detractor');
define('lg_conditional_at_ogintegrations','Integrations');

lg.pg.filter.requests.php

//additions
define('lg_filter_requests_ointegrations','Integrations');

lg.portal.php

//additions
define('lg_portal_agree_terms_privacy', 'I agree to the <a href="%s" target="_blank">Terms of Service</a> and <a href="%s" target="_blank">Privacy Policy</a>');
define('lg_portal_agree_terms', 'I agree to the <a href="%s" target="_blank">Terms of Service</a>');
define('lg_portal_agree_privacy', 'I agree to the <a href="%s" target="_blank">Privacy Policy</a>');
define('lg_portal_req_terms', 'You must agree to the terms');

14. HelpSpot 4 Portal Template Changes

Portal Template Changes

HelpSpot 4 contains only very minor template changes from Version 3.

As of HelpSpot 4.7.2+

request.tpl.php

These two code blocks can be included to allow CC and Subject line fields to appear.

To update your request.tpl.php file, add these lines below the sEmail field:

<?php if ($this->hd_allowCc): ?>
<p><label for="sCC" class="datalabel"><?php echo lg_portal_req_cc_email ?></label><br />
<?php echo $this->helper->showError('sCC','<br />') ?>
<input type="text" name="sCC" size="40" maxlength="250" value="<?php echo $this->request_sCC ?>" />
</p>
<?php endif; ?>

To update your request.tpl.php file to add the Subject Line field add these lines below this div.

Find:

<div class="forumoption"><?php echo lg_portal_req_detailsheader ?></div>

Below add

<?php if ($this->hd_allowSubject): ?>
<p><label for="sCC" class="datalabel"><?php echo lg_portal_req_subject ?></label><br />
<?php echo $this->helper->showError('sTitle','<br />') ?>
<input type="text" name="sTitle" size="40" maxlength="250" value="<?php echo $this->request_sTitle ?>" />
</p>
<?php endif; ?>

js.tpl.php

Find this line:

var password_confirm = $F('new_password_confirm');

Add this below:

var _token = $F('_token');

Find this line:

 parameters: {password: password_new},

Replace that line with this:

parameters: {password: password_new, _token: _token},

loginbar.tpl.php

Find this line:

<form onsubmit="return false;">

Below add:

<input type="hidden" name="_token" value="<?php echo $_SESSION['token']; ?>" id="_token">

As of HelpSpot 4.6+

js.tpl.php

Javascript is no longer loaded from a versioned directory.

To update your js.tpl.php file, find the following:

document.write('<script type="text/javascript" src="<?php echo $this->cf_primaryurl ?>/static_<?php echo $this->cf_version ?>/js/hs-js-combined-portal.php"></script>');

and update to

document.write('<script type="text/javascript" src="<?php echo $this->cf_primaryurl.elixir('js/helpspot.portal.js') ?>"></script>');

css.tpl.php

CSS is no longer loaded from a versioned directory.

To update your css.tpl.php file, find the following:

@import "<?php echo $this->cf_primaryurl ?>/static_<?php echo $this->cf_version ?>/js/jscal2/css/jscal2.css";

And update it to the following:

@import "<?php echo $this->cf_primaryurl ?>/static/js/jscal2/css/jscal2.css";

css.grey.tpl.php

CSS is no longer loaded from a versioned directory.

To update your  css.grey.tpl.php file, find the following:

@import "<?php echo $this->cf_primaryurl ?>/static_<?php echo $this->cf_version ?>/js/jscal2/css/jscal2.css";

And update it to the following:

@import "<?php echo $this->cf_primaryurl ?>/static/js/jscal2/css/jscal2.css";

css.blue.tpl.php

CSS is no longer loaded from a versioned directory.

To update your  css.blue.tpl.php file, find the following:

@import "<?php echo $this->cf_primaryurl ?>/static_<?php echo $this->cf_version ?>/js/jscal2/css/jscal2.css";

And update it to the following:

@import "<?php echo $this->cf_primaryurl ?>/static/js/jscal2/css/jscal2.css";

As of HelpSpot 4+

captcha.tpl.php

The largest change is that is uses a newer reCAPTCHA, which results in some changes to the helpspot/templates/captcha.tpl.php file.

The new captcha.tpl.php file is as follows:

<?php if($this->hd_useCaptcha == 1): ?>


<p><label for="captcha" class="datalabel required"><?php echo lg_portal_captcha ?> - </label><b class="captcha_label"><?php echo $this->helper->encodeText($_SESSION['portal_captcha']) ?></b><br />
<?php echo $this->helper->showError('captcha','<br />') ?>
<input type="text" name="captcha" size="15" maxlength="250" value="" />
</p>

<?php elseif($this->hd_useCaptcha == 2): ?>
<?php echo $this->helper->reCaptcha( $this->hd_reCAPTCHALang ); ?>
<?php /* <p><label for="recaptcha_response_field" class="datalabel required"><?php echo lg_portal_recaptcha ?></label> - <a href="javascript:Recaptcha.reload();"><?php echo lg_portal_recaptcha_changewords ?></a><br />
<?php echo $this->helper->showError('recaptcha','<br />') ?>
<?php echo $this->helper->reCaptcha(); ?>
</p> */?>
<?php endif; ?>

forums.feed.tpl.php

One other minor change is that the Forums XML feed now assumes the UTF-8 character set (as does all of HelpSpot as of version 4).

To update your forums.feed.tpl.php file, find the following:

<?php echo '<?xml version="1.0" encoding="UTF-8"?>

And update it to the following:

<?php echo '<?xml version="1.0" encoding="UTF-8"?>' ?>

15. Troubleshooting

"Whoops, looks like something went wrong." error page.

This error message may be seen when attempting to install or during normal usage of HelpSpot. The error message on this page is rather generic, as the "data" directory not being writable is largely the most popular issue in HelpSpot 4.

As it suggests, it's important to ensure the "data" directory, and it's sub-directories, are writable by the web server.

Making the Data Directory Writable

HelpSpot comes with a directory called "data". This is written to by various processes in HelpSpot. Notably:

  • The data/cache directory, which has some cached items used by underlying code
  • The data/documents directory is the default path for email attachments saved to the file system
  • The data/logs directory contains a log file in which you can find system event and error information, included information that can be sent to HelpSpot support to help debug issues
  • The data/meta directory is similar to the cache directory, but used by particular set of underlying code
  • The data/views directory is a cache of view files used during the installation/update process

The data directory and subdirectories must be writable by the web server.

In Debian/Ubuntu, PHP is likely running as user "www-data". We can ensure these files are owned and writable by that user.

sudo chown -R www-data:www-data /path/to/helpspot/data
sudo chmod -R ug+rw /path/to/helpspot/data

In RedHat/CentOS, php is likely run as user "apache":

sudo chown -R apache:apache /path/to/helpspot/data
sudo chmod -R ug+rw /path/to/helpspot/data

If you run SELinux, then Apache needs to know that it can write to the data directory via the "httpd_sys_content_rw_t" type.

sudo chcon -Rv --type=httpd_sys_content_rw_t /path/to/helpspot/data

Server setup is outlined further for Debian/Ubuntu and RedHat/CentOS, including more possible configuration for SELinux.

Windows

The Windows installer will ensure the data directory is writable by the web server.

CLI Commands and Log File

When you update to HelpSpot 4, you might run commands before the data/logs/helpspot.log file exists. This file may get created as the user you run the command as, for example user "root" or another administrative user. If the data/logs/helpspot.log file is not writable, check to make sure it is owned by user "www-data" or "apache" as needed by your server type and setup.

My Data Directory is Writable, But I still See the Error Screen

If you still receive the blue error screen despite ensuring the data directory is writable, there is a way to get a better error message.

Edit the config.php file and change the "cDEBUG" variable from "false" to "true"

define('cDEBUG',      true); 

If you re-run HelpSpot, you may see a error screen with more available information about the error in the browser. Furthermore, the bottom of the data/logs/helpspot.log file should contain the error and stack trace of the error, which can give clues to the error or be given to us to help you with the issue.

Tables Copied/Converted

The following tables are copied via the convert:base command:

HS_Settings
HS_Address_Book
HS_Automation_Rules
HS_Bayesian_Corpus
HS_Bayesian_MsgCounts
HS_Category
HS_Category_ReportingTags
HS_CustomFields
HS_Errors
HS_Filter_People
HS_Filter_Performance
HS_Filters
HS_Forums
HS_Forums_KnownUsers
HS_Forums_Posts
HS_Forums_Topics
HS_KB_Books
HS_KB_Chapters
HS_KB_Documents
HS_KB_Pages
HS_KB_RelatedPages
HS_Login_Attempts
HS_Mail_Rules
HS_Mailboxes
HS_Mailboxes_StuckEmails
HS_Multi_Portal
HS_Permission_Groups
HS_Person
HS_Person_Photos
HS_Person_Status
HS_Portal_Bayesian_Corpus
HS_Portal_Bayesian_MsgCounts
HS_Portal_Login
HS_Reset_Password
HS_Response_People
HS_Responses
HS_Saved_Reports
HS_Search_Queries
HS_Sessions2
HS_Tags
HS_Tags_Map
HS_Triggers
HS_luSMS
HS_luStatus

These tables are copied during the convert:request command:

HS_Assignment_Chain
HS_Documents
HS_Reminder
HS_Reminder_Person
HS_Request
HS_Request_History
HS_Request_Merged
HS_Request_Note_Drafts
HS_Request_Pushed
HS_Request_ReportingTags
HS_Stats_Responses
HS_Subscriptions
HS_Time_Tracker

Windows Installer Debugging

If you encounter and issue with the windows installer process you can obtain a detailed log of the issue during runtime.

  1. Run the upgrade till the point of the error and then leave it on that screen.
  2. Go to C:\Users\Administrator\AppData\Local\Temp\2 (replace Administrator with the user you are running the installer with)
  3. In that directory there should be a bitrock_installer.txt file that will have logging information.

Patches

1. HelpSpot 4.9.5 Patch

To apply this patch:

  1. Verify that you are using HelpSpot 4.9.5 in the web Admin page.
  2. Navigate to helpspot/portal under your HelpSpot installation directory.
  3. Replace logic.php with the download included on this page.

2. Version 3.1.8

Bug on PHP 5.4 using IonCube on 64bit Linux

This bug is a problem with the IonCube loader for 64 bit linux for PHP 5.4 only. They'll be releasing updated loaders soon, but until then if the latest loader is 4.2.2 you should update to the one attached below or you could experience problems with filters and automation rules.

To apply simply download, unzip and overwrite the loader of the same name with this one.

Bug #235

  • Updated By filter condition could show incorrect results

Fix:

This patch fixes the issue

Installation:

  • Download the file below for Zend or Ioncube as appropriate for your installation
  • Overwrite file of the same name in /helpspot/lib/ and /helpspot/pages/ as in the download

Bug #234

  • Full text searches bypass the in category check when using limited access mode permissions

Fix:

This patch fixes the issue

Installation:

  • Download the file below for Zend or Ioncube as appropriate for your installation
  • Overwrite files of the same name in /helpspot/lib/

3. Version 3.1.7

Bug #224

  • Magnifying glass doesn't work in Live Lookup with multiple matches

Fix:

This patch fixes the issue

Installation:

  • Download the file below
  • Overwrite files of the same name in /static_3.1.7/js/

Bug #231

  • Filters that show the last public note cause a 500 error when there are 0 matches for the filter

Fix:

This patch fixes the issue

Installation:

  • Download the file below for Zend or Ioncube as appropriate for your installation
  • Overwrite file of the same name in /helpspot/lib/

4. Version 3.1.6

Bug #143

  • In rare cases a portal login could cause MySQL CPU to jump to 100%

Fix:

This patch fixes the issue

Installation:

  • Download the file below (for either the IonCube or Zend encoded version)
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move/overwrite files of the same name in /helpspot/lib/

Bug #155

  • IE did not show button to spellchecker in wysiwyg

Fix:

This patch fixes the issue

Installation:

  • Download the file below (for either the IonCube or Zend encoded version)
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move/overwrite display.lib.php in /helpspot/lib/
  • Move/overwrite HelpSpotSpellchecker.php in /helpspot/static_3.1.6/js/tiny_mce_3432/plugins/spellchecker/classes/

Bug #153

  • Full text search sort order could be incorrect

Fix:

This patch fixes the issue

Installation:

  • Download the file below (for either the IonCube or Zend encoded version)
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move/overwrite files of the same name in /helpspot/lib/

5. Version 3.1.5

Combo Patch 1 for Bugs #105, #108, #109, #110

  • Error lib could throw PHP error if DB connection fails
  • Name menu (top right of admin) couldn't be clicked on iPad
  • Live Lookup when run from a trigger/rule didn't send correct query parameters
  • Pipe character (|) in reporting tag name broke some reports

Fix:

This patch fixes the issues

Installation:

  • Download the file below (for either the IonCube or Zend encoded version)
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move/overwrite files of the same name in /helpspot/lib/

6. Version 3.1.1

Bug #74

MSSQL installations could not show the instant search selection list for knowledge book tags

Fix:

This patch fixes the issue

Installation:

  • Download the file below (for either the IonCube or Zend encoded version)
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move/overwrite api.lib.php into /helpspot/lib/

Bug #94

Using a trigger which sends an email can cause an error if the trigger is triggered on the portal

Fix:

This patch fixes the issue

Installation:

  • Download the file below (for either the IonCube or Zend encoded version)
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move/overwrite logic.php into /helpspot/portal/

7. Version 2.7.2

ReCaptcha

Google recently turned off their legacy ReCaptcha URL's, if you use HelpSpot over HTTPS this will break your ReCaptcha. To fix this issue simply download the latest ReCaptcha library from this URL:

http://code.google.com/p/recaptcha/downloads/list?q=label:phplib-Latest

Overwrite the exiting file in /helpspot/lib/recaptcha/ and that should fix the issue.

Bug 1529 & 1530

Fixes several reporting bugs with daylight savings time, overrun dates and time events when reporting on a single day.

Fix:

This patch fixes the issue

Installation:

  • Download the file below (for either the IonCube or Zend encoded version)
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move class.reporting.php into /helpspot/lib/

8. Version 2.7.0

Bug 1372

CSV output for Speed to First Response report does not take business hour selection into account

Fix:

This patch fixes the issue

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move excel.php into /helpspot/pages/
  • Move class.reporting.php into /helpspot/lib/

9. Version 2.6.3

Bug 1080

RSS feeds can contain HTML tags in RSS title tags under some conditions

Fix:

This patch makes sure HTML tags are stripped from the RSS feeds

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move feed_filter.php into /helpspot/pages/

Bug 1088

Person list in time tracker includes inactive staff when it should not.

Fix:

This patch removes inactive staff from the list

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move request.php into /helpspot/pages/

Bug 1104 & 1263

1104: When uploading multiple files via API in private.request.update all but the first will fail

1263: Reporting tags can not be added via private.request.create in some cases

Fix:

This patch fixes the bug so all files upload correctly and reporting tags can be added.

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move class.api.private.php into /helpspot/lib/

Bug 1231

The special "additional" portal hidden field does not work when the portal form is set to use the simple format.

Fix:

This patch fixes the bug so the additional information is captured

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move logic.php into /helpspot/portal/

10. Version 2.6.0

 

Bug 974

This bug causes an insecure content message in Internet Explorer when HelpSpot is running over HTTPS.

Fix:

This patch fixes a file path in one of the javascript libraries to prevent this message.

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Move class.cache.statis.php into /helpspot/lib/
  • Move prototip.js into /js/prototip/js/
  • Login to HelpSpot and change the URL to admin.php?clearcache to clear the javascript cache

 

11. Version 2.4.7

Bug 561

This bug causes emails forwarded into HelpSpot which only have a name in the forwarding information and not an email address to incorrectly set the customer email address in HelpSpot.

Fix:

This patch makes HelpSpot ignore the forwarding information if an email address is not in the forwarding information.

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Both files overwrite files of the same name in /helpspot/lib/

Bugs 623 and 624

These bugs affect the public API. 624 caused the array of files to be returned directly in the request history. The patch creates a tag for files and files are contained within that so that most XML parsers return an array of files.

623 prevented files from being uploaded into a request with an update. 

 

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Both files overwrite files of the same name in /helpspot/lib/

Bug 631

This bug causes the portal black box system to not allow logins even with valid credentials.

Fix:

This patch fixes this issue.

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • The logic.php overwrites a file of the same name in /helpspot/portal/
  • The class.api.public.php overwrites a file of the same name in /helpspot/lib/

Bug 627

This bug causes an unusual number of emails to get stuck and stuck email notifications to appear in the Workspace.

Fix:

This patch fixes an issue with the spam check system that causes this issue.

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • The file overwrites a file of the same name in /helpspot/lib/

 

Bugs 629 and 639

Bug 629 is a display bug where non-email requests show a subject line in filters.

Bug 639 is a bug in the private.request.search API method that prevents a tNote from being returned with the search results.

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • All files overwrite files of the same name in /helpspot/lib/

Bug 821

Knowledge book pages that have embedded flash movies which have been uploaded to HelpSpot (not directly linked outside of HelpSpot) fail to play for portal visitors in FireFox/Safari when using Flash 10.

Fix:

This patch changes the HTTP headers so that the video's play

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Overwrite the file of the same name in /helpspot/pages/

Improvement 607

Dramatically improves speed for filters based on reporting tags and several other conditions.

Installation:

  • Download the file below
  • Unpack on the server if possible. If not and you must use FTP to move the file be sure to force binary mode in the FTP client
  • Overwrite the file of the same name in /helpspot/lib/

 

Release Notes

1. Upgrading - Redirect

Upgrade documentation has moved for HelpSpot 5. Please visit: https://support.helpspot.com/index.php?pg=kb.chapter&id=95

2. New Release Notes Location

Release notes are now located at https://helpspot.com/releases. Please update your bookmarks.

3. Version 4.0.30

Release notes now found on:

https://www.helpspot.com/releases

4. Version 4.0.29

Bug Fixes

  • Fixed issue in output of secondary portals which included an invisible null byte character in the output for the config.php file, resulting in hard to diagnose php errors
  • Fixed an issue where email subject lines could get stripped out under certain conditions related to email character set and multipart settings

5. Version 4.0.28

Enhancements

  • Added an index on session table for users with large numbers of sessions

Bug Fixes

  • Fixed bug where OOO checks in conjunction with round robin auto-assignment within a category could result in a single person getting more requests than they should
  • Certain characters for database passwords in SphinxSearch configuration file escaped
  • Fixed issue where non-multipart emails required converting Subject line to utf-8 encoding (Otherwise resulting in an error when inserting into SqlServer databases)
  • Updated export of csv files to be more compatible with Excel when using special character
  • Fixed issue where filenames of a file/attachment being downloaded containing path separators or "%" characters generated an error

6. Version 4.0.27

Bugs

  • Fixed bug where admin editing a Response changed owner of the response to themselves
  • Fixed issue where SMS notifications were not sent on staff notifications (to staff added to "Notify Staff" section when editing a response)
  • Fixed issue where FULL REQUEST HISTORY email template tag may not have included the most recent note on staff notifications 

Enhancements

  • Security Improvements
  • Admins can change owner of a Response
  • Responses no longer paginated, as it provided an issue for customers with large numbers of responses

7. Version 4.0.26

Reverted an update from 4.0.25 which caused multiple triggers that should normally fire against a request update may to potentially not fire

8. Version 4.0.25

Bug Fixes

  • Fixed missing ##name## replacement in the notify staff on a request email. 
  • Fixed incorrect message that said "Opened via Portal" when a customer reopened a request through replying by email. 
  • Fixed a bug when updating from HelpSpot 3 to HelpSpot 4 where a MySQL databaes connection may be made incorrectly, resulting in an error during update
  • Fixed bug where converting request to public or private note would result in raw HTML being displayed

Enhancement

  • Multiple triggers will test result of previous trigger ran rather than original data

 

9. Version 4.0.24

Bug Fixes

  • Fixed a bug introduced in 4.0.23 where editing a custom field could mistakenly set it's maximum length to "1"
  • Fixed a bug where subscribed staff may not be notified on a new, unassigned request
  • Fixed a bug where users set as Out of Office may be mistakenly selected if they are within a round-robin assignment within a default category

Enchancements

10. Version 4.0.23

Bug Fixes

  • Staff subscribed to a request now get notification emails even if "send notifications via email" is unchecked. To stop emails they need to unsubscribe from the request.
  • Fixed issue with extra field dates and utf8 languages.
  • When using the keyboard shortcut to search the input wasn't getting cleared out. 
  • Removed a double line break with signatures in HTML email. 
  • Fixed an issue with the WYSIWYG editor inserting response placeholders as headings. 
  • Fixed issue where MySQL client may incorrect fallback to latin1 character set instead of utf8/utf8mb4 on Linux
  • Fixed an issue during upgrade where email headers may not be parsed correctly
  • Fixed overflow in note history with non-breaking strings.
  • Fixed sanitization on portal pages.
  • Fixed portal category grouping option in portal template code.
  • Prevent browser from autocompleting username and password when editing staff members.
  • Removed unneeded br tag that was inserted before email signatures 
  • Fix calendar display for foreign languages
  • LiveLookup grid results now overflow with a horizontal scroll bar.
  • Time Tracker is now more accurate even when in a background tab.

Enhancements

  • Improvement in SphinxSearch delta indexes. If you would like, after updating, you can re-generate your Sphinx configuration file using the search:config command.
  • Added group by Category option to the Time Tracker Over Time report.
  • The HelpSpot logo now look better on retina screens

11. Version 4.0.22

Bug Fixes

  • Fixed issue when clicking "done" after reordering triggers in IE11. 
  • Removed "now viewing" when opening a request in peek view.
  • Fixed issue where a slash "/" in the mailbox password would give an error response. 
  • Resolved Windows updater issue when updating from 3.2.12 to 4.0.21 where custom fields may not be re-created correctly

 

Enhancements

  • Live lookup HTTP requests can use user-defined query strings, e.g. example.com?foo=bar
  • Added a new hs command: request:delete to delete a single request
  • Added a new hs command: request:delete-spam to delete all spam currently in the spam queue
  • Custom Connection (Admin > Settings > System > Customer Connect) UI option added to control diagnostic reporting

12. Version 4.0.21

Internal Changes

  • When an email comes in with only a single name in the email header we now treat that name as the first name rather than the last name.

Bug Fixes

  • Fixed round-robin assignments going to deleted staff
  • Fixed issue where blank SMS notifications may be received
  • Fixed issue where plaintext emails may be marked has html in email headers
  • Fixed bug where attachments/files may not be retrieved from the filesystem or SqlServer correctly
  • Fixed issue where replying to staff notifications set the response to private.
  • Fixed filenames for download that may not have ascii-only characters
  • Fixed issues where email replies may mistakenly be marked as private
  • Changed WYSIWYG to not attempt to change URLs, which affected Windows local file paths
  • When editing staff account ensure the secondary email is entered when checking send notifications to secondary email. 
  • If sending a reply fails reopen the request and show the error.
  • Fixed address book issue where clicking a letter wouldn't scroll to the correct location. 
  • Fixed database error when sorting reminders.
  • Fixed issue with API kb searching setting the wrong root tag if Sphinx installed.

Enhancements

  • Added the ability to turn off gravatar photos. See the hidden settings page for instructions.
  • Text Custom fields now use the number entered as the column size. 
  • Admin now requires you to confirm the email address when editing a user 
  • Updated database library for usage with Windows installer upgrade, which uses PHP 5.6 (as of 4.0.20) and related SqlServer drivers

 

13. Version 4.0.20

Enhancements:

  • Email sending library replaced with more modern library, resulting in better error messages and SMTP support
  • MySQL can connect to servers in alternative ports using hostname format `hostname:port`, e.g. `127.0.0.1:3306`
  • Minor improvements in Advanced Search searching tips
  • Windows installer updates PHP to PHP 5.6, which has official support until 2019. (Note that HelpSpot is not yet tested on PHP 7 yet)

 

Bug Fixes:

  • Fixed issue where stored incoming email headers may have incorrectly been stripped out when viewing in admin area
  • Fixed instances where public replies from staff to customers from their email client did not get added as a public note
  • Portal image styles (defaults) tweaked, adding max-width
  • Fixed IE cache bug, overly-eager at caching
  • Fixed issue with placeholder replacement when using a url that is different than cHOST.
  • Fixed issue with html all on one line being stripped. 
  • Removed "take it" button from closed unassigned requests.
  • Fixed issue where Sphinx configuration did not pull in create date of items from Request History, resulting in relevant search results being pushed to the bottom of results
    • We recommend re-generating your Sphinx configuration file
  • Fixed local storage saving when editing existing requests.
  • Fixed issue where mysql host in format of `hostname:port` generated incorrect Sphinx configuration
  • Fixed issue where Safari and iOS could not play .wav files (commonly emailed into HelpSpot as voicemails)
  • Fixed bug where email message ID may not be correctly added to an outgoing email (affected replying to a customer directly from email client)

14. Version 4.0.19

 

Fixes

  • Remove backslashes "\" from drop down lists custom fields.
  • Allow target="_blank" in links created from WYSIWYG. 
  • Fixed issue where IE was too aggressive in caching pages.
  • Adjusted email parsing to account for signatures that had weird formatting. 

15. Version 4.0.18

Enhancements:

  • Tasks now also checks and deletes old error logs and filter performance metrics, helping reduce database size over time

Bug Fixes:

  • Fixed issue where grand-fathered Unlimited licenses were incorrectly reported as invalid during update to HelpSpot version 4
  • Fixed issue for Windows users on Apache, where openssl and curl PHP binaries did not function correctly (loaded old files from Apache installation over the correct PHP dll files)

16. Version 4.0.17

Enhancements

  • Add ability for email templates to include "tel:" and "sms:" links.
  • Added "Next 7/14/30/90/365 Days" to date conditions in filters and rules
  • Options to connect to MySQL via SSL
  • Security Improvements

Fixes:

  • The closing date wasn't being set when creating a brand new request and closing it.
  • In the portal, inline image attachments pointed to the wrong location. 
  • Fixed tabindex on the request screen for drill down extra fields.
  • Improved the performance of the filter management admin screen
  • First Response Speed (biz hours) in filters had incorrect time.
  • Validation check to prevent using the same email for mailboxes and staff. 
  • Fixed opening image attachments in a modal window on closed requests.
  • Updated HelpSpot Windows installer to fix issue where customers on alternate drives (not the C:\) had issues updating. 

17. Version 4.0.16

Enhancements

  • Added "Urgency" condition to Triggers, to test if a request is (or is not) urgent

Fixes

  • Fixed issue where popup blockers prevented viewing a knowledge book in the portal from admin. 
  • Fixed issue where business hours was defaulting to "45 minutes", if you entered 8:00 it would show 8:45. 
  • Windows install bug fixed for Windows customers using MySQL that was not bundled with HelpSpot. The installer assumed MySQL customers were using bundled MySQL's.
  • Fixed issue when adding time to a request the log would get cleared out until you refreshed. 

18. Version 4.0.15

Enhancements

  • Added a Safari pin icon. In Safari, right click on your HelpSpot tab to pin HelpSpot to your tab bar.
  • Mailbox ID's are now included in email errors

Fixes

  • Fixed issue where the last public note wasn't showing in filters.
  • Fixed bug where filter/mail rule condition field ID's not always random

Notes:

  • Version 4.0.14 fixed a security vulnerability, it's recommended you update to the latest HelpSpot
  • Users of HelpSpot 3 (versions 3.1.1 - 3.2.12) can download a patch file within https://store.helpspot.com

19. Version 4.0.14

Bugs

  • Security improvements
  • Official release (non beta) of bug fixes from version 4.0.13

20. Version 4.0.13

Bugs

  • KnowledgeBook search results had no ID in URL of results
  • Fixed issue where local storage wasn't being cleared after creating a new request.
  • Updated Live Lookup to filter out HTML email content fields, which were received when automating Live Lookup through triggers
  • Fixed issue where SqlServer customers, in particular using German language, were seeing garbled character sets (especially on umlaut's).
  • Fixed issue where MySQL customers may have garbled filters during update to version 4 (usually coinciding with a mismatch when storing as UTF-8 but setting the connecting client as latin1 or latin2 character sets).
  • Actually, for realsies, fixed issue of php.ini's date.timezone setting (or lack of setting) generating an invalid license error on update. Seriously, I think we got it this time.

21. Version 4.0.12

Bug Fixes

  • Resolved issue where the initial request column in the workspace had weird character spacing.
  • Resolved issue with the selected state of select fields.

22. Version 4.0.11

Bug Fixes

  • Resolved issue where select drop down option value incorrectly parsed when it had integer values
  • Resolved issue where some customers experienced using HelpSpot commands where a PHP class was not found

23. Version 4.0.10

Features

  • Drafts are now saved automatically to the browsers localstorage for new requests, where supported

Bug Fixes

  • String vs number values in custom fields (leading/traililng 0 issue)
  • Notifications may have failed to be received due to being flagged as duplicate by mail servers
  • Fixed issues for PostgreSQL database during updates
  • Fixed issues where customers with large number of custom field ran into MySQL error due to limit of 64 indexes per table

24. Version 4.0.0 - 4.0.9

HelpSpot Version 4 Changelog (July 21, 2015)

Upgrade Documentation - Note upgrading requires you be on HelpSpot 3.2.12 first.

Major Features:

  • HelpSpot Cloud - Hosting for HelpSpot provided by Userscape
  • Native iOS/Android applications
  • True multi-lingual support (UTF-8 character set support)
  • Better search via SphinxSearch search engine
  • See https://www.helpspot.com/new for more!

Additional features:

  • Sidebar can search request history.
  • Added user option - User can decide to make sidebar search full history by default
  • Modified attachment handling so they are not lost when switching between public/private/external.
  • CLI Commands now supported in HelpSpot!
    • attachments:tofile - Save database attachments to the filesystem
    • convert:base - Convert helpspot 3 database to helpspot 4 database
    • convert:requests - Convert requests to UTF8 for helpspot 3 to 4 update
    • search:config - Generate configuration for Sphinx serach engine
    • update - After installing new HelpSpot files, run this command to update HelpSpot, useful for automating the update process
    • db:exists - Test if HelpSpot database (as configured in config.php) exists and has HelpSpot data within it
    • reset:email-templates - Reset email templates to "factory defaults"
  • Improved the markdown handling
  • Ability to add attachments to responses.
  • Added replying to notifications as public responses back to customer
  • API error responses for merged requests now returns the request ID of the correct request. Developer Note: API errors can now return meta data about the request $this->_error(208, '', ['field_name' => 'some_value']);
  • Added additional email loop protection - HelpSpot ensures it is not emailing itself
  • Added private.meta - api call for getting basic details on the installation
  • Added private.util.getAllStaff - gets all staff ever in the install
  • Added private.util.getStaffPhoto - base64 of staffer image. Expects xPerson passed in via get
  • Viewing of closed requests now tracked and displayable
  • Improved display of currently viewing. Now shows in the workspace grid.
  • Added grouping by customer id and customer email to requests over time and total over time reports
  • Support for Outlook's [mailto: example@domain.com] format in forwarded emails.
  • Filter has new "last update by" column, to show if last update (of any kind) was done by staff, the system or a customer.
  • Custom fields of type date or datetime in email defined as ##hs_custom<fieldid>:1234567890## can now parse human-readable dates, such as: ##hs_custom<fieldid>:11/13/1984 11:59:00## (the date format there can vary greatly and still be parsed accurately).
  • Added LDAP library that's easier to use for Authentication and Live Lookup.
  • Added private.request.markRead and private.request.markUnRead (only usable for requests assigned to the user)
  • Implemented Google's latest reCAPTCHA on public portal
  • Added private.request.markTrash - mark a request as trash
  • Added private.request.markSpam - mark a request as spam
  • Removed fTrash flag option from private.request.create and private.request.update 
  • Added skipCustomChecks to private.request.create and private.request.update - allows custom field checks to be skipped
  • Added private.response.listAll - returns a list of all responses
  • Added private.response.usersMostCommon - returns the top 10 responses used by a user
  • Added private.response.get - returns a response
  • Added webhooks to triggers and automation rules (need to document sample of what's POST'd perhaps in api docs?)
  • Added ##hs_request_id:012345## email parser tag to assign update to an existing request ID, useful if automated systems (e.g. eBay support) strips out the {12345} request ID tag from the subject line
  • Removed spellcheck module in TinyMCE wysiwyg in favor or browser-based spellcheck. All modern browsers now support this (including IE10+).
  • Live Lookup now expects your xml to be in UTF-8.

Bug Fixes:

  • Fixed users not receiving email on new, un-open requests.  
  • Fixed dtGMTClosed date when setting fOpen = 0 via api - 
  • Fixed a bug where clicking a predefined response parent folder would send the user to /null - 
  • Fixed a bug when activating a previously de-activated trigger with a quote in the name would trigger a js error. - 
  • Fixed a bug where some API calls that error could dump out invalid XML. 
  • Fixed word break in request history for IE9 - NOTE: Need to document the portal templates css change - 
  • Fixed the html to text conversion when quoting. 
  • Fixed bug when calculating minutes in reports.
  • Fixed bug where multiple space-separated names in ##hs_customer_firstname## and ##hs_customer_lastname## email tags weren't parsed correctly. For example fname: herbert walker and lname: bush would turn into fname: herbert and lname: walker bush.
  • Fixed bug where trigger notifications to staff included incorrect REQUESTCHECKURL value 
  • Fixed bug with advanced tags encoding 
  • Fixed bug where setting batch status to active wouldn't reopen the request. 
  • Fixed xss issue with customer information and extra fields. 
  • Improved on styling for minor issues
  • Improved cache handling for images retrieved behind authentication
  • No longer url-encoding mailbox folder (INBOX and subfolders) so customers can include sub-folder mailboxs such as INBOX/helpspot.
  • Fixed KB title to be converted to htmlentities on save. 
  • Fixed cdata in multiple results of LL 
  • Fixed toggling of tags in responses 
  • Fixed ability to set out of office forwarding to yourself. Basically anyone except the current staff you are editing. 
  • Fixed issue where if you was subscribed to two tickets and later they became merged. You were subscribed twice. 
  • Force logout users when marking them as inactive from admin.

25. Version 3.2.12

Version 3.2.12 Change log (July 9th, 2014)

  • Improved update in WYSIWYG to result in improved button layout for users who have not customized the WYSIWYG button layout previously. Will only affect users updating from 3.2.10 or lower to 3.2.12.
  • Improved wording on instructions for WYSIWYG buttons.
  • Added "browser_spellcheck" option (if applicable) to WYSIWYG to allow browser-based spellchecking as per latest TinyMCE documentation
  • Fixed issue where running HelpSpot in an iFrame would not fully function when a URI-encoded entity was present for $_GET variables, used to fill out customer information.
  • Fixed issue in Triggers & Rules where stripping HTML out of search terms also stripped out email that were in format "FName LName <sample@email.com>"

For the latest WYSIWYG update (version 3.2.11 and higher), we suggest using a button format of the following when editing requests. This can be edited in Admin > Settings > HTML Email:

  • Button Row One: styleselect fontsizeselect | outdent indent | undo redo | code
  • Button Row Two: | bold italic underline strikethrough | link unlink | blockquote | bullist numlist | removeformat | pastetext pasteword | forecolor backcolor
  • Leave Button Row Three empty

These options will appear look like so:

...and will result in this layout:

26. Version 3.2.11

Version 3.2.11 Change log (June 18th, 2014)

  • NEW Inbox zero messages
  • NEW Wysiwyg for improved performance in all browsers
  • Responses used via the search for responses function weren't counted in the response usage report
  • Fixed issue with PHP 5.3 on installs missing mbstring not encoding some things correctly
  • Fixed repeating notes in the note stream
  • Fixed escaping of some characters in responses
  • Fixed ReCaptcha on HTTPS urls
  • Fixed a bug with Windows-Baltic encodings
  • Improved matching of the body text of emails when using 'contains'
  • Account Name placeholders were not properly set in automation based emails
  • Fixed bug where IIS based installations could not use Live Lookup via automation rules/triggers due to HTTP GET length
  • Fixed issue where inactive staff could be assigned requests via automation rules
  • Fixed issue where CC/BCC addresses on external notes would be added to public notes and have to be manually removed
  • Fixed users showing up more than once in the "viewable by" label on filters
  • Fixed bug where last insert id may not be returned correctly in some cases

27. Version 3.2.10

Version 3.2.10 Change log (January 24th, 2014)

  • Bug - Latest Chrome version (32) incorrectly set tooltip height
  • Bug - Some custom fields weren't deletable on SQL Server 2008+
  • Bug - Emails with certain unencoded characters could be cut off, resulting in missing content
  • Bug - Curly quotes and other special characters were converted to question marks instead of the correct standard character

28. Version 3.2.9

Version 3.2.9 Change log (December 26th, 2013)

  • New Feature - Added the ability to update requests as a customer via private.request.update
  • Bug - Grouping by contacted via in reports didn't show mailboxes correctly
  • Bug - Prevent sending notification emails in some cases to inactive users
  • Bug - Improvements for IE10 and IE11
  • Bug - Adjust wysiwyg to fix issue with nested lists in Outlook
  • Bug - Improve merge UI in workspace to include more information in drop down
  • Bug - Fixed issue where last selected request for batch merge would not be listed
  • Bug - Fix time tracker column display in filters
  • Bug - Batch responding with a response will now apply 1 usage for each batched reply rather than 1 total for the entire batch in response usage report
  • Bug - Fixed load more in inactive users
  • Bug - Fixed remove request button from batch importing UI
  • Bug - Fixed search for staff where it could be broken in some cases

29. Version 3.2.7

Version 3.2.7 Changelog (November 8th, 2013)

  • New Feature - Gravatars are now shown in request history for customers who have them
  • New Feature - Add ability to group reports by drill down custom fields.
  • Bug - Add validation to reminders to make sure a date is set before submitting
  • Bug - Fixed issue with some triggers not replacing the ##ACCESSKEY## correctly.
  • Bug - Fixed some html labels that didn't match up to the correct inputs.
  • Bug - Fixed issue with triggers not being called in API request.update
  • Bug - Fixed issue with reattaching an attachment with an apostrophe in the file name.
  • Bug - Fixed issue with category tags not working correctly if it contained a percent symbol.
  • Bug - Response folders were not respecting permissions
  • Bug - Fixed issue with grouping by year in reports
  • Bug - Adjusted the way drafts are saved.
  • Bug - In CSV export change the time tracker time to be in seconds.
  • Bug - Fixed issue with time tracker not escaping properly.
  • Bug - Hide the next / previous when opening the request modal from a sidebar search.
  • Bug - The keyboard shortcuts were not respecting the workspace view type.
  • Bug - Made Javascript includes work across http/https for mobile UI to prevent warnings

30. Version 3.2.5

Version 3.2.5 Changelog (June 24, 2013)

  • Bug - display of request subscribers was not working and adding errors to the error log.

31. Version 3.2.4

Version 3.2.4 Changelog (June 18, 2013)

  • Bug - Changed an internal setting that creates a hard lock on MySQL databases when merging requests. On low performance servers this created significant database contention. HelpSpot will no longer lock the request tables while merging. However, if you're on a database configuration with good performance for your HelpSpot installation size this can be re-enabled via a hidden setting.
  • Bug - Changed the embed shortcuts so they are less sensitive
  • Bug - In mobile UI remove inactive users from selection list
  • Bug - Remove subscribers when they are marked inactive.
  • Bug - Fixed admin -> mailboxes sorting by name
  • Bug - Fixed issue when clicking the attachment icon
  • Bug - Fixed double inserting a URL in the mail notes template
  • Bug - Fixed the trigger for "contacted via", "Now is", "Email"
  • Bug - Limited staff shouldn't get notification on new uncategorized requests.
  • Bug - Fixed support for german forwarded emails
  • Bug - Fixed time tracker person list should honor the limited to category setting.
  • Bug - Fixed report grouping by contacted via.
  • Bug - Adjusted the print stylesheet for the ticket
  • Bug - Fixed support for basic authentication on API/RSS feeds on fastCGI setups
  • Bug - Fixed bug where editing a reporting tag would create a new one rather the editing the existing ones name
  • Bug - Fixed issue with IE and the drill down list on the portal
  • Bug - Accented characters in custom field selection items cause reports to fail to load

32. Version 3.2.3

Version 3.2.3 Changelog (4/19/2013)

  • New Feature - Filter management and performance screen now available in Admin -> System -> Filter Management
  • New Feature - Filters that don't use a date range are now limited to the past year of results by default to improve poorly constructed filters. This can be adjusted in Admin -> Settings -> System or disabled there if desired. If you're seeing some tickets "disappear" after upgrading it's like due to this setting so you may want to extend the range to more days or disable.
  • Bug - Fixed several bugs with the Windows installer
  • Bug - Auto refresh in Workspace wasn't always refreshing correctly
  • Bug - Fixed several SQL Server errors and bugs

33. Version 3.1.9

Version 3.1.9 Changelog (1/30/2013)

  • Bug - Full text searches could bypass limited to category permission
  • Bug - Update By could return incorrect results
  • Bug - Embedded images have incorrect URL in the portal and API results
  • Bug - A bad character could break grouping by assigned user reports
  • Bug - A rule with more than one request push call fails after first
  • Bug - Live Lookup would not follow a URL redirect
  • Bug - Fixed SMS notifications on urgent requests
  • Bug - private.filter.get didn't honor user permissions
  • Bug - Fix Windows installer bug with LDAP PHP module
  • Update - TinyMCE wysiwyg
  • Update - PHP in Windows installer to 5.3.20

34. Version 3.1.8

Version 3.1.8 Changelog

  • Bug - Fixed error on filters which tried to show last public notes in a filter with 0 results
  • Bug - Fixed bug in Live Lookup where multiple result could not be viewed via magnifying glass icon
  • Bug - Adjusted session key storage size for some systems

35. Version 3.1.7

Version 3.1.7 Changelog

  • New - Support for unlimited user licenses
  • Change - The "Updated By" condition is now applied after the results of other conditions to enhance performance for it's more common use cases
  • Change - Windows Installer upgrades PHP to 5.3.15
  • Bug - Improved checking for empty fields in Live Lookup
  • Bug - A long line in an email could cause the outbound email to be truncated
  • Bug - Improved speed when selecting last public note for display in filters
  • Bug - Fixed Firefox 13 bugs
  • Bug - Fixed spellchecker default for Chrome/Firefox
  • Bug - Triggers would not check note type properly
  • Bug - Forums LatestTopics parameter in templates did not honor setting
  • Bug - Fixed error with SQL full text search
  • Bug - Passing an empty field to the API incorrectly caused the request creation to fail
  • Bug - A wrong URL was included in staff notifications
  • Bug - Character fixes to widget
  • Bug - When API's are off return HTTP code 400 rather than 200
  • Bug - In emails a bad character could cause data to be stripped
  • Bug - Widget background failed to close on Firefox
  • Bug - Fixed update and close on mobile
  • Bug - Knowledge pages didn't detect HTML content containing only HTML lists as HTML pages
  • Bug - Incorrect rounding of decimal fields in grid view
  • Bug - Long numeric only strings in a text custom field were rounded
  • Bug - Links to KB weren't properly linked in full public history placeholder
  • Bug - Fixed spellchecker on IE
  • Bug - Changed ordering of full text search results
  • Bug - Various wording changes
  • Bug - Request push could fail to return error information in UI
  • Bug - Bad data in a MySQL query could cause high load on the MySQL server

36. Version 3.1.6

Version 3.1.6 Changelog

  • Bug - Add admin username/password for built in LDAP authentication
  • Bug - The popup calendar would not work from the search page
  • Bug - Time tracker events report could fail to load
  • Bug - Non HTML notes sent in via the API displayed with HTML paragraph tags
  • Bug - Tag search on the portal could show a non-functional link to a hidden page of a public book
  • Bug - Triggers sending email could end up with a PHP error
  • Bug - private.request.create should not append a signature to a note when using xPersonOpenedBy=0 (customer)
  • Bug - Triggers with multiple actions could cause a PHP include error
  • Bug - MSSQL had an error with full text search using "is not" in a phrase
  • Bug - Triggers could not match custom field checkboxes
  • Bug - Triggers could fail to match changed conditions
  • Bug - Made response usage report more accurate and clear by removing filter option
  • Bug - Changed UI of public notes to customers template editing to notify but not request a request ID be included
  • Bug - Responses could fail to display properly for group user permissions
  • Bug - Live Lookup via a trigger could sent the wrong HTTP GET parameters to the Live Lookup script
  • Bug - The name menu (top right corner) could not be clicked on iPad
  • Bug - Emailing customers from an automation rule/trigger could fail in some cases
  • Bug - A pipe (|) in a reporting tag breaks the reports

37. Version 3.1.5

Version 3.1.5 Changelog

  • Bug - Triggers may not be executed in some scenerios when they should be
  • Bug - Fixed several character encoding issues
  • Bug - Title bar count didn't match total of the filter
  • Bug - Adjusted full text search ordering
  • Bug - Getting started tab didn't register custom reports
  • Bug - Open before/after filter condition didn't properly set time of day
  • Bug - SMS would not send from Automation Rule
  • Bug - Empty date custom fields would show today's date in workspace grid
  • Bug - Response search could show responses not in a users permissions
  • Bug - Name menu had to short a closing delay for iPad
  • Bug - Email headers would not display more than 1 of same header (like received)
  • Bug - Response search would show inactive messages
  • Bug - Triggers that generated emails from portal actions could have a PHP error
  • Bug - Portal query error for secondary portals with no KB's
  • Bug - Added more mime type extensions for attachments with invalid or unknown names
  • Bug - Emails in Windows-1257 character encoding could have characters dropped from email
  • Bug - Response folders could not display due to javascript error
  • Bug - Filter CSV should download all results
  • Bug - KB images may not display in secondary portal
  • Bug - Mobile ui shows inactive users in drop down
  • Bug - Fixed issue where custom pages were only for admin users
  • Bug - Time events report now has customer ID column
  • Bug - IE8 category selection javascript error

38. Version 3.1.1

Version 3.1.1 Changelog

  • 2127: Bug - My Queue read/unread image click improperly incremented
  • 2352: Bug - Triggers could miss some events such as reopens of requests
  • 2384: Bug - Fixed problems with links to requests after a left navigation search
  • 2386: Bug - Moved to using HTML5 audio plugin on supported browsers for inline audio attachments
  • 2388: Bug - Fixed "load more" on filters
  • 2391: Bug - Added groupings to Speed to Resolution report
  • 2395: Bug - Fixed inline image inserts on Webkit browsers
  • 2397: Bug - Address book could not delete contacts
  • 2401: Bug - Fixed issue with drop down lists in popup tooltips on IE
  • 2402: Bug - Fixed error where MS SQL Server could not delete custom fields
  • 2406: Bug - Fixed addition error on response usage report
  • 2412: Bug - Fixed error where filters listed above the inbox could show the wrong count
  • 2416: Bug - Permission groups without spam access could still see spam controls in some places
  • 2449: Bug - Fixed issue where automation rule could improperly reassign a request from an out of office user
  • 2450: Bug - Knowledge tag cloud search wouldn't show all results
  • 2476: Bug - Fixed time tracker report error
  • 2488: Bug - When adding a category custom fields now default to unchecked
  • 2498: Bug - Tag search when no forums exist caused an error on SQL Server
  • 2518: Bug - IE8 javascript errors
  • 2521: Bug - Inactive responses returned in response search on request screen

39. Version 3.1.0

HelpSpot 3.1.0

3.1.0 is the first production ready release of the version 3 series. See what's new in V3.

HelpSpot V3 and 3.1.0 in particular contain important new security features and enhancements. All users are encouraged to upgrade.

  • 2195: Feature - New password reset system for improved password security along with other password improvements
  • 2170: Feature - Added the ability to group requests by category reporting tags in requests over time report
  • 2183: Feature - Added next/back to closed requests
  • 2331: Feature - Added report for response usage
  • 2135: Feature - Added report for knowledge book helpfulness
  • 2188: Bug - Responses more than one folder deep would not appear in some permission setups
  • 2189: Bug - Added TO to LiveLookup address book search
  • 2191: Bug - Fixed various issues with IE7
  • 2206: Bug - Option to set custom field order was not visible
  • 2213: Bug - Improved pie chart colors on Todayboard
  • 2223: Bug - A trigger which checked a mailbox value caused an error
  • 2251: Bug - Improved public/private/external note visual indicators
  • 2277: Bug - A trigger could cause a PHP error on the portal in some cases
  • 2278: Bug - Re-attachments fail to be emailed
  • 2329: Bug - Knowledge tag cloud did not display on homepage under SQL Server
  • 2358: Bug - Fixed issue where printing pages did not use print stylesheet
  • 1635: Bug - Fixed issue where two triggers could conflict
  • 1807: Bug - Custom stylesheet now referenced in HTML emails
  • 2073: Bug - IE9 fixed report hovers
  • 2081: Bug - Made billable checkbox label clickable
  • 2086: Bug - Filter count didn't show in title when 0
  • 2087: Bug - Closed requests didn't display custom field information
  • 2088: Bug - Fixed installer to check for PHP equal to 5.3.0 rather than greater than 5.3.0
  • 2095: Bug - Fixed the display of several reports under Microsoft SQL Server.
  • 2098: Bug - Private books would show "link to" when they should not
  • 2100: Bug - File attachments were not accepted correctly via the API
  • 2106: Bug - Modal confirm notifications now defaulted for faster acceptance
  • 2113: Bug - RSS filters would not display complete content
  • 2115: Bug - Adding time tracker time on a new request left the date at January 1 instead of today
  • 2118: Bug - Secondary portals could not show helpful pages on homepage from more than one book
  • 2120: Bug - Restored ability to see Time Tracker entries on closed requests
  • 2141: Bug - Request history would be truncated in wrong place

40. Version 3.0.8 Beta

3.0.8 Changes

  • 1993: Feature - New reports: customer activity, response usage
  • 2019: Feature - Added "logged in user" as an option for assignment chain filters
  • 2031: Feature - Added billable checkbox to time tracker
  • 1906: Feature - Anonymous error submission system (setting in admin-settings-system)
  • 2032: Bug - Updated various wording
  • 2054: Bug - Files could not be deleted from KB's
  • 2063: Bug - Fixed issue where resized images could fail to be deleted and use disk space
  • 1902: Bug - Added check to protect system if new files are uploaded but installer.php is not run
  • 1905: Bug - Fixed various SQL Server errors
  • 2020: Bug - Changed calendar layout to be Sunday - Saturday
  • 2021: Bug - Fixed Windows installer which could fail to build scheduled tasks on Win 2003
  • 2028: Bug - Not all custom predefined list fields would display in Request Over Time report grouping option
  • 2030: Bug - Filter custom field columns that should show 0 would display blank instead
  • 2002: Bug - Added "serious mode" setting allowing phrases and other fun things to be disabled
  • 2001: Bug - Adjusted inbox zero phrases to only display sometimes to increase randomness
  • 2003: Bug - Removed the ability for extra emails on the TO line to be automatically converted to CC's (this caused to many issues with looping/self notifying)
  • 2018: Bug - Fixed/disabled WYSIWYG on iPad/iPad2
  • 1926: Bug - Date/Datetime custom fields did not work on portal
  • 1931: Bug - The Windows installer upgrading a V3 installation to a newer V3 installation could break fastcgi
  • 1933: Bug - Portal popup did not work in IE
  • 1934: Bug - Full text search failed on MS SQL
  • 1946: Bug - CSV exporting was not working for filters
  • 1951: Bug - Fixed ordering of filters in the Workspace
  • 1954: Bug - When a request email fails the staffer is returned back to the request screen to review
  • 1956: Bug - Don't allow creation of reminders in the past
  • 1959: Bug - private.request.get now marks external notes as such via a new tag that's returned in the note history items
  • 1960: Bug - Improved usability of public/private/external selector
  • 1961: Bug - Improved usability of Timezone selector box
  • 1962: Bug - Fixed default workspace setting
  • 1984: Bug - Improved request history load speed when first opening a request
  • 1991: Bug - Fixed some date/time formatting in reports
  • 1992: Bug - Several security related fixes and enhancements

41. Version 3.0.7 Beta

3.0.7 Changes

  • 1886: Feature - Added a new api call: private.request.subscriptions() to retrieve a users subscriptions (accepts xPerson via GET)
  • 1868: Bug - More than 5 API calls per minute under a single account would fail
  • 1888: Bug - Fixed problem with error due to unset timezone
  • 1892: Bug - Forum topics could fail to be created on SQL Server due to topic string length
  • 1893: Bug - Javascript reference error on login screen

42. Version 3.0.6 Beta

3.0.6 Changes

  • 1846: Feature - Live Lookup can now accept a label="" attribute on tags to set a custom title
  • 1849: Bug - Knowledge books could fail to insert an image path
  • 1850: Bug - PHP defaulting to output compression could cause CSS display errors
  • 1761: Bug - Calendar fields can now be updated and also reset to empty
  • 1841: Bug - Users could select themselves to forward to when out of office
  • 1842: Bug - Reporting tags could fail to be set by triggers and other automation
  • 1844: Bug - Time tracker didn't display on new request screen

43. Version 3.0.5 Beta

3.0.5 Changes

  • 1788: Feature - New preference to move to next request in a filter/queue on close
  • 1820: Feature - Inbox Zero "enhancements" (inspired by HS customer http://figure53.com)
  • 1830: Feature - Modified login system to only allow 5 attempts per minute per account
  • 1783: Feature - Added option to show results by hours & minutes in first response speed report
  • 1790: Bug - Made further adjustments for Google Pagespeed
  • 1803: Bug - Fixed counts in mobile UI
  • 1804: Bug - Fixed sidebar search for customer ID
  • 1805: Bug - SMTP error text showed in wrong location
  • 1806: Bug - Deleting spam in the forums would only delete one spam item at a time
  • 1810: Bug - Fixed re-attaching of attachments from history
  • 1811: Bug - Windows wouldn't list categories in custom fields
  • 1813: Bug - Changed permission groups to remove unnecessary permissions
  • 1817: Bug - Moved timetracker inline on the request screen from the left nav
  • 1821: Bug - Fixed bug where mailboxes using SSL based SMTP overrides (aka gmail) could not send email
  • 1822: Bug - Fixed bugs with special characters in reports
  • 1823: Bug - Fixed file downloads on KB pages in admin
  • 1824: Bug - IE CSS portal template would not be served for grey and blue portal themes
  • 1828: Bug - Added check for source file permissions that are too open
  • 1834: Bug - Todayboard categories chart only counted open requests instead of all
  • 1836: Bug - Batch responding now warns if closing without setting status
  • 1837: Bug - Modified HTML to allow browser autocomplete on custom fields
  • 1666: Bug - Adjusted Live Lookup results display
  • 1713: Bug - Fixed overlay min width
  • 1729: Bug - getHelpfulPages template call did not work correctly in secondary portals
  • 1758: Bug - Reporting tags now stay in place when selected rather than resorting to the top
  • 1768: Bug - Global setting to prevent batch closing caused reassignment batch button to break
  • 1769: Bug - Contact via trigger option would failed
  • 1771: Bug - Fixed various IE javascript errors
  • 1778: Bug - Fixed IE9 bug where javascript was broken when in IE7/8 compatibility mode
  • 1781: Bug - Fixed CSS when in maintenance mode
  • 1785: Bug - Fixed IE8 but where portals would not show in admin drop down list
  • 1786: Bug - Fixed UI so that it's possible to subscribe to a request that already has subscribers

44. Version 3.0.4 Beta

3.0.4 Changes

  • 1734: Feature - Added support for both displaying and inserting images inline in HTML emails
  • 1756: Feature - Added a spam whitelist and blacklist
  • 1751: Bug - Letter case of a mailbox reply to could cause it to CC itself on requests
  • 1752: Bug - Widget success page could fail to load
  • 1665: Bug - Next/Back buttons did not work in the Inbox view
  • 1669: Bug - On MySQL merges could fail
  • 1673: Bug - Response search on request screen javascript error
  • 1674: Bug - Added today and same day last week request count totals on Todayboard
  • 1677: Bug - Improved CSS/JS caching. Added compatibility fix for Google Pagespeed
  • 1678: Bug - Forward command failed to re-attach attachments
  • 1684: Bug - Adjusted time element of calendars to change in 1 minute increments
  • 1685: Bug - Admins now have access to edit any knowledge book settings
  • 1687: Bug - Improved IMAP error logging
  • 1689: Bug - Keyboard shortcut details link failed in Chrome
  • 1691: Bug - Staff search did not search inactive users
  • 1692: Bug - LDAP connection test could report "Error: Success"
  • 1693: Bug - Restored missing image edit.gif
  • 1696: Bug - Batch update and closed failed to close requests
  • 1697: Bug - Improved display of CC/BCC email addresses on request screen
  • 1698: Bug - Custom theme JS embedded with wrong link type
  • 1699: Bug - Stopped the encoders from encoding the /custom_pages example script
  • 1704: Bug - Forum main page now includes user icons for faster identification
  • 1705: Bug - Fixed Live Lookup calls from the address book
  • 1709: Bug - Some links in the KB breadcrumb trail were broken
  • 1714: Bug - Fixed spelling errors
  • 1716: Bug - Removed unneeded language file strings (removed hundreds of old v2 strings)
  • 1717: Bug - Widget could submit tags in note body
  • 1720: Bug - Prevent auto refresh of workspace from leaving blank grid
  • 1725: Bug - Removed the open password option from login page
  • 1729: Bug - getHelpfulPages template call did not work correctly in secondary portals
  • 1730: Bug - Adding a note to another staffers request could cause an empty message body error

45. Version 3.0.3 Beta

3.0.3 Changes

  • 1644: Feature - Added ability to link to chapters from KB popup
  • 1658: Feature - Added ability to save changes to an existing saved report
  • 1664: Bug - Long reporting tags would break tag display
  • 1643: Bug - In some cases the reminders UI would render incorrectly making it impossible to delete reminders.
  • 1645: Bug - FireFox had some excess space at the top of the request screen
  • 1646: Bug - When creating a response the custom field tab could cause errors if the installation has no custom fields
  • 1648: Bug - Updating personal preferences could cause signatures to lose leading line breaks
  • 1650: Bug - Fixed a Postgres specific database error
  • 1651: Bug - Applying a response without a category would unset any currently set category (and hide assignment, tags, etc)
  • 1652: Bug - WYSIWYG on installations with MBString could show odd characters
  • 1653: Bug - When viewing a request the last viewed filter is now correctly highlighted
  • 1655: Bug - imezone may not be set in the installer in some cases

46. Version 3.0.2 Beta

3.0.2: Bugs

  • 1636: Bug - Removed @ check in mailbox passwords
  • 1637: Bug - Live refresh not populating counts/grid correctly
  • 1638: Bug - Reply Above not inserted correctly in auto replies
  • 1639: Bug - Installation failed on MySQL 5.5+
  • 1640: Bug - WYSIWYG could fail to load in some cases
  • 1642: Bug - Dates in reminders could not be set properly

47. Version 3.0.1 Beta

For more information and screenshots of new features visit our What's New page.

3.0.1: Feature Highlights

  • All new design, rebuilt from the ground up to be instantly familiar yet remarkable.
  • New and redesigned reports
  • Todayboard, our new dashboard giving you insights into what's going on today in the system.
  • Stream View. Peek into requests in any filter without excessive clicks and loading.
  • Triggers are a new way to automate HelpSpot in real time.
  • Knowledge Tags, tag your books and forum topics for easier searching and reference.
  • Clean printing gives you clean printed output from any page in the system.
  • Admin themes. Create custom themes for the admin and even hook in custom javascript.
  • Portal themes. 2 new great portal themes to use right out of the box.
  • Integrated "reply above" for emails reduces database size by 50% and in many cases more
  • Improved performance, including faster filters, faster page rending, better caching and more

48. Version 3.0.1 - Template Changes

This page describes the changes to each HelpSpot portal template. If you have an HTML editor available like Dreamweaver or BBEdit it is probably more efficient to simple use the diff tools to compare your edited documents (/custom_templates) with the new templates (/helpspot/templates/). If those tools are not available, the listings below will allow you to manually change the templates.

These changes are only needed if you have customized your portal and specifically customized the files listed below. If not, you do not need to make any adjustments.

Your portal will not work correctly until these changes have been made.

Note: If you're upgrading from versions prior to 2.6.0 (2.4.2,2.1.1,2.1.0) you will also need to apply the previous template changes as well.

These templates have changed in version 3:

  • css.tpl.php
  • forums.posts.tpl.php
  • forums.topics.tpl.php
  • header.tpl.php
  • home.tpl.php
  • index.tpl.php
  • js.tpl.php
  • kb.page.tpl.php
  • request.check.tpl.php
  • search.tpl.php
  • searchbox.tpl.php

css.tpl.php

Modified line 16, changed URL. Line should be:

header('Content-type: text/css'); header('Content-Disposition: inline; filename="style.css"'); ?> /* Import styles for calendar used in date/datetime custom fields */
@import "<?php echo $this->cf_primaryurl ?>/static_<?php echo $this->cf_version ?>/js/jscal2/css/jscal2.css";

Add to end of file:

.calendar_input{
	padding-right: 10px;
	padding-top: 5px;
	padding-bottom: 5px;
	position: relative;
	text-align:	bottom;
	cursor: pointer;
	padding-left: 34px;
	border: 1px solid #BBBBBB;
}

.calendar_btn{
	position: absolute;
	top: 1px;
	left: 2px;
	height: 24px;
	width: 24px;
	background: transparent url(<?php echo $this->cf_primaryurl ?>/portal/images/calendar.png) no-repeat left top;
}

.tag-block-home{
	
}

.tag-block-page{
	margin: 0px;
	padding-left: 42px;
}

.tag-block a{
	display: inline-block;
	height: 26px;
	line-height: 26px;
}

.tag-sep{
	font-size: 11px;
	color: #ccc;
}

.tag-table{
    font-size: 13px;
    width: 100%;
    margin: 15px 0 20px 0;
 	border-bottom: 1px solid #DADADA;
}

.tag-table td { 
	padding: 8px; /* not for grey design */		
}

.tag-header{
	margin-bottom: 30px;
}

#helpspot-link{
	font-size: 12px;
}

footer.tpl.php

Replace line 25 through end of file. Previously line 25 started with a <strong> tag. Should now be:

</div> <!-- End of footer div -->
</div> <!-- End of container div -->

<div id="helpspot-link">
	<?php
	/*
	You may remove this link, however we would be very appreciative if you didn't! Helping spread the word about HelpSpot
	creates a stronger community and a better product for all our customers. 
	Sincerely, 
	
	Ian Landsman 
	President, UserScape
	ian@userscape.com
	*/
	?>
	
	<strong><a href="http://www.helpspot.com">Help Desk Software</a> by HelpSpot</strong>
</div>
</body>
</html>

forums.posts.tpl.php

Add at line 61:

<?php if($this->splugin('Forums_PostTags','count',$this->get_id)): ?>
	<fieldset class="fieldset">
		<legend><b><?php echo lg_portal_tags ?></b></legend>
		<div class="tag-block tag-block-page">
			<?php foreach($this->splugin('Forums_PostTags','getTags',$this->get_id) AS $tags): ?>
				<a href="index.php?pg=tag.search&id=<?php echo $tags['xTag'] ?>">
					<?php echo $tags['sTag'] ?>
				</a> <span class="tag-sep"> / </span>
			<?php endforeach; ?>
		</div>
	</fieldset>
<br />
<?php endif; ?>

<?php if(!$this->helper->isTopicClosed($this->topic,$this->forum)): ?> <form action="index.php?pg=forums.posts&id=<?php echo $this->get_id ?>" method="post">

header.tpl.php

Replaced line 9 (meta robots tag) with:

<meta name="description" content="<?php echo $this->hd_name ?> - help desk and customer service portal" />
<?php if($this->get_page == 'request.check'): ?>
	<meta name="robots" content="noindex, nofollow">
<?php else: ?>
	<meta name="robots" content="index, follow">
<?php endif; ?>

<title><?php echo $this->pg_title ?></title>

Modified line 18, changed URL. Line should be:

<!--stylesheets-->
<link rel="stylesheet" type="text/css"  href="<?php echo $this->cf_url ?>/index.php?pg=<?php echo $this->hd_theme ?>" media="screen, projection" />

Modified & Added at line 18, changed URL & added IE stylesheet. Line should be:

<!--stylesheets-->
<link rel="stylesheet" type="text/css" href="<?php echo $this->cf_url ?>/index.php?pg=<?php echo $this->hd_theme ?>" media="screen, projection" />
<!--[if lt IE 8]>
	<link rel="stylesheet" type="text/css" href="<?php echo $this->cf_url ?>/index.php?pg=<?php echo $this->hd_theme_ie ?>" />
<![endif]-->

Modified line 23, added class attribute. Line should be:

</head>
<body onload="<?php echo $this->pg_onload ?>" class="page-<?php echo $this->get_page_css_class ?>">

home.tpl.php

Added at line 30:

><?php endif; ?>
<?php $this->helper->reset_altrow(); ?>

<?php if($this->splugin('Tags','count') > 0): //Only show tags if there are any ?>
	<table width="555" cellspacing="0" class="forumtable tag-cloud-homepage">
	<tr>
		<td>
			<h2><?php echo lg_portal_tags ?></h2>	<br />
		</td>
	</tr>
	<tr>
		<td class="tag-cloud-td">
			<div class="tag-block tag-block-home">
			<?php foreach($this->splugin('Tags','getCloud') AS $tag): ?>
				<a href="index.php?pg=tag.search&id=<?php echo $tag['xTag'] ?>"  style="font-size:<?php echo $tag['font-size'] ?>%;"><?php echo $tag['sTag'] ?></a> <span class="tag-sep"> / </span> 
			<?php endforeach; ?>
			</div>
		</td>
	</tr>
	</table>
<?php endif; ?>

<?php if($this->splugin('Forums_LatestTopics','count') > 0): //Only show most recent forum posts if there are any ?>

Modified line 44 added class name. Line should be:

<td align="right" class="forum-name">

Added at line 71:

<?php endif; ?>
<?php $this->helper->reset_altrow(); ?>

<?php if($this->splugin('KB_HelpfulPages','count') > 0): //Only show most helpful pages if there are any ?>

index.tpl.php

Added at line 24:

case "css": include $this->loadTemplate('css.tpl.php'); break;
case "css.grey":
	include $this->loadTemplate('css.grey.tpl.php');
	break;
case "css.blue":
	include $this->loadTemplate('css.blue.tpl.php');
	break;		
case "ie.css":
	include $this->loadTemplate('ie.css.tpl.php');
	break;
case "ie.css.grey":
	include $this->loadTemplate('ie.css.grey.tpl.php');
	break;
case "ie.css.blue":
	include $this->loadTemplate('ie.css.blue.tpl.php');
	break;

Added at line 77:

case "search": include $this->loadTemplate('search.tpl.php'); break;
case "tag.search":
	include $this->loadTemplate('tag.search.tpl.php');
	break;	

js.tpl.php

Replace the document.write at line 24 with:

// jscalendar/calendar-setup.js (used for date custom fields)
document.write('<script type="text/javascript" src="<?php echo $this->cf_primaryurl ?>/static_<?php echo $this->cf_version ?>/js/hs-js-combined-portal.php"></script>');

kb.page.tpl.php

Added at line 30:

<p> <?php echo $this->page['tPage'] ?> </p>

<?php if($this->splugin('KB_PageTags','count',$this->get_id)): ?>
	<fieldset class="fieldset">
		<legend><b><?php echo lg_portal_tags ?></b></legend>
		<div class="tag-block tag-block-page">
			<?php foreach($this->splugin('KB_PageTags','getTags',$this->get_id) AS $tags): ?>
				<a href="index.php?pg=tag.search&id=<?php echo $tags['xTag'] ?>">
					<?php echo $tags['sTag'] ?>
				</a> <span class="tag-sep"> / </span>
			<?php endforeach; ?>
		</div>
	</fieldset>
<br />
<?php endif; ?>

Modified line 37 changed variable. Line should be:

<?php foreach($this->splugin('KB_PageDownloads','getDownloads',$this->get_id) AS $download): ?>
	<li><?php echo $this->helper->mimeimg($download['sFilename']) ?> <a href="index.php?pg=file&from=2&id=<?php echo $download['xDocumentId'] ?>"><?php echo $download['sFilename'] ?></a>
<?php endforeach; ?>

request.check.tpl.php

Modified line 169 added ID. Line should be:

	<input type="text" name="id" value="" size="20" maxlength="100" tabindex="100" />
	<input type="submit" name="submit" id="accesskey-btn" value="<?php echo lg_portal_check ?>" tabindex="101" />
</p>

Added at line 197:

<?php if(isset($_GET['reset_password'])): ?>
<script type="text/javascript">
document.observe("dom:loaded", function(){
	var page_href = location.href + " ";
	if(page_href.search(/password/i) > 0){
		$("feedback_box").show();
		$("feedback_box").addClassName("feedback_box_positive");
		$("feedback_box").update("<?php echo htmlentities(lg_portal_password_reset) ?>");
	}
});
</script>
<?php endif; ?>
	
<?php include $this->loadTemplate('footer.tpl.php'); ?>

search.tpl.php

Added at line 19:

<?php include $this->loadTemplate('searchbox.tpl.php'); ?>

<?php if($this->splugin('Tags','searchCount',$this->get_q)): ?>
	<fieldset class="fieldset">
		<legend><b><?php echo lg_portal_searchtags ?></b></legend>
		<div class="tag-block tag-block-page">
			<?php foreach($this->splugin('Tags','searchTags',$this->get_q) AS $tags): ?>
				<a href="index.php?pg=tag.search&id=<?php echo $tags['xTag'] ?>">
					<?php echo $tags['sTag'] ?>
				</a> <span class="tag-sep"> / </span>
			<?php endforeach; ?>
		</div>
	</fieldset>
<br />
<?php endif; ?>

searchbox.tpl.php

Modified line 6 added ID. Line should be:

<p align="center">
	<input type="text" name="q" id="q" value="<?php echo $this->get_q ?>"> 

49. Version 2.7.2

2.7.2: Features and Bugs

  • 1423: Feature - Added support for line breaks in widget text
  • 1457: Feature - Added xPortal ID option to create.request and private.create.request
  • 1459: Feature - Added mailbox account name placeholder for last, first
  • 1468: Feature - Upgraded TinyMCE (wysiwyg editor) to 3.3.8
  • 1474: Feature - Replaced the last customer email tag with last customer note (your templates will automatically be updated). This now replies with the last note of any type not just emails, so portal updates, API generated updates, etc.
  • 1479: Feature - Added reportingTags parameter to private.request.search
  • 1484: Feature - Added 2 indexes to HS_Request to improve speed on certain filter conditions
  • 1478: Bug - On Windows the Black Box Username field could default to a blank space instead of empty
  • 1470: Bug - Prevented an unneeded update query in the Workspace
  • 1465: Bug - UTF8 control characters in an email could break API XML
  • 1467: Bug - Updating global email templates could overwrite custom mailbox templates
  • 1448: Bug - Numerci and Decimal custom fields did not accept 0 on the portal form
  • 1451: Bug - KB Pages with only table tags would have
    added to them
  • 1452: Bug - Required checkbox fields now checked via javascript as other required fields are
  • 1453: Bug - Auto response email template could not correctly display CSS
  • 1455: Bug - Could not download a report as CSV where open/closed was set to closed
  • 1336: Bug - Push requests could not be logged when using Postgres DB
  • 1337: Bug - Postgres DB installations wouldn't list request history on portal when using customer ID display option
  • 1342: Bug - Drill down lists could not be edited if they contained certain special characters
  • 1348: Bug - Speed to first response report can sometimes count merged requests as negative values
  • 1349: Bug - The email_staff parameter in private.request.create did not work as expected
  • 1359: Bug - Batch request could fail on pasted text with bad characters

50. Version 2.7.1

2.7.1: Features and Bugs

  • 1386: Feature - Improved filter caching for faster results especially in large installations.
  • 1386: Change - Removed filter cache time setting, still available as a hidden setting.
  • 1394: Feature - Improved search tab UI. Enter starts search, last search remembered for configurable period of time in hidden settings (defaults to 20 minutes)
  • 1409: Feature - Added exclusive public history notes email tag (will show all public notes in the request besides the current one being sent) to compliment "inclusive" one
  • 1398: Bug - API private.request.addTimeEvent allowed adding time events to non-existent request ID's
  • 1387: Bug - Address Book A-Z navigation could break under some conditions.
  • 1342: Bug - Drill down lists could fail to be editable.
  • 1348: Bug - Improved the speed to first response reports handling of merged requests.
  • 1349: Bug - email_staff API parameter did not email staff members indicated.
  • 1372: Bug - Speed to first response report had problems when downloading as a CSV.
  • 1417: Bug - Subject lines that end in \ break the javascript on the request page
  • 1420: Bug - calendar date selection could fail in advanced search

51. Version 2.7.0

For screenshots of several new features visit our What's New page.

2.7.0: Feature Highlights

  • 108: Feature - Global BCC option, so all public note emails (optionally all outbound email) can be BCC'd to a specified address.
  • 1128: Feature - New advanced search interface with optional filter creation
  • 1108: Feature - New report: Speed to first response
  • 1139: Feature - New tab widget allows a question/feedback form to easily be added to any webpage or site
  • 1240: Feature - Added email tag which will insert the complete public history of a request
  • 1297: Feature - Added ability to re-attach an attachment in the request history
  • 604: Feature - Added a simple address book for commonly used email addresses. Integrated with Live Lookup for global address book functionality.
  • 1310: Feature - Added assignment chain management. It's now possible to search/filter the full history of all users who have ever been assigned a request (works going forward after upgrade).

2.7.0: Features and Bugs

  • 121: Feature - When doing a batch response any people currently CC'd will be CC'd on the batch reply
  • 1074: Feature - Improved image caching
  • 1123: Feature - Framed portal pages would work inconsistently in some IE versions
  • 1124: Feature - Added US Cellular and Telstra to SMS list
  • 1126: Feature - Responses are no longer required to have a note
  • 1131: Feature - Responses can now set "send from" and "TO"
  • 1109: Feature - Filter/Report exporting now done in CSV for wider compatibility
  • 1157: Feature - Improved request history search speed
  • 1145: Feature - API method private.request.search can now search on xPersonAssignedTo
  • 1187: Feature - "Currently Viewing" notification on request screen now less obtrusive, continually viewable and updates in real time
  • 1208: Feature - Live Lookup now passes the request ID in it's call
  • 1221: Feature - Added ability to set the contact type via the API creation methods
  • 1251: Feature - Added button to clear error table
  • 1252: Feature - Added check for shell_exec when using command line Live Lookup
  • 1194: Feature - Added ability to repair MySQL tables from the system information screen
  • 1296: Feature - Each request history item now has a "forward" command which will quote the note, set the subject, and re-attach any files in the note
  • 503: Bug - Changed wysiwyg to use raw encoding to true characters are stored in database
  • 1080: Bug - HTML tags not stripped from RSS titles
  • 1088: Bug - Removed inactive users from time tracker selection list
  • 1092: Bug - Fixed bug where IE7 users could sometimes not take an urgent request from the Inbox
  • 1101: Bug - Numeric custom fields would log changes from/to nothing
  • 1104: Bug - When uploading multiple attachments via the api, ones beyond the first would not upload correctly
  • 1159: Bug - Added logic to prevent workspace from stretching on long strings of characters
  • 1163: Bug - Fixed email_staff option in API which would not email selected staff
  • 1166: Bug - An apostrophe as the leading character of a customer name would cause the request not to update
  • 1170: Bug - Improved email validation
  • 1171: Bug - Portal black box now creates accounts for unknown but valid users as the default system does
  • 1175: Bug - When using the option to write attachments to disk the process would sometimes failover to DB when it shouldn't
  • 1142: Bug - Removed encoded HTML characters from text staff notification emails
  • 1143: Bug - Drill down custom field data was not available in API results
  • 1119: Bug - Using make note public on an HTML email could break the layout of the request.
  • 1113: Bug - The request push details link did not work on closed requests
  • 1114: Bug - Responses would be erased in some browsers if enter was hit directly after insertion
  • 1276: Bug - Prevent email ID prefix from containing anything but letters
  • 1286: Bug - View request link in emails could have wrong URL
  • 1292: Bug - Email table of results rule action in some cases may not remember the correct person to email
  • 1243: Bug - Increased size of the sReplyName field
  • 1257: Bug - Fixed wrong path to attachment images in secondary portals
  • 1262: Bug - Clarified notes on MSSQL wild card searches
  • 1263: Bug - Private api method private.request.create could not add reporting tags
  • 1223: Bug - Mail rules would not always match subject lines properly if they were encoded
  • 1229: Bug - Remove currently out of office users from list of those who can be set as a person to forward to while out of office.
  • 1231: Bug - "additional" hidden portal form field would not submit text in some configurations
  • 1237: Bug - Added check to ensure at least 1 staff member is added to a category
  • 1211: Bug - The date opened placeholder did not show the correct date, it showed the current date.
  • 1213: Bug - Command clicking a request ID would not open it in a new window
  • 1190: Bug - Long lists of reporting tags would sometimes fail to reorder correctly
  • 1146: Bug - Print view shows custom fields which are not part of the requests currently selected category.
  • 1148: Bug - Fixed issue with special characters in drill down fields
  • 1152: Bug - Add check to make sure the SMS field is filled in if checking off SMS notification options
  • 1156: Bug - Installs with many custom fields could not fully use Live Lookup due to the use of GET to transmit the information, switched to POST
  • 1321: Bug - Private api method private.request.getCategories returned all reporting tags for each category
  • 1314: Bug - Clicking update and close in Google Chrome Mac crashes if status is not already selected
  • 1315: Bug - Secondary portal forums send emails from the default system account instead of the secondary portals selected account.
  • 1304: Bug - IE could receive a blocking javascript error on Rules pages

52. Version 2.6.3

  • 1024: Feature - Installer.php now does additional checks for proper database permissions and errors during upgrades
  • 1025: Feature - kb.getBookTOC and kb.getPage now return information on related pages.
  • 1033: Feature - Installer.php now automatically puts the system in maintenance mode when doing an upgrade (after upgrade button pushed) and turns off maintenance mode when complete
  • 1050: Feature - The email tag ##forward:true## is now accepted in the body of the message as well as the subject line
  • 1052: Feature - The request history option menu now stays open longer
  • 1058: Feature - Added a button to clear stuck emails allowing the system to retry downloading them
  • 1060: Feature - Added cHD_TAKEIT_DOCHECK hidden setting to allow Take It button to bypass assigned to check and directly assign to clicker
  • 1013: Bug - New Level 2 users could be created and defaulted to a filter they didn't have access to in some configurations
  • 1014: Bug - IE sometimes shows browser security warning on admin page
  • 1015: Bug - In some cases Windows Installer did not correctly set the tmp directory to writable causing email attachments to fail
  • 1020: Bug - IE could show an "out of memory" browser error on preferences page
  • 1021: Bug - Closed requests had a javascript error in IE
  • 1022: Bug - private.request.get now returns the merged request if the request has been merged
  • 1032: Bug - HTML H2 tags did not display correctly in preview mode
  • 1036: Bug - Force table locking in MySQL when doing merges to prevent a situation where both requests in a merge if called simultaneously to merge into each other could be deleted
  • 1038: Bug - Closed requests showed request history based on "notes" preference so would show notes only if that preference was set. Now shows all history items regardless of setting.
  • 1039: Bug - Drill down data in filter grid did not display properly in all cases
  • 1044: Bug - Windows installer could fail to install the Zend Optimizer for new installations in some cases
  • 1053: Bug - Malformed email can cause only the first line or two of an email to be displayed
  • 1055: Bug - Fixed rare bug where if the database has an error two new requests could be merged into one
  • 1056: Bug - Fixed issues with custom field creation when database user does not have alter permissions in MySQL

53. Version 2.6.2

  • 1011: Bug - "Customer will not be emailed" message and note draft saving may not function properly on the request screen. "Customer will not be emailed" may fail to correctly switch to "Customer will be emailed" when appropriate causing confusion to help desk staff. 
    This bug only affects HelpSpot version 2.6.1.

54. Version 2.6.1

  • 968: Feature - Added hidden setting to disable auto linking of shortcuts (r: f: k:) in note field
  • 973: Feature - Hidden setting to set a maximum image size to attempt to thumbnail in the request history
  • 981: Feature - Option to open request history search results in a new window
  • 984: Feature - Added a reporting tags column for filters
  • 990: Feature - Phone numbers in the iPhone UI are now clickable in the customer information area
  • 957: Bug - Merging generates an email to user doing the merge even if it's same person
  • 970: Bug - Clicking update request now auto submits time if time clock is running
  • 974: Bug - Installations running over SSL can show insecure items error when accessing request page
  • 975: Bug - Formatted text box and plain text note box would not auto resize
  • 982: Bug - Spellchecking with the wysiwyg enabled did not work
  • 991: Bug - iPhone UI is now faster due to removal of transitions
  • 992: Bug - iPhone UI now correctly links to knowledge book pages
  • 993: Bug - Editing an automation rule can cause an "operation aborted" error in IE
  • 999: Bug - Workspace quick menu sometimes would remain stuck on "loading..." while trying to view request details
  • 1000: Bug - Fix improperly decoded attachment extensions
  • 1001: Bug - Setting a note to public via a response and attempting to set the subject line and CC fails
  • 1002: Bug - Certain filter conditions if used on their own may incorrectly return all requests if no requests match the condition

55. Version 2.6.0

For screenshots of several new features visit our What's New page.

2.6.0: Feature Highlights

  • 56: Feature - Smart assignment. When re-assigning a request to a category the staffer is part of the assigned to box will default to the staffer rather than the default user.
  • 384: Feature - Multilevel response grouping
  • 417: Feature - Live request access status. Staff are warned when entering a request another user is viewing or editing.
  • 428: Feature - Request histories can now display a full history, just notes, just public notes, or files. The setting is saved until it is changed by the staffer (setting is unique to each user)
  • 607: Feature - Significant filter speed improvements. Especially for reporting tags and full text searches on the MySQL database
  • 633: Feature - Integrated iPhone interface
  • 768: Feature - Filter view request quick menu for viewing request history from the Workspace
  • 753: Feature - Added indicator to visually confirm when an email will be sent to a customer on the request screen
  • 787: Feature - Specific column widths can now be specified in filters
  • 823: Feature - Added support for reCAPTCHA as a captcha type in the portal
  • 869: Feature - Per mailbox public and external note email templates for easy support of different mailbox domains.
  • 871: Feature - Filter counts are now cached for 5 minutes by default (setting in Admin->Settings->System). Caching dramatically reduces the number of queries per page in filter heavy installations.
  • 928: Feature - Multi-portal support. Create unlimited portals for different websites all managed by one HelpSpot instance.

2.6.0: Features and Bugs

  • 164: Feature - Option to quote all public history
  • 566: Feature - Forwarded email parsing now requires the subject line to contain a special command: ##forward:true##
  • 568: Feature - Added "van:" as another "from" to search for in email forward parser
  • 585: Feature - Option to show the SQL of a filter on the filter creation/edit screen
  • 615: Feature - Default the create filter batch option to unchecked
  • 628: Feature - API: allow override of fNoteIsHTML
  • 665: Feature - Request Push API: Assigned user and logged in user information sent. Live Lookup API: logged in user information sent with api call.
  • 668: Feature - Mailbox option to use a staff member name in the from emails of public notes instead of generic mailbox name
  • 645: Feature - Pass fUserType value in Live Lookup API so results returned can be tailored to user level
  • 678: Feature - Added notification suppression option to automation rules
  • 679: Feature - Added email template placeholders for opened date and current time
  • 687: Feature - Move to inbox option for automation rules
  • 700: Feature - Added setting to turn off auto reply on portal form requests
  • 701: Feature - New filter column which displays who's currently viewing/editing a request
  • 716: Feature - Filter "take it" column now works like the built in inbox "take it" column
  • 722: Feature - Add an "is not spam" action to mail rules
  • 727: Feature - Upgraded wysiwyg to latest version
  • 728: Feature - Show count of currently open requests for a customer on the request screen
  • 732: Feature - Added ability to merge a request from the history tab
  • 734: Feature - Added logged in user placeholders
  • 741: Feature - Automation rule option to only run rule if it's directly called, not when tasks2.php is called without an ID (as normal)
  • 758: Feature - New API method of private.request.merge
  • 760: Feature - Added option to group merge from filters
  • 766: Feature - Save As option for responses and filters to quickly base a new response/filter off of an existing one
  • 767: Feature - Links in the request history to external sites now open in a window without leaving the request screen
  • 779: Feature - Menu option to link directly to a specific request history note
  • 781: Feature - API: private.request.search now accepts date parameters
  • 785: Feature - Added "active" status to "change status" drop down in filters
  • 786: Feature - Filters now have the option for grouped and/or conditions
  • 796: Feature - Option to convert a request history item into a new request
  • 812: Feature - Added a Request Push API action to automation rules
  • 817: Feature - Added hidden config.php setting which allows SSL MySQL connections
  • 819: Feature - When clicking "update and close" with the status still "active" a quick popup will appear allowing a status selection without the need to scroll.
  • 864: Feature - Added Getting Started menu
  • 897: Feature - Significant improvements in client CPU and Memory utilization in all browsers
  • 902: Feature - Added xPersonOpenedBy to private.request.create
  • 931: Feature - Email table of results will no longer send an email if no requests match the rule
  • 933: Feature - Added ability to move chapters between books
  • 828: Bug - Adding a mailbox incorrectly showed an "edited" message
  • 821: Bug - Flash movies uploaded into the knowledge books may not display correctly for visitors using Flash 10
  • 806: Bug - Editing a KB name or description causes order to be set to 0
  • 808: Bug - Remove formatted text (Markdown) escape characters from text versions of emails
  • 809: Bug - Leave attached .eml files as attachments instead of parsing them as part of the mail body
  • 792: Bug - Add tag button in Safari submits form when it should not
  • 783: Bug - Portal requests show a RE in excel download of filters when they should not
  • 747: Bug - Line breaks are now stripped from drill down option lists
  • 748: Bug - The batch request form no longer forces required custom fields to be changed
  • 750: Bug - Spaces at the end of an email address cause emails to fail
  • 752: Bug - tasks2.php no longer outputs any text
  • 739: Bug - Creating a request with no note causes odd character dump in request history
  • 713: Bug - Private API returns a basic auth header in addition to the xml failure notice
  • 714: Bug - Formatted text content now used directly for text part of emails
  • 723: Bug - Internet Explorer would append responses to top of screen instead of the note box in some instances
  • 724: Bug - A login box appears in the draft save area of the request screen if the user is logged out while working a request
  • 703: Bug - Mail rule headers now default to "contain" instead of "is"
  • 706: Bug - Search fields now trim whitespace
  • 711: Bug - Safari could not set public api return values in settings
  • 680: Bug - When choosing a relative comparison operator in an automation rule the time field would not hide
  • 647: Bug - kb.getToc now wraps pages with a pages tag for easier parsing (existing code that uses this method may need updating)
  • 669: Bug - Multi-word searching in Postgres would not return results
  • 671: Bug - Improperly formatted email messages caused attachments to not be imported properly
  • 677: Bug - On some configurations files with no mimetypes would not be saved to the database
  • 635: Bug - Custom field dates in automation rules show timestamp
  • 639: Bug - private.request.search does not return tnote
  • 629: Bug - Subject line shows on non-email created requests
  • 631: Bug - Black Box Portal authentication may not work in some cases
  • 618: Bug - Umlaut in subject line forces requests to always be created, never appended to existing
  • 619: Bug - Original Note tag will send back a private note on a manually entered request with the first note as a private note
  • 623: Bug - Files could not be uploaded via request.update method
  • 624: Bug - Group files in request.get into a tag for easier parsing
  • 627: Bug - Certain emails become stuck due to spam check
  • 586: Bug - Change filter condition so that both checked and unchecked can be found
  • 600: Bug - Apostrophe in knowledge book page title makes them not insertable into note box
  • 582: Bug - Reporting tags don't show when editing a response on IE
  • 584: Bug - Emails with multiple CC's can stretch page
  • 567: Bug - First result of Live Lookup result with multiple entries sometimes not shown
  • 173: Bug - Space character can get through on a CC and breaks javascript
  • 564: Bug - Email template tags don't insert in FireFox 3
  • 878: Bug - Borders added to images in the knowledge books would not be displayed
  • 879: Bug - Login check did not work for new request screen
  • 939: Bug - Downloads over SSL on request check page fail to IE
  • 955: Bug - Request Push to SQL Server 2008 fails when Push() does not return a value

56. Version 2.6.0 - Template Changes

This page describes the changes to each HelpSpot portal template. If you have an HTML editor available like Dreamweaver or BBEdit it is probably more efficient to simple use the diff tools to compare your edited documents (/custom_templates) with the new templates (/helpspot/templates/). If those tools are not available, the listings below will allow you to manually change the templates.

These changes are only needed if you have customized your portal and specifically customized the files listed below. If not, you do not need to make any adjustments.

Your portal will not work correctly until these changes have been made.

Note: If you're upgrading from versions prior to 2.4.2 (2.1.1,2.1.0) you will also need to apply the template changes here.

These templates have changed in version 2.6:

  • css.tpl.php
  • email.tpl.php
  • forums.posts.tpl.php
  • forums.topics.tpl.php
  • js.tpl.php
  • request.tpl.php

css.tpl.php

Modified line 16, changed URL. Line should be:

header('Content-type: text/css');
header('Content-Disposition: inline; filename="style.css"');
?>
/* Import styles for calendar used in date/datetime custom fields */
@import "<?php echo $this->cf_primaryurl ?>/js/jscalendar/skins/aqua/theme.css";

Modified line 226, changed URL. Line should be:

.navBar a:link.navOn, .navBar a:visited.navOn, .navBar a:hover.navOn
{
	font-weight: bold;
	padding: 0 0 6px 10px;
	text-decoration: none;
	color: #39399c;
	background: url(<?php echo $this->cf_primaryurl ?>/portal/images/blue-tri.gif) no-repeat left top;
}

Modified line 270, changed URL. Line should be:

.subnavBar a:link.navOff, .subnavBar a:visited.navOff
{
	font-weight: normal;
	padding: 0 0 6px 10px; 
	text-decoration: none;
	color: #3163ce;
	background: url(<?php echo $this->cf_primaryurl ?>/portal/images/blue-dot.gif) no-repeat left top;
}

Modified line 279, changed URL. Line should be:

.subnavBar a:hover.navOff
{
	font-weight: normal;
	padding: 0 0 6px 10px; 
	text-decoration: underline;
	color: #39399c;
	background: url(<?php echo $this->cf_primaryurl ?>/portal/images/blue-dot.gif) no-repeat left top;
}

Modified line 288, changed URL. Line should be:

.subnavBar a:link.navOn, .subnavBar a:visited.navOn, .subnavBar a:hover.navOn
{
	font-weight: bold;
	padding: 0 0 6px 10px; 
	text-decoration: none;
	color: #39399c;
	background: url(<?php echo $this->cf_primaryurl ?>/portal/images/blue-tri.gif) no-repeat left top;
}

email.tpl.php

Replaced lines 45-52 for new captcha include, should now be:

//Captcha form protection. You can turn this on and off via a setting in Admin->Settings->System Security. It's enabled by default 
//This text captcha should be sufficient for most automated spam. If someone has modified a robot to target your site specifically 
//then obfuscating the word via javascript or using an image may improve results ?>
<?php include $this->loadTemplate('captcha.tpl.php'); ?>

<div class="formbuttondiv">

forums.posts.tpl.php

Replaced lines 89-96 for new captcha include, should now be:

		//Captcha form protection. You can turn this on and off via a setting in Admin->Settings->System Security. It's enabled by default 
		//This text captcha should be sufficient for most automated spam. If someone has modified a robot to target your site specifically 
		//then obfuscating the word via javascript or using an image may improve results ?>
		<?php include $this->loadTemplate('captcha.tpl.php'); ?>

		<p>
			<input type="checkbox" name="fEmailUpdate" value="1" /> <?php echo lg_portal_emailupdate ?>
		</p>

forums.topics.tpl.php

Modified line 29, changed URL. Line should be:

		<?php if($topic['fSticky']): ?>
			<img src="<?php echo $this->cf_primaryurl ?>/images/sticky.gif" align="center" alt="<?php echo lg_portal_sticky ?>" height="16" width="16" />
		<?php endif; ?>

Modified line 54, changed URL. Line should be:

 	<?php if($this->get_start == 0 && $this->hd_forumFeedsEnabled): ?>
 	| <a href="index.php?pg=forums.feed&id=<?php echo $this->get_id ?>"><img src="<?php echo $this->cf_primaryurl ?>/portal/images/rss.gif" alt="" align="center" border="0" /></a>
 	<?php endif; ?>

Replaced lines 92-99 for new captcha include, should now be:

		//Captcha form protection. You can turn this on and off via a setting in Admin->Settings->System Security. It's enabled by default 
		//This text captcha should be sufficient for most automated spam. If someone has modified a robot to target your site specifically 
		//then obfuscating the word via javascript or using an image may improve results ?>
		<?php include $this->loadTemplate('captcha.tpl.php'); ?>

		<p>
			<input type="checkbox" name="fEmailUpdate" value="1" /> <?php echo lg_portal_emailupdate ?>
		</p>

js.tpl.php

Modified line 24, changed URL. Line should be:

// jscalendar/lang/calendar-en.js (used for date custom fields)
// jscalendar/calendar-setup.js (used for date custom fields)
document.write('<script type="text/javascript" src="<?php echo $this->cf_primaryurl ?>/js/c_portaljs_<?php echo $this->cf_version ?>.php"></script>');

request.tpl.php

Modified line 128, change P to a DIV tag. Line should be:

	<div id="<?php echo $fieldID ?>_wrapper" style="<?php echo $visible ?>"><label for="<?php echo $fieldID ?>" class="datalabel<?php echo $requiredClass ?>"><?php echo $field['fieldName'] ?>:</label><br />
		<?php echo $this->helper->showError($fieldID,'<br />') ?>

Modified line 157, change P to a DIV tag. Line should be:

		<?php endif; ?>
	</div>
<?php endforeach; ?>

Modified line 182, added label to simple portal textarea. Line should be:

<?php elseif($this->hd_portalFormFormat == 0): ?>

	<p><label for="simple" class="datalabel"><?php echo lg_portal_req_simple ?>:</label><br />
	<?php echo $this->helper->showError('simple','<br />') ?>
		<textarea name="simple" cols="50" rows="10" style="width:100%;"><?php echo $this->request_simple ?></textarea>
	</p>

Replaced lines 202-209 for new captcha include, should now be:

//Captcha form protection. You can turn this on and off via a setting in Admin->Settings->System Security. It's enabled by default 
//This text captcha should be sufficient for most automated spam. If someone has modified a robot to target your site specifically 
//then obfuscating the word via javascript or using an image may improve results ?>
<?php include $this->loadTemplate('captcha.tpl.php'); ?>

</div>

57. Version 2.4.7

  • 20: Feature - Added setting to turn off spam filtering or to check for spam, but not to train
  • 535: Feature - Attempt to determine proper customer information from an email forwarded into HelpSpot
  • 537: Feature - Improved data compression and cleaning for installations with Tidy
  • 523: Feature - Added URL parameter of ?clearcache which will force the cache system to clear
  • 518: Feature - Added option to save attachments to the file system rather than in the database
  • 520: Bug - Static file caching now stores both a text and gzip version of the files
  • 525: Bug - Fixed API bug where attachments would not attach with private.request.update and private.request.create
  • 533: Bug - When using IIS with SSL some browsers could not download file attachments in the portal
  • 534: Bug - Added a check in the installer to determine if HelpSpot was unzipped properly
  • 542: Bug - Fix email template issue with some templates being blank when upgrading from 1.5.5 to 2.4.x
  • 546: Bug - Changed wording for default mailbox in send from drop down to be more clear
  • 547: Bug - Date custom fields may be off by 1 day on older dates before 1990
  • 552: Bug - Images in knowledge books didn't shown when the domain uses a port other than 80
  • 555: Bug - Hidden email blocks do not work in the portal
  • 497: Bug - Added save draft option for text mode
  • 499: Bug - Added extra checks for empty emails after emails are cleaned. If empty an alternate escaped version is used if possible
  • 502: Bug - Fixed type error in installer.php
  • 504: Bug - Fixed link to documentation on black box setup
  • 512: Bug - Fixed wrapping of customer/history search tabs on 800x600 resolution browsers
  • 513: Bug - wysiwyg incorrectly created inner page anchor tags
  • 514: Bug - Removed xMailboxToSendFrom from customer.getRequests API method
  • 515: Bug - Spam requests are no longer counted in the workload report
  • 516: Bug - Editing preferences causing default workspace to be reseet
  • 554: Bug - Auto refresh causes browser title to be undefined after a refresh in a custom filter

58. Version 2.4.2

2.4.2: Features and Bugs

  • 488: Feature - Added setting for default request history search type
  • 490: Feature - Request history search request ID link is now a standard A tag so it can be opened in a new window/tab by right clicking
  • 492: Bug - RE: is now shown in the email subject line below the note box and it's addition is logged
  • 494: Bug - Custom field values were not being sent to the Live Lookup URL
  • 495: Bug - Ajax custom field would not populate with data after an option was selected
  • 496: Bug - Reminder confirmation window now fits text
  • 473: Bug - Graph showed error in 80/20 report when no reporting tags were found
  • 475: Bug - Escaped version of HTML email is used if purification strips all text.
  • 476: Bug - Added ability to save draft in formatted text mode
  • 477: Bug - Urgent requests did not have the red header as it should be
  • 482: Bug - Javascript caching would not work on PHP 4
  • 483: Bug - Assign the "send from" mailbox as requests enter the system to prevent continuous logging of notes about send from changing
  • 485: Bug - Reminder dialog shows garbled text on PHP 4
  • 486: Bug - Restore draft options doesn't show newest saved drafts until a page refresh. Options are now updated in real time.

 

2.4.0: Feature Highlights

  • 221: Feature - Added a simple portal login that allows customers to see their request history in the request check area. The login only applies to request check, the rest of the portal remains completely open. Access keys are also still in use and remain a viable way to check on the history of a request.
  • 201: Feature - Added grouping ability to filters
  • 211: Feature - Automatic saving of note drafts on request page every 20 seconds. The user may also force a save
  • 181: Feature - When the PHP PECL Mailparse extension is available HelpSpot will use it. This provides up to a 70% improvement in memory usage while importing emails
  • 351: Feature - New round robin auto assignment option for even distribution of requests across staff
  • 129: Feature - Added a Maintenance mode which takes HelpSpot offline. Mail importing will stop, no requests will be accepted via the portal or API
  • 333: Feature - Added checks for stuck emails and when possible import around the stuck email as well as notify admins that an email is stuck.
  • 140: Feature - Added loop protection for new emails. By default more than 10 emails from the same address within one hour will result in no more auto response emails being sent to the address in order to break the loop
  • 177: Feature - Added the ability to set Inbox as the category default
  • 418: Feature - Dramatic speed improvements for filters, especially on large databases (special thanks to Catalyst for their time and assistance on this)
  • 183: Feature - WYSIWYG now supports Safari Browser

 

2.4.0: Other Features and Bug Fixes

  • 284: Feature - Add ability to do secure SMTP connects for outbound email
  • 289: Feature - Added IS/IS NOT filter criteria for predefined custom fields in filters
  • 291: Feature - Added email forgot password option for staff
  • 292: Feature - Added API method for returning requests by a customers portal login email/password
  • 236: Feature - Improved customer history search. Added new search types
  • 244: Feature - Added report for response usage
  • 260: Feature - Added request open/closed placeholder
  • 306: Feature - Allow per mailbox SMTP settings
  • 272: Feature - Added private note and external note to change note types in responses
  • 329: Feature - Added support for multiple Live Lookup endpoints. Allowing Live Lookup calls to multiple URL's
  • 338: Feature - Hide private kb's and global responses when in limited access mode for guests
  • 341: Feature - Added email header information when using the request history quote feature on an email
  • 345: Feature - Added API method for searching time events
  • 347: Feature - Added ability to remove a request from a batch while on the batch screen
  • 348: Feature - Added ability to change status from the quick action menu (workspace)
  • 350: Feature - List the TO in the public note request history
  • 356: Feature - Added ability to set the note body on the request page by passing tBody in via the URL
  • 363: Feature - Added closed after and closed before date options to filters
  • 371: Feature - Modified private.request.create and private.request.update API methods to allow for using importing operations (allow setting of creation date)
  • 429: Feature - Improved javascript and CSS compression and caching
  • 446: Feature - Add more relative date options, past 7/14/30/90/365 days
  • 80: Feature - Added KB helpful/not helpful API methods
  • 111: Feature - Remember "send from" when changed while updating a request
  • 116: Feature - Added option in Windows Installer to use an existing MySQL database if available
  • 114: Feature - Edits to the public note subject line are now logged and saved
  • 154: Feature - New "staff initiated" contacted via type
  • 169: Feature - Added captcha to email post form
  • 175: Feature - Added 60 and 90 day options to remove from trash setting
  • 187: Feature - Added an initial request placeholder
  • 206: Feature - Added keyboard shortcut for create request and ID search box
  • 213: Feature - Added ability to set reporting tags from a response
  • 214: Feature - Added ability to set the BCC from a response
  • 229: Feature - Added ability to add a private note from mail and automation rules
  • 231: Feature - Added more search criteria to the private.request.search API method: open/closed/custom fields/status/category
  • 197: Feature - Added most used menu to response menu
  • 301: Bug - Honor Reply To email/name if available
  • 331: Bug - Show all categories in report drop downs
  • 308: Bug - Request history text sometimes squished on history search
  • 311: Bug - Fixed issue where HTML emails would sometimes be empty after cleaning
  • 315: Bug - When doing an update and close if the email fails the staff are not notified.
  • 322: Bug - private.request.create does not attach files on create
  • 262: Bug &nbsp; shown on data searches in search tab
  • 263: Bug - Default customfield date/times to today
  • 264: Bug - Fix limited access mode for L2 so that only their categories can be seen in a filter
  • 259: Bug - Using ##accesskey## in responses does not insert the access key
  • 238: Bug - No longer build tNote index when using Postgres
  • 298: Bug - Enforce limited access rules on request page
  • 279: Bug - Set default date on calendars to date selected
  • 283: Bug - Changing preferences resets customized columns
  • 439: Bug - Can't export excel on any pages other than the first page of filter results
  • 440: Bug - filters: last public update by doesn't work as expected
  • 416: Bug - Don't allow public note cc/bcc to carry over into external notes
  • 352: Bug - On the portal make sure kb/forum search is not shown if neither is public
  • 354: Bug - Tidy on PHP5 broken on Jan 2008 Tidy build
  • 349: Bug - KB pages with double quotes in title can't be inserted on request page (or forums)
  • 342: Bug - Improve character set parsing of emails
  • 339: Bug - Response breaks if custom field is to be set and has been deleted
  • 334: Bug - remove initial request note from "subject line" options in email templates
  • 335: Bug - Special characters break the outbound text version of HTML emails
  • 337: Bug - Filter counts don't update on auto refresh
  • 198: Bug - Append response menu goes past bottom of screen
  • 222: Bug - Aspell doesn't work on Windows with wysiwyg when there's a space in the file path
  • 223: Bug - Some characters display incorrectly in IE7 due to wrong encoding header
  • 224: Bug - Improve Postgres memory use on large attachment inserts
  • 225: Bug - Adding columns can sometimes add another empty column in safari
  • 215: Bug - Quoting text only returns first line in some installations
  • 203: Bug - Don't turn mailto: urls in emails into absolute url links
  • 185: Bug - HTML entities show in Excel export
  • 178: Bug - Formatted text headers in responses don't work after level 1 header in wysiwyg
  • 179: Bug - Portal template editor broken on some IE7 builds
  • 156: Bug - Fixed issue with drill down custom fields on IIS
  • 161: Bug - Live Lookup overwrites fields that are not returned
  • 165: Bug - Tidy on PHP4 returns 1 instead of note text
  • 166: Bug - Added AT&T to SMS list
  • 167: Bug - Confirm that new licenses cannot be uploaded if they have less users than are currently active in the installation
  • 151: Bug - private.request.getCategories returns only categories marked as public
  • 152: Bug - Strip form tags from any HTML emails
  • 146: Bug - Trim excess characters in new predefined list items
  • 115: Bug - Add option which allows you to turn on Gecko spellchecking for wysiwyg
  • 141: Bug - Loop protection for within a request to prevent overload. Only unique emails will be imported, identical duplicates will be ignored
  • 131: Bug - Long custom fields create horizontal scroll
  • 132: Bug - Special characters in drill down
  • 133: Bug - Add ability to select which website to install to on IIS7 when using Windows Installer
  • 135: Bug - Installer dies when trying to reach a remote database it can't reach
  • 118: Bug - White space not held in text signatures box
  • 112: Bug - External notes should not be allowed to be sent without a TO
  • 15: Bug - When system is set to send text, but receive is set to display HTML, notifications contain HTML
  • 22: Bug - List of staff in reminders box shows random characters and/or wrong person included
  • 78: Bug - Absolute URL's for KB images
  • 105: Bug - Windows Desktop Installer should check if PHP is already installed and not continue if it is

59. Version 2.4.2 - Template Changes

This page describes the changes to each HelpSpot portal template. If you have an HTML editor available like Dreamweaver or BBEdit it is probably more efficient to simple use the diff tools to compare your edited documents (/custom_templates) with the new templates (/helpspot/templates/). If those tools are not available, the listings below will allow you to manually change the templates.

These changes are only needed if you have customized your portal and specifically customized the files listed below. If not, you do not need to make any adjustments.

Your portal will not work correctly until these changes have been made.

Note: If you're upgrading from version 1.x you will also need to apply the template changes here.

These templates have changed in version 2.4:

  • css.tpl.php
  • email.tpl.php
  • index.tpl.php
  • js.tpl.php
  • navigation.tpl.php
  • request.check.tpl.php
  • request.tpl.php
  • searchbox.tpl.php

css.tpl.php

New lines starting at 502:

pre{ font: 100% courier,monospace; border: 1px solid #ccc; overflow: auto; overflow-x: scroll; width: 90%; padding: 1em 1em 1em 1em; background: #fff7f0; color: #000 }
.initsubject{ color: #7F7F7F; } .request_summary{ display: block; overflow: hidden; height: 14px; } .feedback_box_error{ border: 1px solid red; padding: 10px; color: red; font-weight: bold; } .feedback_box_positive{ border: 1px solid green; padding: 10px; color: green; font-weight: bold; } .calendar_date_table{ padding-left: 0px; margin-left: 0px; margin-top: 2px; margin-bottom: 0px; padding-bottom: 0px; } .calendar_date{ text-align: bottom; border: 1px solid #666666; background-color: #fff; padding: 2px; } .calendar_date_holder{ color: #666666; cursor: pointer; } .sending_note{ color: red; }

email.tpl.php

Modified line 20, change form URL. Line should be:

<form action="index.php?pg=email&id=<?php echo $this->get_id ?>" method="POST">

New lines starting at 41:

<p><label for="youremail" class="datalabel"><?php echo lg_portal_youremail ?></label><br> <input type="text" name="youremail" size="40" maxlength="250" value="<?php echo $this->helper->visitor['email'] ?>" /> </p>
<?php //Captcha form protection. You can turn this on and off via a setting in Admin->Settings->System Security. It's enabled by default //This text captcha should be sufficient for most automated spam. If someone has modified a robot to target your site specifically //then obfuscating the word via javascript or using an image may improve results ?> <?php if($this->hd_useCaptcha == 1): ?> <p><label for="captcha" class="datalabel required"><?php echo lg_portal_captcha ?> - </label><b class="captcha_label"><?php echo $_SESSION['portal_captcha'] ?></b><br /> <?php echo $this->helper->showError('captcha','<br />') ?> <input type="text" name="captcha" size="20" maxlength="250" value="" /> </p> <?php endif; ?>
<div class="formbuttondiv">

index.tpl.php

New lines starting at 11:

case "request.check":
// If a visitor is logged in already send them to their history if($this->splugin('Request_Check','isLoggedIn') && empty($this->get_id)){ $this->helper->redirect($this->cf_url.'/index.php?pg=request.history'); }
include $this->loadTemplate('request.check.tpl.php'); break;

New lines starting at 18:

break;
case "request.history": include $this->loadTemplate('request.history.tpl.php'); break;
case "css":

New lines starting at 71:

		
break;
case "maintenance": include $this->loadTemplate('maintenance.tpl.php'); break;
default:

js.tpl.php

Modified line 12, added text to header. Line should be:

header('Content-type: text/javascript; charset=utf-8');
header('Content-Disposition: inline; filename="js.js"');

New lines starting at 58 (bottom of file):

}
//Function that resets a portal login password function ChangePortalLoginPassword(){ //Find the new password they've set var password_new = $F('new_password'); //Find the password confirmation they've set var password_confirm = $F('new_password_confirm'); //Check if the password and the password confirm field match and that the password is not empty. if(password_new != password_confirm || password_new.empty()){ //Popup an alert to notify the user that the passwords must match show_feedback("<?php echo lg_portal_req_passworderror ?>","error"); }else{ //Everything is OK so send the new password to the server new Ajax.Request("index.php?pg=password.change", { method: "post", parameters: {password: password_new}, onSuccess: function(transport) { show_feedback("<?php echo lg_portal_req_passwordsaved ?>","success"); //Hide the password box and clear the form fields $("change_password_box").hide(); $("new_password").value = ""; $("new_password_confirm").value = ""; }, onFailure: function(transport){ show_feedback("<?php echo lg_portal_req_passwordposterror ?>","error"); } }); } } //Function that sends the retrieve password email function RetrievePortalLoginPassword(){ //If there's no email in the box show feedback that an email needs to be entered if($F("login_email").empty()){ show_feedback("<?php echo lg_portal_req_emailempty ?>","error"); return; }else{ //Change link text to loading $("retrievePortalPasswordLink").update('<span class="sending_note"><?php echo lg_portal_req_sending ?></span>'); //An email is available so send the password email new Ajax.Request("index.php?pg=password.retrieve", { method: "post", parameters: {login_email: $F("login_email")}, onSuccess: function(transport) { show_feedback("<?php echo lg_portal_req_passwordsent ?>","success"); }, onFailure: function(transport){ show_feedback("<?php echo lg_portal_req_emailerror ?>","error"); }, onComplete: function(){ //Remove sending text $("retrievePortalPasswordLink").update(); } }); } } //Function to create a feedback box at the top of the right column. function show_feedback(message,type){ //Style the feedback box as appropriate for each type of feedback if(type == "error"){ $("feedback_box").addClassName("feedback_box_error"); }else{ //By default shows positive feedback $("feedback_box").addClassName("feedback_box_positive"); } //Show the box $("feedback_box").show(); //Insert message into the feedback box $("feedback_box").update(message); }

navigation.tpl.php

New lines starting at 46 (bottom of file):

<div id="content2col">
<!-- Feedback box. Hidden by default and called from Javascript functions to provide user feedback --> <div id="feedback_box" style="display:none;"></div>

request.check.tpl.php

New lines starting at 11:

	
<h1><?php echo lg_portal_accessidheader ?> : <?php echo $this->get_id ?></h1>
<?php include $this->loadTemplate('loginbar.tpl.php'); ?>
<br />

Modified lines starting at 26. Replace the entire block below with the one after:

Old Code:

<?php /* Because the updates are only protected by the access key this code hides the request information after the request has been closed for X days. This keeps people from submitting information about a new request into an old one and also prevents search engines from getting this private information if the URL is accidentally published. You may change the time after the request is closed through the last variable below. Other valid examples are: '2 week', '1 month', '15 day'. Empty will turn off access as soon as the request is closed '' Leaving some time is also good because if the customers issue wasn't in fact solved then it gives them time to provide more information. In that case HelpSpot will reopen the request back to the original person assigned rather than the customer submitting a new request about an existing issue and the back and forth that results from that scenario. */ ?> <?php if($this->splugin('Request_Check','isClosed',$this->get_id,'2 Day')): ?>

New Code:

		<?php 
		/* This code hides the 
			request information after the request has been closed for X days. This keeps
			people from submitting information about a new request into an old one and also 
			prevents search engines from getting this private information if the URL is accidentally 
			published. You may change the time after the request is closed through the last variable below.
			Other valid examples are: '2 week', '1 month', '15 day'. Empty will turn off access as soon as the request is closed ''
			
			Leaving some time is also good because if the customers issue wasn't in fact solved then it gives them time to 
			provide more information. In that case HelpSpot will reopen the request back to the original person assigned 
			rather than the customer submitting a new request about an existing issue and the back and forth that results
			from that scenario.
			
			Note that as of version 2.4 this line also checks to see if the customer is logged in. If they are they are allowed 
			to view the request even if the time specified below has passed.
		*/ ?>
		<?php if($this->splugin('Request_Check','isClosed',$this->get_id,'2 Day') && !$this->splugin('Request_Check','isLoggedIn')): ?>

Modified line 43. Replace the entire line with the one after:

Old Code:

			
<p><a href="index.php?pg=request"><?php echo lg_portal_closedsubmitnew ?></a></p>

New Code:

			<p>
				<a href="index.php?pg=request.check"><?php echo lg_portal_closedlogin ?></a>
				<?php echo lg_portal_closedor ?>
				<a href="index.php?pg=request"><?php echo lg_portal_closedsubmitnew ?></a>
			</p>

New lines starting at 119:

<?php endforeach; ?>
<?php //Don't show update box for requests closed longer than 2 days ?> <?php if(!$this->splugin('Request_Check','isClosed',$this->get_id,'2 Day')): ?>
<p><label for="update" class="datalabel"><?php echo lg_portal_req_update ?>:</label><br />

New lines starting around 134:

<div class="formbuttondiv"> <input type="submit" name="submit" value="<?php echo lg_portal_req_updaterequest ?>" /> </div>
<?php endif; ?>
<?php endif; ?> <?php else: ?>

Modified line 149. Replace the entire block below with the one after:

Old Code:

<?php else: ?> <form action="index.php?pg=request.check" method="get"> <input type="hidden" name="pg" value="request.check" /> <p><?php echo $this->helper->showError('id','<br />') ?> <b><?php echo lg_portal_req_enterkey ?>:</b> <input type="text" name="id" value="" size="20" maxlength="100" /> <input type="submit" name="submit" value="<?php echo lg_portal_check ?>" /> </p> </form> <?php endif; ?>
<?php include $this->loadTemplate('footer.tpl.php'); ?>

New Code:

<?php else: ?>

	<form action="index.php?pg=request.check" method="get">
		<input type="hidden" name="pg" value="request.check" />
		<p><?php echo $this->helper->showError('id','<br />') ?>
			<b><?php echo lg_portal_req_enterkey ?>:</b><br /><br />
			<input type="text" name="id" value="" size="20" maxlength="100" tabindex="100" />
			<input type="submit" name="submit" value="<?php echo lg_portal_check ?>" tabindex="101" />
		</p>
	</form>
	
	<hr width="80%" />
	
	<form action="index.php?pg=login" method="post">
		<p><b><?php echo lg_portal_req_login ?>:</b></p>
		
		<p><label for="login_email" class="datalabel"><?php echo ($this->hd_requestCheckAuthType == "internal" ? lg_portal_req_loginemail : lg_portal_req_loginusername) ?>:</label><br />
			<?php echo $this->helper->showError('login_email','<br />') ?>
			<input type="text" name="login_email" id="login_email" size="40" maxlength="100" tabindex="102" value="<?php echo $this->get_login_email ?>" autocomplete="off" /><br />
			<?php if($this->hd_requestCheckAuthType == "internal"): ?>
			<?php //only show this password retrieval link if we're using internal authentication on the portal ?>
				<span id="retrievePortalPasswordLink">(<a href="#" onclick="RetrievePortalLoginPassword();return false;"><?php echo lg_portal_req_emailpassword ?></a>)</span>
			<?php endif; ?>
		</p>		

		<p><label for="login_password" class="datalabel"><?php echo lg_portal_req_loginpassword ?>:</label><br />
			<input type="password" name="login_password" id="login_password" size="40" maxlength="100" tabindex="103" value="" autocomplete="off" />
		</p>
		
		<p>
			<input type="submit" name="submit" value="<?php echo lg_portal_req_loginbutton ?>" tabindex="104" />
		</p>
	</form>
	
<?php endif; ?>
	
<?php include $this->loadTemplate('footer.tpl.php'); ?>

request.tpl.php

Modified line 206, change input size. Line should be:

	
<p><label for="captcha" class="datalabel required"><?php echo lg_portal_captcha ?> - </label><b class="captcha_label"><?php echo $_SESSION['portal_captcha'] ?></b><br /> <?php echo $this->helper->showError('captcha','<br />') ?>
<input type="text" name="captcha" size="15" maxlength="250" value="" />
</p>

searchbox.tpl.php

Modified entire file. Replace all lines in searchbox.tpl.php with:

<?php if($this->splugin('Forums_Forums','count') || $this->splugin('KB_Books','count')): ?>
	<form action="index.php" method="get">
	<input type="hidden" name="pg" value="search">
	<div class="">
		<p align="center">
			<input type="text" name="q" size="40" style="width:60%;" value="<?php echo $this->get_q ?>"> 
			<select name="area" id="area" style="width: 25%;">				
				<?php if($this->splugin('KB_Books','count')): ?>
					<option value="kb" <?php if($this->get_area == 'kb') echo 'selected' ?>><?php echo lg_portal_searchkb ?></option>
				<?php endif; ?>
				<?php if($this->splugin('Forums_Forums','count')): ?>
					<option value="forum" <?php if($this->get_area == 'forum') echo 'selected' ?>><?php echo lg_portal_searchforum ?></option>
				<?php endif; ?>
			</select>	
			<input type="submit" name="submit" value="<?php echo lg_portal_search ?>">
		</p>
	</div>
	</form>
<?php endif; ?>

60. Version 2.1.1

  • 19: Feature - System preference to show linked images in HTML emails
  • 64: Feature - Set new installations to have IP/Time portal validation off by default
  • 98: Feature - Improved speed of filters which use date/time ranges
  • 99: Bug - Display count in filters could not be removed
  • 69: Bug - Special characters in Live Lookup or request history searches break search results
  • 74: Bug - Request ticker doesn't properly show HTML emails
  • 79: Bug - Attachments hard to click when horiz scroll in place on request history
  • 82: Bug - Add close option to request history box
  • 91: Bug - Attachments with no file extensions are not downloadable
  • 6: Bug - Image tags not removed from modal box display of initial requests
  • 8: Bug - Wrong URL for request check when using notify feature
  • 9: Bug - No text version sent with HTML emails of staff notifications
  • 10: Bug - Spellchecker not enabled in Forums
  • 11: Bug - HTML rendering bug for emails from Outlook using Word for editor
  • 16: Bug - Merging request with itself doesn't provide proper error
  • 21: Bug - White space trimmed from signature when in text email mode
  • 22: Bug - List of staff in reminders box shows random characters and/or wrong person included
  • 27: Bug - Upgrade link in admin should point to installation upgrade page not zip and tar files
  • 28: Bug - Force reminders to be sent via email even if notification is off
  • 40: Bug - Force MySQL to not use strict mode
  • 42: Bug - Request ID placeholder not replaced correctly in update notes
  • 43: Bug - Wysiwyg spellchecking doesn't work on Windows
  • 51: Bug - Improperly formated email FROM not parsed correctly
  • 54: Bug - Badly formatted HTML emails cause email system to get stuck
  • 55: Bug - Allowing Gecko spellcheck option in wysiwyg breaks spellchecker on some Windows servers. Gecko spellcheck option turned off
  • 57: Bug - Admin page doesn't load if bad query returned for stats
  • 58: Bug - Set spellchecker to use upload_tmp_dir instead of system temp dir when possible
  • 63: Bug - Trash deleted even when set to never delete

61. Version 2.1.0

Primary Changes

  • Significant speed improvements in the Workspace for all filters
  • Batch reply to multiple requests at once
  • Automation rules can mark items as not urgent
  • Email subject lines are now templated and can contiain placeholders
  • Test mailbox connection button on mailbox page to allow for easy testing
  • 6 new reports
  • Portal template editing from within HelpSpot in Admin->Tools
  • Hide number of requests history notes to user configurable amount
  • Request merging
  • User preference for returning to request page or workspace after closing request
  • Ability to email results of an automation rule
  • Automation option to email an arbitrary email address
  • Automation option to send SMS
  • Improved reminders interface
  • Added view source option to emails in request history
  • If zlib is available Javascript will be compressed for increased speed
  • Moderators may now post to closed forums, effectively allowing moderator posting only on selected forums.
  • 6 New custom fields: Ajax select, decimal, drill down, regex match, date, and date time
  • Expanded placeholders throughout system
  • Fast navigation menu for request page
  • Custom where clause filter
  • Added latest note column
  • Limit number of emails imported per tasks.php run
  • Email request ID prefix to allow inter-HelpSpot installation communication via email
  • Live Lookup auto run option
  • Live Lookup now sends and sets custom fields
  • Automation rules now log notes correctly
  • Status id's over 10 save in filters
  • Last update filter times now filter correctly
  • Subject line width fixed
  • Portal file downloads on Windows/SQL Server fixed
  • Removed unneeded settings for load limit and RSS short description

62. Version 2 - Template Changes

This page describes the changes to each HelpSpot portal template. If you have an HTML editor available like Dreamweaver or BBEdit it is probably more efficient to simple use the diff tools to compare your edited documents (/custom_templates) with the new templates (/helpspot/templates/). If those tools are not available, the listings below will allow you to manually change the templates.

These changes are only needed if you have customized your portal and specifically customized the files listed below. If not, you do not need to make any adjustments.

Note: Your portal will not work correctly until these changes have been made.

These templates have changed in version 2:

  • css.tpl.php
  • forums.posts.tpl.php
  • forums.topics.tpl.php
  • header.tpl.php
  • index.tpl.php
  • request.tpl.php
  • request.check.tpl.php

css.tpl.php

New line starting at 15:


header('Content-type: text/css');
header('Content-Disposition: inline; filename="style.css"');
?>
/* Import styles for calendar used in date/datetime custom fields */
@import "js/jscalendar/skins/aqua/theme.css";


body
{

New line starting at 438:


}

.captcha_label{
	color:				#000;
	font-size:			14px;
	border: 			1px solid red;
	padding:			3px 10px 3px 10px;	
}


.forumoption{

Remove line 41 in h2 class:

margin-bottom: -10px;

Remove line 60 in h4 class:

margin-bottom: -10px;

Remove line 138 in #content2col class delete the /20px:

font: 12px/20px Arial, Helvetica, sans-serif;

forums.posts.tpl.php

New line starting at 85:

<p><label for="sURL" class="datalabel"><?php echo lg_portal_posterurl ?>:</label><br /> <input type="text" name="sURL" size="40" maxlength="250" value="<?php echo $this->helper->visitor['url'] ?>" /> </p>
<?php //Captcha form protection. You can turn this on and off via a setting in Admin->Settings->System Security. It's enabled by default //This text captcha should be sufficient for most automated spam. If someone has modified a robot to target your site specifically //then obfuscating the word via javascript or using an image may improve results ?> <?php if($this->hd_useCaptcha == 1): ?> <p><label for="captcha" class="datalabel required"><?php echo lg_portal_captcha ?> - </label><b class="captcha_label"><?php echo $_SESSION['portal_captcha'] ?></b><br /> <?php echo $this->helper->showError('captcha','<br />') ?> <input type="text" name="captcha" size="20" maxlength="250" value="" /> </p> <?php endif; ?>

forums.topics.tpl.php

New line starting at 15:

<p><label for="sURL" class="datalabel"><?php echo lg_portal_posterurl ?>:</label><br /> <input type="text" name="sURL" size="40" maxlength="250" value="<?php echo $this->helper->visitor['url'] ?>" /> </p>
<?php //Captcha form protection. You can turn this on and off via a setting in Admin->Settings->System Security. It's enabled by default //This text captcha should be sufficient for most automated spam. If someone has modified a robot to target your site specifically //then obfuscating the word via javascript or using an image may improve results ?> <?php if($this->hd_useCaptcha == 1): ?> <p><label for="captcha" class="datalabel required"><?php echo lg_portal_captcha ?> - </label><b class="captcha_label"><?php echo $_SESSION['portal_captcha'] ?></b><br /> <?php echo $this->helper->showError('captcha','<br />') ?> <input type="text" name="captcha" size="20" maxlength="250" value="" /> </p> <?php endif; ?>

header.tpl.php

New lines starting at 19:



<link rel="stylesheet" type="text/css"  href="<?php echo $this->cf_url ?>/index.php?pg=kb.wysiwyg" media="screen, projection" />

<!--javascript-->
<script type="text/javascript" src="<?php echo $this->cf_url ?>/index.php?pg=js"></script>

</head>

Modified line starting at 19 (line 23 after above edit), replace <body> with:

<body onload="<?php echo $this->pg_onload ?>">

index.tpl.php

New lines starting at 16:


	case "css":
		include $this->loadTemplate('css.tpl.php');
		break;	
	case "js":
		include $this->loadTemplate('js.tpl.php');
		break;				
	case "kb":
		include $this->loadTemplate('kb.tpl.php');
		break;

request.tpl.php

New lines starting at 22:


$this->assign('pg_title',lg_portal_request);

//Set onload
$this->assign('pg_onload', "ShowCategoryCustomFields();");

include $this->loadTemplate('header.tpl.php');

Modify line 106 (109 after above change), replace <select name="xCategory"> with:

<select name="xCategory" id="xCategory" onchange="ShowCategoryCustomFields();">

New lines starting at 123 (126 after above changes):

<?php $fieldID 		 = 'Custom'.$field['fieldID']; //Set the field ID for use below ?>
<?php $visible = $field['isAlwaysVisible'] ? '' : 'display:none;'; //Set if the custom field is visible by default ?>

Modify line at 124 (128 after above changes), replace <p> with the code below. Be sure to leave the rest of the line the same from the <label> tag on.

<p id="<?php echo $fieldID ?>_wrapper" style="<?php echo $visible ?>"><label for="<?php echo $fieldID ?>" class="datalabel<?php echo $requiredClass ?>"><?php echo $field['fieldName'] ?>:</label><br />

New lines starting at 142 (146 after above changes):


		<?php elseif($field['fieldType'] == 'numtext'): ?>
			<input name="<?php echo $fieldID ?>" type="text" size="10" maxlength="10" value="<?php echo $this->$fieldID ?>">
		<?php elseif($field['fieldType'] == 'drilldown'): ?>	
			<?php echo $this->helper->getDrillDownField($field,' '); ?>
		<?php elseif($field['fieldType'] == 'decimal'): ?>	
			<input name="<?php echo $fieldID ?>" type="text" size="10" maxlength="10" value="<?php echo $this->$fieldID ?>">
		<?php elseif($field['fieldType'] == 'regex'): ?>
			<?php echo $this->helper->getRegexField($field); ?>
		<?php elseif($field['fieldType'] == 'date'): ?>	
			<?php echo $this->helper->getDateField($field); ?>
		<?php elseif($field['fieldType'] == 'datetime'): ?>	
			<?php echo $this->helper->getDateTimeField($field); ?>
		<?php endif; ?>

New lines starting at 198:

<?php endif; ?>

<?php 
//Captcha form protection. You can turn this on and off via a setting in Admin->Settings->System Security. It's enabled by default 
//This text captcha should be sufficient for most automated spam. If someone has modified a robot to target your site specifically 
//then obfuscating the word via javascript or using an image may improve results ?>
<?php if($this->hd_useCaptcha == 1): ?>

	<p><label for="captcha" class="datalabel required"><?php echo lg_portal_captcha ?> - </label><b class="captcha_label"><?php echo $_SESSION['portal_captcha'] ?></b><br />
		<?php echo $this->helper->showError('captcha','<br />') ?>
		<input type="text" name="captcha" size="20" maxlength="250" value="" />
	</p>
	
<?php endif; ?>

</div> <div class="formbuttondiv">

request.check.tpl.php

Modified lines starting at 72. Replace the entire block below with the one after:

<?php //Output public custom fields. ?> <?php foreach($this->splugin('CustomFields','getPublicCustomFields') AS $field): ?> <?php $fieldID = 'Custom'.$field['fieldID']; //Set the field ID for use below ?> <b><?php echo $field['fieldName'] ?>:</b> <?php if($field['fieldType'] == 'checkbox'): ?> <?php echo ($request[$fieldID] == 1 ? lg_portal_checkboxchecked : lg_portal_checkboxempty) ?><br /> <?php else: ?> <?php echo (empty($request[$fieldID]) ? ' - ' : $request[$fieldID]) ?><br /> <?php endif; ?> <?php endforeach; ?> <br />

New code:

	<?php //Output public custom fields. ?>
	<?php foreach($this->splugin('CustomFields','getPublicCustomFields') AS $field): ?>
		
		<?php $fieldID = 'Custom'.$field['fieldID']; //Set the field ID for use below ?>
		<?php $visible = $field['isAlwaysVisible'] ? '' : 'display:none;'; //Set if the custom field is visible by default ?>
		
		<div id="<?php echo $fieldID ?>_wrapper" style="<?php echo $visible ?>">
		<b><?php echo $field['fieldName'] ?>:</b> 
			
			<?php if($field['fieldType'] == 'checkbox'): ?>
				<?php echo ($request[$fieldID] == 1 ? lg_portal_checkboxchecked : lg_portal_checkboxempty) ?>
			<?php elseif($field['fieldType'] == 'drilldown'): ?>
				<?php echo $this->helper->showDrillDownField($request[$fieldID]); ?>
			<?php elseif($field['fieldType'] == 'date'): ?>	
				<?php echo $this->helper->shortDateFormat($request[$fieldID]) ?>
			<?php elseif($field['fieldType'] == 'datetime'): ?>
				<?php echo $this->helper->longDateFormat($request[$fieldID]) ?>
			<?php else: ?>
				<?php echo (empty($request[$fieldID]) ? ' - ' : $request[$fieldID]) ?>
			<?php endif; ?>
		</div>
		
	<?php endforeach; ?>			
	<!-- You must uncomment this line if you want to show custom fields -->
	<script type="text/javascript" language="JavaScript">ShowCategoryCustomFields(<?php echo $request['xCategory'] ?>);</script>
	<br />	

63. Version 1.5.5

New Features

  • Option in each request history log item to show it as text holding the line break formatting
  • Added fax as an option for contacted via
  • Queues in mobile interface now show first line of request
  • Added request ID filter condition
  • Personal photo's now limited to 50K to prevent users from uploading large files
  • Added relative to last update filter condition
  • Tasks.php now tries to prevent auto-replies to undeliverable messages

Bug Fixes

  • Fixed bug with closed requests not being correctly reopened and instead opening a new request
  • Fixed bug in Live Lookup which prevented multiple results from being displayed
  • Fixed session logout bug with some versions of MySQL
  • Removed trashed items from being counted in request drop down list
  • Removed trashed items from being counted in reports
  • Don't allow reactivation of staff when no license slots are available
  • Fixed path to upgrade links
  • When entering print view in a queue sort order is preserved
  • Fixed broken images
  • Fixed Safari bug with drag/drop
  • Spam count in forums now shows correct amount
  • Javascript bug in spam delete when submitting
  • Fixed PHP4 bug with deleting portal spam
  • Fixed calendar time issue when creating reminders in the PM
  • No longer need to display "last update" columns to sort by them
  • Javascript bug in IE when doing history search
  • Improved error message on index.php before installation
  • Deleting a staffer with active requests and will now ignore any auto-assignments on categories they are in
  • Time tracker box now observes preference setting when creating a new request

64. Version 1.5.1

Bug Fixes

  • Fixed major bug where some Windows installations would not be able to access admin.php
  • Fixed Live Lookup toggle error.
  • Fixed category list in filters when in limited access mode.

65. Version 1.5.0

New Features

  • Filters are totally redesigned with dozens of new options and combinations. In addition, the new interface makes it much easier to see what conditions are defined. Viewable columns are now sortable, OR filtering, and much more.
  • 3 tier SPAM filtration added to portal forms.
  • Significant speed enhancements to batch operations in the queue's.
  • My Queue now shows if a request has been replied to. This column can also be added to filters.
  • Prepared responses are now group-able.
  • Request notes can now be sent to external emails. For instance to ask for input from a vendor.
  • The portal now accepts file uploads in the request submission form as well as displays them on the request check page.
  • Requests can now be moved to the "trash". Trashed requests will be automatically deleted after 30 days (or less if configured to do so by the administrator)
  • Age limits for re-opening requests. Emails for a request older than this limit will be turned into new requests.
  • The request note text area now auto resizes as you type.
  • Forum posts can now be spellchecked and can insert prepared responses and knowledge book links.
  • Improved calendar selector for dates.
  • After closing a request the user is now returned to the last queue they were in rather than to the closed request.
  • Added 'Mark as spam' as option for mail rules.
  • Improved caching mechanism for Internet Explorer speeds up page loading and fixes issues with old cache pages being shown when they shouldn't be.
  • Live Lookup can now be called via HTTP POST.
  • Added several new conditions to Automation.
  • The Time Tracker is now available on new requests before submitting the request.
  • Audio files are now embedded into the request history allowing one click playing.
  • Support for MySQL 5
  • Support for Microsoft SQL Server 2005
  • Support for the PHP MySQLi interface.
  • Support for IE7
  • RSS feeds now use HTTP basic authentication for more secure access.
  • Reordering of workspace columns, filter columns, and custom field lists now draggable for easy reordering.
  • Filters now paginate when they hit the single page limit.
  • Ability to run individual instances of tasks.php and tasks2.php for each mailbox/automation rule.
  • Tasks.php debugging now shows more detail and speeds.
  • The CC field can now be set from a prepared response.
  • Time reports can now be filtered by all other request criteria like categories and status.
  • Optimized email SPAM filter resulting in dramatically faster checking and learning.
  • Status, category, and custom fields can now be set by passing values into the request page via GET.

Bug Fixes

  • Fixed international character issues in time tracker and Live Refresh.
  • Fixed time comparison conditions in Automation.
  • Filtering on contacted via now works correctly.
  • Assigned to Inbox is now remembered correctly in filters.
  • Fixed error created in error log when using Live Refresh and the queue being called had 0 requests in it.
  • Email notifications no longer sent when an email is detected to be SPAM.
  • Fixed image rendering bug in knowledge book WYSIWYG editor.
  • Fixed cookies so 2 different installations can safely share the same domain in different folders.
  • Fixed bug on MS SQL Server where custom fields using predefined lists would leave a change note when they shouldn't.
  • CSS change so that request notes which have strings more than 400px wide no longer pull interface to the right.
  • User passwords now hidden from administrators.
  • Limited access mode no longer shows unassigned categories in queue batch operation list.
  • Printer friendly portal pages now correctly format HTML.
  • Fixed Live Lookup link when customer ID was not numeric.
  • Fixed bug in admin settings when trying to use Black Box auth before setting usernames.
  • Added check for a new customer trying to upload a license with less named users than exist in their trial installation.

66. Version 1.5.0 - Template Changes

This page describes the changes to each HelpSpot portal template. If you have an HTML editor available like Dreamweaver or BBEdit it is probably more effecient to simple use the diff tools to compare your edited documents (/custom_templates) with the new templates (/helpspot/templates/). If those tools are not available, the listings below will allow you to manually change the templates.

These changes are only needed if you have customized your portal and specifically customized the files listed below. If not, you do not need to make any adjustments.

Note: Your portal will not work correctly until these changes have been made.

These templates have changed in version 1.5.0:

  • css.tpl.php
  • forums.posts.tpl.php
  • forums.topics.tpl.php
  • index.tpl.php
  • request.check.tpl.php
  • request.tpl.php

css.tpl.php

New line starting after 484:

pre{
font: 100% courier,monospace;
border: 1px solid #ccc;
overflow: auto;
overflow-x: scroll;
width: 90%;
padding: 1em 1em 1em 1em;
background: #fff7f0;
color: #000
}

forums.posts.tpl.php

New lines starting after line 92, just before the close form tag </form>

	
<!-- START: SPAM Protection DO NOT REMOVE -->
<?php echo $this->helper->getSPAMCheckFields() ?>
<!-- END: SPAM Protection DO NOT REMOVE -->

forums.topics.tpl.php

New lines starting after line 95, just before the close form tag </form>

	
<!-- START: SPAM Protection DO NOT REMOVE -->
<?php echo $this->helper->getSPAMCheckFields() ?>
<!-- END: SPAM Protection DO NOT REMOVE -->

index.tpl.php

New lines after line 56

case "moderated":
include $this->loadTemplate('moderated.tpl.php');
break;

request.check.tpl.php

Edit line 20. It should now be:

<form action="index.php?pg=request.check" method="post" enctype="multipart/form-data">

New lines after line 115

<?php //File uploads. You can turn this on and off via a setting in Admin->Settings->Portal. It's disabled by default ?>
<?php if($this->hd_allowFileAttachments == 1): ?>

<p><label for="doc[]" class="datalabel"><?php echo lg_portal_req_file_upload ?>:</label><br />
<?php //TIP: You can have multiple file uploads by adding more lines identical to the one below. ?>
<input type="file" name="doc[]" size="40">
</p>

<?php endif; ?>

request.tpl.php

Edit line 33. It should now be:

<form action="index.php?pg=request" method="post" enctype="multipart/form-data">

Replace line 146 with:

<?php //portalFormFormat 1 is the complex 3 question display. 2 is the simple single textarea. 
//1 is the default. If you'd like to just use the simple textarea you can switch the setting in Admin->Settings->Portal

if($this->hd_portalFormFormat == 1): ?>

New lines after original line 169 (after above modification it's around 172)

<?php //File uploads. You can turn this on and off via a setting in Admin->Settings->Portal. It's disabled by default ?>
<?php if($this->hd_allowFileAttachments == 1): ?>

<p><label for="doc[]" class="datalabel"><?php echo lg_portal_req_file_upload ?>:</label><br />
<?php //TIP: You can have multiple file uploads by adding more lines identical to the one below. ?>
<input type="file" name="doc[]" size="40">
</p>

<?php endif; ?>

New lines after line 175 (after above modification it's around 188), just before the close form tag </form>

<!-- START: SPAM Protection DO NOT REMOVE --> <?php echo $this->helper->getSPAMCheckFields() ?> <!-- END: SPAM Protection DO NOT REMOVE -->  

67. Version 1.3.1

New Features

  • Binary searching enabled in SQL Server and MySQL for phrase searching
  • Live Lookup now AJAX enhanced, embedded in the page
  • Request page history search now AJAX enhanced, embedded in the page
  • Customer information can now be inserted from a request page history search
  • You can now add the 'Take It' button to filters. Note that it does not prevent others from taking the request as the Inbox does.
  • Make public button returned to request history and now logs when the public/unpublic state is changed and who did so
  • Mail rules can now assign to the inbox
  • Using SMTP authentication is now optional when using an SMTP server for email
  • Note attachments now visible in the portal
  • Last update/customer update/public update/time/public count fields now sortable
  • Each knowledge book now has a printer friendly version of the entire book
  • Live Refresh feature can optionally refresh your queue/filter without reloading the page or losing your checked requests
  • Email accounts now have loop protection so that HelpSpot and an email autoresponder don't send emails to each other indefinitely creating numerous new requests.
  • Subject lines of outbound emails now contain only the request ID and not the full access key

Bug Fixes

  • Live Lookup now works correctly from the command line
  • Tasks.php memory performance improved
  • Existing responses can now be selected properly when using SQL Server
  • Spellchecker now works when PHP short tags disabled
  • Knowledge book searches no longer show HTML in the portal
  • Postgres didn't correctly add time tracking in filter column
  • Don't show make public/private in closed requests
  • Apostrophe in Live Lookup request no longer breaks 'insert' button
  • Extra brackets/quotes removed from CC box on public notes
  • Request history quoting now works with accented characters
  • Emails from the same account but different capitalization now correctly displayed as public
  • Request page javascript checks now work correctly in IE
  • Tasks.php now runs correctly from the command line with IP security enabled
  • Mbstring functions now used if available before Iconv
  • Placeholders used in request notes now replaced before storing in database so that they do not change when a request is reassigned
  • Fix WYSIWYG error when using zlib compression
  • Internal change to allow easier use of CGI wrappers

68. Version 1.2.0

Major New Features

  • Automation rules for escalation, reassignment and more
  • Mail rules for routing email and instant responses
  • Automatic assignment now controlled on the category level
  • Time tracking
  • Export filters to Excel
  • Predefined responses can now set several request fields as once
  • Quote request history notes
  • Configurable session timeouts

Other New Features

  • New filter columns last update, last customer update, public note count
  • Excess whitespace now removed from Microsoft Outlook emails
  • Improved email parser and handling of nested multipart mime messages
  • Show sent subject in request history
  • Out of office can now be reassigned to Inbox
  • Out of office shown on request page assignment drop down
  • Forums now show if a poster is subscribed via email
  • Personal preference added for defaulting notes to public
  • Personal preference added for embedding images
  • Personal preference added for knowledge book wysiwyg
  • All emails in the "To" header of an email are now shown
  • New filter option for open less than X hours
  • Forum RSS feeds now have pubdate item
  • Embedded images now show file names
  • Open a knowledge book page from the request page
  • Filter option to make RSS feeds customer friendly (no private notes)
  • Added week interval to reports
  • Added quick time selection to reports
  • New parser tag to allow staff assignment
  • Added the ability to batch assign to Inbox
  • Ability to limit the calling of tasks.php and tasks2.php to certain IP's

Bug Fixes

  • Improved email validation
  • Knowledge book pages in related pages popup now numbered correctly
  • Tab order on request page fixed
  • Date in before/after filter field can now be changed
  • Emails with only attachments now show in history correctly
  • Public requests that didn't send an email no longer store an email subject
  • Request ID search box fixed in FireFox 1.5+
  • Keyboard shortcuts no longer interfere with request ID search
  • Email found to be SPAM by email parser now has assigned user reset

69. Version 1.1.3

Bug Fixes

  • Critial: Email with very long "from" addresses (usually SPAM) can break the email parser and cause excess rows to be inserted in the request history database table. While a rare occurrence updating is strongly recommended.
  • SPAM filter efficiency bugs fixed.
  • Databases now protected from overly long strings in customer information

70. Version 1.1.2

New Features

  • Added debugging mode to tasks.php (enable in Admin->Settings)
  • Mobile version now has titles on each page
  • Mobile version now does not embed images in requests
  • Added ability to cancel file uploads
  • Added ability to pass initial customer data into create request screen via GET
  • When CCing others on a note the CC's are stored and displayed in the request history

Bug Fixes

  • Fixed problem with request page when IMAP extension not installed
  • Fixed blank page error on closed requests when running PHP 5.1.2 on Windows with IIS
  • HelpSpot now recognizes pjpeg
  • Attached images now save with correct file names to desktop
  • Append response now uses new menu in place of select list which caused the window to strech
  • Back arrow now does not return to queue when on request page and using keyboard shortcuts
  • Required numeric fields now accept 0
  • Green tab was stretched too far when uploading files
  • Fixed error with newest posts RSS feed
  • Fixed checkbox image when showing a custom field checkbox in a filter
  • Request ticker no longer shows both open and closed requests. Now only open.

71. Version 1.10

New Features

  • Integrated spellchecking
  • Dedicated mobile access version (requires HTML capable mobile browser)
  • Keyboard shortcuts in workspace
  • Ability to set default workspace
  • Auto shrink attach images for display in request history
  • New admin page layout
  • Enhanced Live Lookup layout
  • Urgent emails now marked as urgent when imported
  • Other people CC'd on emails are now visible
  • External emails may be CC'd on a request
  • Ability to make an assigned request back to unread
  • Improved request creation layout
  • Insert a link to a knowledge book page in a request
  • View latest forum posts in addition to topics
  • Limited access mode for Guest and Level 2 staffers. Allows use of those types for customer access by hiding other customers information.
  • Added portal template options to show custom fields on request check page.

Bug Fixes

  • Fixed character set issues in email names
  • Fixed character set issues with display of special characters, default character set now ISO-8859-1
  • SQL Server now defaults to AND searching
  • Spam requests marked as closed from request screen no longer train twice
  • In portal replaced incorrect maxsize HTML elements
  • Fixed reporting bug in reporting tags drill down
  • Upgraded WYSIWYG editor to eliminate IE bugs

72. Version 1.03

New Features

  • Add link to release notes on the admin homepage
  • Check for new HelpSpot version every 5 days upon administrator login
  • Provide option to strip HTML from requests or just escape HTML, allow exceptions to stripping
  • Underline "time since" in request history to make date more obvious to rollover
  • Added more tags to email parser including category and custom fields
  • Show category ID's and custom field ID's in their respective admin pages
  • Allow creation of multiple portal request submit forms and correctly handle redirects
  • Allow override and submission of 'simple' request submission textarea even when details form is in use in settings
  • Add assigned staff member placeholders for use in predefined requests

Bug Fixes

  • Fixed "misbehaving headers" error when running on Windows as a CGI
  • Increased DB error checking in installer.php
  • Incorrect PHP version checking in installer.php
  • Email subjects initiated from the create request screen were not maintained in future correspondence
  • When emails are received with attachments, but no text body the attachments were not shown
  • Changed wording in installer to 'installation time zone'
  • Lowered tasks.php timeout to prevent scripts from hanging
  • Removed unneeded javascript from installer.php
  • Corrected portal navigation highlighting when using custom templates
  • HTML not stripped from update emails correctly
  • Javascript popup alert when sending email fails on create a request page, now works correctly
  • When customizing columns the date closed would incorrectly show 12/31/1969
  • CC to other staff with no note caused blank page to appear
  • Custom fields admin page redesigned slightly to make examples more clear