Upgrading to 4.0 from 3.7

SupportPal 4.0 is a major release with some breaking changes. The focus of this release is around improving the add-on (a general term we use to cover plugins, widgets, channels, integrations, reports, and languages) functionality and introduces the add-on marketplace.

This upgrade guide is aimed at those upgrading from the last stable version (3.7.x) to 4.0.0.

Estimated Upgrade Time: 1 - 2 Hours.

Backup!
Before attempting an upgrade, please take a backup of both your SupportPal database and all associated SupportPal files, then verify the backup is valid (not corrupt). If you use either of our operator panel system update or app update command options, a backup will automatically be taken before performing the update.

What's New?

View the 4.0 Release Notes for the new features and improvements in this series.

New System Requirements

The new minimum PHP version is now 7.4.0.
PHP 7.2 and 7.3 have reached end of life and support for them have been dropped in this release.
The new minimum version for ionCube loaders is now 11.0.1.
The Hash PHP extension is now required.
Internet Explorer 11 is no longer supported.
The /addons directory and subdirectories must be writeable.

Docker Changes

Breaking changes have been introduced to all of our docker deployment methods in order to facilitate easier customisation and upgrades. Jump ahead to the relevant section depending on which docker deployment method you're using:

Monolithic container (installation guide) - jump ahead.
High availability containers (installation guide & AWS Elastic Beanstalk) - jump ahead.

Monolithic Deployments

Follow the usual upgrade steps described at Upgrade Guide.

High Availability Deployments

New Image Tag Naming Convention

The format used for tags on our high availability images has changed. Previously the format version-type-os was used, where:

version represented the SupportPal version number
type represented the purpose of the image, for example web, cron
os represented the os version string, for example Debian buster (version 10)

The new, simplified, format is now version-type.

Upgrade steps

Due to the introduction of breaking changes, we recommend migrating to a new directory. Follow the steps below to begin:

Open a bash compatible terminal. If you're on Windows, use Git Bash.
Take a full backup.

Browse to a directory where you would like to create a new SupportPal deployment, and run the below commands:

            
                curl -LsS https://raw.githubusercontent.com/supportpal/helpdesk-install/master/templates/docker-compose/setup.sh
                bash setup.sh --target

Follow the new customisation guidance to adapt any previous customisations to the new structure. This should typically be the difference between the *.dist.yml and .yml files.
Destroy the old containers:
1. Browse to your old helpdesk-install deployment directory.
2. Copy the value of the COMPOSE_FILES variable from Makefile. For example given:
```
COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.override.yml
```
  The copied value would be:
```
-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.override.yml
```
3. In the copied value, replace docker-compose.override.yml with docker-compose.https.yml
4. Replace COMPOSE_FILES with the copied value in the command below and run:
```
docker compose COMPOSE_FILES down -v
```
Initialise the new containers:
1. Browse to your old helpdesk-install deployment directory.
2. Copy the entire COMPOSE_FILES line from Makefile. For example:
```
COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.override.yml
```
3. In the copied value, replace docker-compose.override.yml with docker-compose.https.yml
4. Paste the copied value at the top of the Makefile within your new deployment directory (created earlier by setup.sh). For example,
```
                    COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.https.yml
                    include Makefile.dist
                    include .env
                
```
5. From your old deployment directory, copy over your database secrets and SSL certificates from ssl/ and secrets/ directories.
6. Remaining within the new deployment directory, run:
```
                    make start
                
```

Development Changes

Template Engine

Twig, our template engine, has been upgraded from v2 to v3 which offers better performance and robustness. The template engine is used throughout the help desk to render merge fields.

For most users, the upgrade should not make a difference. However, if you have written any custom Twig code we encourage to read over the list of deprecations in Twig 2.x.

Framework

We've upgraded the core framework (laravel/framework) from version 6 to 8. Please review the upgrade guides for breaking changes:

We recommend testing any customisations on a development installation before upgrading your help desk. Please contact us for a development license key if you don't already have one.

Add-ons

An important part of this release is the improvements to the add-on framework that exists in the software. An add-on is a general term that covers any component which is not core to the software and adds additional functionality.

Add-on Categories

Channels - the methods through which tickets can be opened in the system.
Integrations - for configuring connection (API or app) details for third-party providers that are utilised in various places in the system.
Languages - translate the system to other languages. New in 4.0.0.
Plugins - general area to build extra functionality to the system.
Widgets - the panels that show on the operator dashboard.

All add-ons are now placed in the /addons directory in the SupportPal installation directory, within which there are subdirectories for each category of add-on.

During the upgrade, the system will try to move non-default add-ons to the new directories, such as plugins from /app/Plugins/ to /addons/Plugins. The old directories will no longer be used.

PHP Namespace

As the files have moved to a new directory, we recommend updating the PHP namespace in your add-ons. It is just a case of replacing any instances of App\Plugins\ to Addons\Plugins\ (and similar applies to the other add-on categories). For example:


namespace App\Plugins\BlestaInformation\Controllers;

This should be changed to:


namespace Addons\Plugins\BlestaInformation\Controllers;

Language/View Namespace

To avoid conflicts between different types of add-ons, the language and view namespaces have been prefixed with the add-on category. It is just a case of replacing any instances of MyPlugin:: to Plugins#MyPlugin:: (and similar applies to the other add-on categories) throughout your PHP and Twig files.

Views


View::composer('BlestaInformation::settings', function ($view) {

This should be changed to:


View::composer('Plugins#BlestaInformation::settings', function ($view) {

Languages


<th>{{ Lang.get('BlestaInformation::lang.invoice_no') }}</th>

This should be changed to:


<th>{{ Lang.get('Plugins#BlestaInformation::lang.invoice_no') }}</th>

Plugins

All non-default plugins will be automatically disabled on upgrade and must be manually reactivated. We recommend reading over this section and ensure each plugin works on 4.0.0 before reactivating.

Widgets

The signature of the getEmbeddableView function has changed, you must update your widgets to return a View object or null.


    public function getEmbeddableView(): ?View;

Languages

Language files have moved from /resources/lang to /addons/Languages and now have a new structure. If you have one or more custom languages installed currently, the upgrade script will automatically attempt migrating them to the new format during the upgrade to 4.0.

Other Important Changes

New editor: TinyMCE
The text editor included in SupportPal has been replaced with TinyMCE. We have tried to replicate the look and feel of the old editor as much as possible, but there will be some differences in usage.
Assigning a ticket to an SLA plan must match its conditions
If you wish to change the SLA plan on a ticket, the conditions for each plan are now checked before a list of matching plans are provided to choose from. Previously it was possible to assign to any SLA plan.
Default order for articles search API endpoint
The default order for articles that are fetched by the articles search API endpoint now uses the weight option with descending direction (the strongest weight first).