You're browsing the documentation for an old version of SupportPal. Consider upgrading to the [latest version](https://docs.supportpal.com/current/Documentation+Home). 

# Upgrading to 2.2 from 2.1

SupportPal 2.2.0 is a major update, adding mutli-lingual functionality and time tracking support, amongst many other new features and improvements.

  This upgrade guide is aimed at those upgrading from the last stable version (2.1.2) to 2.2.0. Upgrading from an earlier version is possible, but there may then be more important and breaking changes than listed below. 

**Estimated Upgrade Time: Less Than 1 Hour.**

  **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). 

## What's New?

View the [2.2 Release Notes](2.2+Release+Notes) for the new features and improvements in this series.

## New Requirements

Please make sure your server meets the below new [system requirements](System+Requirements) before beginning the upgrade:

- The licensing client now uses HTTPS (SSL) to connect with our licensing server, therefore your firewall must allow outbound port 443 access to licensing.supportpal.com

## Upgrading Database

Several indexes have been added to the database in order to improve the performance of some SQL queries. Due to this change, the upgrade script may be slow so we recommend to read through the below before continuing:

### Disable Server-side Timeouts

We recommend that you disable server-side timeouts within your web server, PHP and MySQL configurations before beginning the SupportPal 2.2.0 in-browser upgrade process.

Please ask your server administrator or hosting provider for more details on what settings are appropriate to disable for your server environment. We suggest the following PHP configuration:

- `<a href="http://php.net/manual/en/info.configuration.php#ini.max-execution-time" target="_blank">max_execution_time</a> = 0`
- `<a href="http://php.net/manual/en/filesystem.configuration.php#ini.default-socket-timeout" target="_blank">default_socket_timeout</a> = 36000`
- `<a href="http://php.net/manual/en/mysql.configuration.php#ini.mysql.connect-timeout" target="_blank">mysql.connect_timeout</a> = -1`

### Manual Upgrade

If you can't disable server-side timeouts or prefer to manually execute SQL queries, below we have provided an SQL file that you can run against the database. The SQL file contains all of the database migrations that *may* take significant time to execute, to make use of the file please follow the below steps:

