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.
Estimated Upgrade Time: 1 - 2 Hours.
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 numbertype
represented the purpose of the image, for exampleweb
,cron
os
represented the os version string, for example Debianbuster
(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:
- Browse to your old
helpdesk-install
deployment directory. -
Copy the value of the
COMPOSE_FILES
variable fromMakefile
. For example given:
The copied value would be:COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.override.yml
-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.override.yml
- In the copied value, replace
docker-compose.override.yml
withdocker-compose.https.yml
-
Replace
COMPOSE_FILES
with the copied value in the command below and run:docker compose COMPOSE_FILES down -v
- Browse to your old
-
Initialise the new containers:
- Browse to your old
helpdesk-install
deployment directory. -
Copy the entire
COMPOSE_FILES
line fromMakefile
. For example:COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.override.yml
-
In the copied value, replace
docker-compose.override.yml
withdocker-compose.https.yml
-
Paste the copied value at the top of the
Makefile
within your new deployment directory (created earlier bysetup.sh
). For example,COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.https.yml include Makefile.dist include .env
-
From your old deployment directory, copy over your database secrets and SSL certificates from
ssl/
andsecrets/
directories. -
Remaining within the new deployment directory, run:
make start
- Browse to your old
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 templates and 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.
/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
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 theweight
option with descending direction (the strongest weight first).