SupportPal Docs

Upgrading to 5.0 from 4.2

SupportPal 5.0 is a major release with some breaking changes. The focus of this release is around improving the...

Contents

What's New?

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

New System Requirements

Please ensure your server meets the server requirements before trying to upgrade.

Important Changes

SLA Plan Escalation Rules
The due time for the next reply to the ticket and for its resolution are now shown separately. Escalation rules can now specifically target either the reply due time or resolve due time being breached - see SLA Plans for a description of the new functionality. To maintain backwards compatibility, when upgrading all existing escalation rules will be duplicated to run in both scenarios.

We strongly advise to review your SLA plan escalation rules post-upgrade.

Removed Commands
The app:backup, app:restore, app:update commands must now be called from the app-manager path, as shown below. They have been deprecated since 4.2.0 and will no longer work as of this release. 


    php app-manager/artisan app:backup
    php app-manager/artisan app:restore
    php app-manager/artisan app:update

Email Driver
The php-imap email driver has been removed completely from this release and is no longer an optional PHP requirement of the system. Horde has been the default email driver since SupportPal 3.2.0 due to additional features such as OAuth support, no changes should be necessary.

Memcached Support Removed
Memcached is no longer supported as a cache driver. We recommend to switch to the Redis cache driver instead.

Reports
The reports covering first response time and time to resolution require some data to be generated and stored in the database in the background. This is done shortly after the upgrade has completed, so these reports may be missing data until this has finished.

Report endpoints removed from API
The /api/reports and /api/report/{category}/{name} end points have been removed. We recommend to make use of the export functionality built-in to the report dashboards.

Docker Deployment Changes

AWS Elastic Beanstalk

We are no longer maintaining our pre-built Elastic Beanstalk configurations from the supportpal/helpdesk-install repository and as such they have been removed. If you're using those configurations, you're welcome to continue but will need to maintain them yourself.

Monolithic Deployments

Important: HTTP/HTTPS changes

The default value of the HTTPS_ENABLED environment variable has been changed to 0. This is to prevent unnecessary requests to the certificate authorities when SSL connections are not required. If your help desk permits SSL (HTTPS) connections you must now enable the HTTPS_ENABLED environment value. Follow configuring Free SSL for guidance, and make these files changes before upgrading to v5.

Recommended: Cron MAILTO Directive

We recommend to add [email protected] to your .env file. This will now notify you via email if there are any issues processing the cron job.

Compose Deployments

Documentation for deployments using the github://supportpal/helpdesk-install/templates/docker-compose repository has moved. It can now be found in the .md files within the aforementioned repository directory.

Config File Changes

config/email.php
The following configuration options have been removed:

config/trustedproxy.php
The following configuration options have been removed:

Email Template Changes

As part of changes to the email verification system, a number of email templates have been updated. The upgrader will automatically attempt to update the email templates if they have not been modified. The full list of changes can be found below.

User - Account confirmation

This email template has been renamed to "Account verification".

 Dear {{ user.formatted_name }},<br>
 <br>
 Thank you for registering an account at our help desk.<br>
 <br>
-To finish the activation process, please confirm your email address by clicking the link below:<br>
+To finish the activation process, please verify your email address by clicking the link below:<br>
-<a href="{{ confirmation_link }}">{{ confirmation_link }}</a><br>
+<a href="{{ verification_link }}">{{ verification_link }}</a><br>
 <br>
 The above link will be valid for the next 24 hours. If you do not activate the account in time, you may re-register at the help desk at any time.<br>
 <br>
 Kind Regards,<br>
 <strong>{{ brand.name }}</strong>

User - Added as new organisation user

This email template has been renamed to "Organisation invitation".

 Dear {{ user.formatted_name }},<br>
 <br>
-An account has been created for you at our support help desk by {{ owner.formatted_name }}, you will have access to tickets that have been opened by {{ owner.formatted_name }}. To finish the activation process, please confirm your email address by clicking the link below:<br>
+You have been invited by {{ owner.formatted_name }} to join {{ organisation.name }}.

-<a href="{{ confirmation_link }}">{{ confirmation_link }}</a><br>
+<a href="{{ invitation_link }}">Accept Invitation</a><br>
-<br>
-The above link will be valid for the next 24 hours. If you do not activate the account in time, you may re-register at the help desk.<br>
 <br>
 Kind Regards,<br>
 <strong>{{ brand.name }}</strong>

User - Confirm new email address

This email template has been renamed to "Verify new email address".

 Dear {{ user.formatted_name }},<br>
 <br>
-If you made this change, please confirm your new email address by clicking the link below:<br>
+If you made this change, please verify your new email address by clicking the link below:<br>
-<a href="{{ confirmation_link }}">{{ confirmation_link }}</a><br>
+<a href="{{ verification_link }}">{{ verification_link }}</a><br>
 <br>
 The above link will be valid for the next 24 hours. If you do not activate the account in time, you may re-register at the help desk.<br>
 <br>
 Kind Regards,<br>
 <strong>{{ brand.name }}</strong>

User - New account details

 Dear {{ user.formatted_name }},<br>
 <br>
 We just set up an account for you at our help desk. All you need to do now is set a password, it only takes a few seconds.<br>
 <br>
 Click the below link to get started:<br>
