SupportPal Docs

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.

Contents

Estimated Upgrade Time: 1 - 2 Hours.

What's New?

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

New System Requirements

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 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:

  1. version represented the SupportPal version number
  2. type represented the purpose of the image, for example web, cron
  3. 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:

  1. Open a bash compatible terminal. If you're on Windows, use Git Bash.
  2. Take a full backup.
  3. 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
  4. 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.
  5. 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
  6. 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 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:

  1. 6.x to 7.x
  2. 7.x to 8.x

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

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.

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