1. Upload and extract the 2.2.0 zip file
2. Download and manually run the following SQL script against your database:  
     [ 2.2.0\_migrations.sql ](https://docs.supportpal.com/build/assets/2.2.0_migrations-D4KADV_U.sql)
3. Proceed with the usual SupportPal upgrade by browsing to http://support.yourdomain.com/upgrade

## Template Changes

  This section is only relevant if you've modified either your frontend or operator panel template. 

This release has a large number of breaking template changes to both the frontend and operator panel templates. We always recommend to apply all the template changes ([frontend](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24), [operator panel](https://github.com/supportpal/supportpal-resources/commit/66e8de54d9de3bf97a919bfaa419e7c580b15eb6)) to your custom templates to ensure that they continue to function properly, however below is a list of breaking changes (linked to our resources repository with the diff) where updating the template is essential.

### Frontend

- [assets/frontend/css/redactor.css](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-43fb06cbec7c37115add7e665c66ac89 "assets/frontend/css/redactor.css") - New UX for textarea custom fields (lines 76-100).
- [assets/frontend/js/main.js](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-96cda2b81a374fcecd04c2f3993486a6 "assets/frontend/js/main.js") - Changing the language and redirecting to the right URL (lines 17-18 and 22-29).
- [assets/frontend/js/ticket.js](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-8a00a105a17e5e85ce826ef867431285 "assets/frontend/js/ticket.js") - Loading in the full message (line 34).
- [templates/frontend/default/core/dashboard.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-cf78108db43f249f3f3bc38140e50ea9 "templates/frontend/default/core/dashboard.twig") - Showing the track ticket option based on channel settings (line 26).
- [templates/frontend/default/footer.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-297780b440276dcd18849bf39dde86cd "templates/frontend/default/footer.twig") - Changing the language and redirecting to the right URL (lines 4-12).
- [templates/frontend/default/forms/customfields.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-a16f51b30bf59e0a6d210bc139de0ea5 "templates/frontend/default/forms/customfields.twig") - New UX for textarea custom fields (line 9).
- [templates/frontend/default/selfservice/article.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-31b1b162276f2e8a8430fa16dcb2cfb5 "templates/frontend/default/selfservice/article.twig") - New attachment fetching function name (lines 68 and 71).
- [templates/frontend/default/selfservice/comment.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-174bafe00a731546042cfd992e808811 "templates/frontend/default/selfservice/comment.twig") - Showing comment text (line 26).
- [templates/frontend/default/sidebar.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-071d93c0bdee7717a7d9d753f1fca62d "templates/frontend/default/sidebar.twig") - Changing the language and redirecting to the right URL (lines 72-80).
- [templates/frontend/default/ticket/entire\_message.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-b5db6e2018521bdcfb1041a71cbccecf "templates/frontend/default/ticket/entire_message.twig") - Showing ticket message text (line 45).
- [templates/frontend/default/ticket/feedback.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-4a72796e900e26b8e8d4af5d7c110834 "templates/frontend/default/ticket/feedback.twig") - New UX for textarea custom fields (lines 34-37).
- [templates/frontend/default/ticket/forms/newticket\_step3.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-74780c2e269c41a8f9281ab0672c76b0 "templates/frontend/default/ticket/forms/newticket_step3.twig") - Showing the captcha/article suggestions based on channel settings and new UX for textarea custom fields (lines 144, 164 and 192).
- [templates/frontend/default/ticket/message.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-bc9a68b6496e978cdaff14344ae57509 "templates/frontend/default/ticket/message.twig") - Showing ticket message text and new attachment URL (line 21 and 29).
- [templates/frontend/default/ticket/ticket.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-a94abcff9b30fcbaa8738d1260fc16f4 "templates/frontend/default/ticket/ticket.twig") - New attachment download code and new UX for textarea custom fields (lines 3-8 and 198).
- [templates/frontend/default/user/organisation.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-639524d16eb7e3a790048dd16cc3eff3 "templates/frontend/default/user/organisation.twig") - New UX for textarea custom fields (lines 157-160).
- [templates/frontend/default/user/organisation\_add.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-b0cc0a2df4a6f267b65fa258c63f1366 "templates/frontend/default/user/organisation_add.twig") - New UX for textarea custom fields (lines 30-34).
- [templates/frontend/default/user/profile.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-0db2beb32ca028ba354eaf95e55ef86e "templates/frontend/default/user/profile.twig") - New UX for textarea custom fields (lines 31-35).
- [templates/frontend/default/user/register.twig](https://github.com/supportpal/supportpal-resources/commit/95869cf23d342255e1b31d44f274802a5c005f24#diff-3b6e9010465242f99d098f40583adc74 "templates/frontend/default/user/register.twig") - New UX for textarea custom fields (lines 45-49).

### Operator Panel

The operator panel requires copying all [changes](https://github.com/supportpal/supportpal-resources/commit/66e8de54d9de3bf97a919bfaa419e7c580b15eb6) as the majority of them have been made to support multi-lingual features.

## Email Template Changes

The upgrader will attempt to automatically update the email templates if they've not been modified, but this section is still relevant if it mentions it was unable to update or you've added a translated version of a template listed below.



A new setting has been introduced to only send attachments in emails that are above the set size to avoid potential memory issues, the default value for this is '`10M`'. As part of the change, we have updated our default email templates to include links to download attachments in case they are not attached in the email.

Below is a list of default email templates affected, split by section, and the new code that needs to be copied in to them. You will also need to apply the changes to your own custom email templates depending on where they are used and who they are targeted to. The email template name has been given with the ID in brackets, the ID should be seen in the URL when you go to edit it.

### User

- New ticket reply (2)
- New ticket opened (3)
- Waiting for your response (11)
- Ticket closed due to inactivity (13)
- Ticket closed by operator (20)

View the HTML source of the template (click `<>`, the first icon, in the editor toolbar) and insert the following code on a new line after `{{ message.text }}`.

```

    {% if not message.attachments.isEmpty() %}
        <div style="padding-top:15px;">
            <span style="color:#999;font-size:12px;text-transform:uppercase;">Attachments</span>
            {% for attachment in message.attachments %}
                <div style="background:#f5f5f5;margin-top: 2px;padding:5px 12px;">
                    <a href='{{ attachment.frontend_url }}'>{{ attachment.original_name }}</a>
                    &nbsp;<span style="color:#999;">({{ attachment.upload.size }})</span>
                </div>
            {% endfor %}
        </div>
    {% endif %}

```

### Operator

- Assigned operator to ticket (1)
- New ticket opened (4)
- New ticket reply (5)
- New internal ticket opened (18)
- Ticket department changed (19)
- Operator replied to ticket (23)
- Operator added a ticket note (24)

View the HTML source of the template (click `<>`, the first icon, in the editor toolbar) and insert the following code on a new line after `{{ message.text }}`. There will be two cases of this in all of the templates.

```

    {% if not message.attachments.isEmpty() %}
        <div style="padding-top:15px;">
            <span style="color:#999;font-size:12px;text-transform:uppercase;">Attachments</span>
            {% for attachment in message.attachments %}
                <div style="background:#f5f5f5;margin-top: 2px;padding:5px 12px;">
                    <a href='{{ attachment.operator_url }}'>{{ attachment.original_name }}</a>
                    &nbsp;<span style="color:#999;">({{ attachment.upload.size }})</span>
                </div>
            {% endfor %}
        </div>
    {% endif %}

```

## Plugin Changes

  **Backwards compatibility**  
 Please ensure any custom plugins and widgets that you have written use the `plugin.php` and `widget.php` route file names respectively. 

Prior to SupportPal 2.2 any plugin route files were protected by operator authentication and the permissions system. In 2.2 you can now use specific filenames, to associate the routes within the file with a specific middleware group:

   Filename Attributes   `frontend.php` Protected by frontend authentication, and maintenance warning system   `operator.php` Protected by operator authentication   `settings.php`, `plugin.php`, `widget.php` Protected by operator authentication and plugin / widget permissions.  Any file within the `Routes` directory that does not match the above list does not have any attributes imposed i.e. routes are unauthenticated, outside of the permissions system and so on.

## Configuration File Changes

The following configuration items have moved files; if you're currently using or have modified any of these please update the new configuration file to avoid losing the change.

- Below `/config/app.php` items have moved to `/config/email.php`: 
    - `toggle_quotes`
    - `macro_start_char`
    - `macro_end_char`
- Below `/config/app.php` items have moved to `/config/mail.php`: 
    - `delimiter`

## Other Important Changes

- **Report URLs** - The operator panel report URLs now support spaces and other characters (slug-friendly). This means that existing URLs may have changed (any uppercase characters are now lowercase). If you're using the URLs anywhere, please make sure to update them.
- **Conditions** - The conditions system has been reworked to perform better. As part of this, there are a few changes to how existing conditions work: 
    - The ticket message content option now only has a 'contains' option, if you used 'begins with', 'ends with' or 'does not contain', these will all be updated to 'contains' on updating. On MySQL 5.6+, it will now use FULL TEXT search to search messages, similar to how the operator search works.
    - Ticket tag and operator assigned group 'is not' condition now fetches tickets that do not contain any tags/assigned operators.
- **Ticket grid counts** - The ticket counts in the sidebar on the ticket grid now only include non-resolved tickets for the given filter or item.