-<a href="{{ confirmation_link }}">{{ confirmation_link }}</a><br>
+<a href="{{ verification_link }}">{{ verification_link }}</a><br>
 <br>
 The above link will be valid for the next 7 days. If you do not activate the account in time, you may re-register at the help desk at any time.<br>
 <br>
 Kind Regards,<br>
 <strong>{{ brand.name }}</strong>

User - Password reset

 Dear {{ user.formatted_name }},<br>
 <br>
-We received a request to reset your password at our help desk, please confirm your email address by clicking the link below, after which you will be able to set a new password:<br>
+We received a request to reset your password at our help desk, please verify your email address by clicking the link below, after which you will be able to set a new password:<br>
-<a href="{{ confirmation_link }}">{{ confirmation_link }}</a><br>
+<a href="{{ verification_link }}">{{ verification_link }}</a><br>
 <br>
 The above link will be valid for the next 24 hours. If you did not make this request, please inform our support team.<br>
 <br>
 Kind Regards,<br>
 <strong>{{ brand.name }}</strong>

Operator - Password reset

-A request has been made to reset the password for your help desk operator account, please confirm your email address by clicking the link below, after which you will be able to set a new password:<br>
+A request has been made to reset the password for your help desk operator account, please verify your email address by clicking the link below, after which you will be able to set a new password:<br>
-<a href="{{ confirmation_link }}">{{ confirmation_link }}</a><br>
+<a href="{{ verification_link }}">{{ verification_link }}</a><br>
 <br>
 The above link will be valid for the next 24 hours. If you did not make this request, please inform an administrator.

Operator - User export ready

 An export you requested has been processed and is now ready for download:<br>
-<a href="{{ download_url }}">{{ filename }}</a><br>
+<a href="{{ download_url }}">{{ filename }}</a>
-<br>
-If you need to delete the export or request a new one, you can do so from the edit user page as linked below. A list of previous exports will also be available.<br>
-<a href="{{ edit_url }}">{{ edit_url }}</a>

There are also two new email templates:

Development Changes

Framework

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

  1. 8.x to 9.x
  2. 9.x to 10.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.

Database and Queries

To support sql_require_primary_key in MySQL and innodb_force_primary_key in MariaDB, we have added an id column to all membership/pivot tables. This may impact your customisations such as reports or add-ons if they use join queries. For example, a join query without a table name may now throw an ambiguous column error. 


-Upload::leftJoin('email_log_raw', 'email_log_raw.upload_id', '=', 'id');
+Upload::leftJoin('email_log_raw', 'email_log_raw.upload_id', '=', 'upload.id');

Similarly, a join query that selects an id column without specifying the table name may now return the id belonging to the joined table. This case needs to be carefully reviewed as it will not throw an error. 


-Upload::leftJoin('email_log_raw', 'email_log_raw.upload_id', '=', 'upload.id')->pluck('id');
+Upload::leftJoin('email_log_raw', 'email_log_raw.upload_id', '=', 'upload.id')->pluck('upload.id');

Reports

The report framework has been replaced in this version and old reports will no longer function. Due to the differences in the frameworks, it is not possible to migrate old reports. You must develop new reports following our Report Development guide.

Add-ons

There are some breaking changes to be aware of if you use Form Requests or API Controllers/API Route Files within your add-ons.

Web Requests

The following Request classes have been renamed:

If your add-on uses Form Requests, you will need to update the class it extends:

Requests/SettingsRequest.php

    <?php

    namespace Addons\Plugins\HelloWorld\Requests;

    use App\Http\Requests\FormRequest;
    use Lang;

    class SettingsRequest extends FormRequest
    {
        ...
Web Controllers - Views

The \TemplateView::other function has been deprecated and replaced with \TemplateView::operator, all instances should be updated as it will be removed in a future major release. 


-return \TemplateView::other('Plugins#TimeTracking::settings')
+return \TemplateView::operator('Plugins#TimeTracking::settings')

There is a new \TemplateView::frontend function available for returning frontend views.

API Requests
API Controllers

The library which we used to handle API requests has been removed in favor of core Laravel functionality. As such, the Dingo\Api\Routing\Helpers trait no longer exists.

Controllers/ApiController.php

    <?php

    namespace Addons\Plugins\HelloWorld\Controllers;

    use App\Modules\Core\Controllers\BaseApiController;

    class ApiController extends BaseApiController
    {
        public function foo()
        {
            return response()->json([
                'status' => 'success',
                'data'   => 'foo',
            ]);
        }
    }
API Exceptions

Exceptions in the \Dingo\Api\Exception namespace have been removed. The following new exceptions are available:

All other exceptions should be replaced by throw new \Symfony\Component\HttpKernel\Exception\HttpException($code, 'message');

API Route Files

The $api variable no longer exists and $router should be used as found in the other route files.


-$api->version('v1', ['namespace' => 'Addons\Plugins\TimeTracking\Controllers\Api'], function ($api) {
+$router->group(['namespace' => 'Addons\Plugins\TimeTracking\Controllers\Api'], function ($router) {

All further references of $api should be replaced with $router in the file too.