RT 5.0.6 Documentation


Go to latest version →

UPGRADING FROM RT 4.4.0 and greater

The 5.0 release is a major upgrade and as such there are more changes than in a minor bugfix release (e.g., 4.4.0 to 4.4.1) and some of these changes are backward-incompatible. The following lists some of the notable changes, especially those that might require you to change a configuration option or other setting due to a change in RT. Read this section carefully before you upgrade and look for changes to features you currently use.

See devel/docs/UPGRADING-5.0 for internals changes relevant to extension writers, including deprecated code.

Upgrading Recommendations

RT now defaults to a database name of rt5 and an installation root of /opt/rt5.

If you are upgrading, you will likely want to specify that your database is still named rt4 or even rt3. Alternatively, you could import a backup of your database as rt5 to conform to the new default, although this isn't required.

Upgrading to RT 5 over an existing RT 4 installation (/opt/rt4) is not recommended and will almost certainly cause issues. Instead, do a fresh install into /opt/rt5 (or your custom location) for the code portion of the upgrade. Then import your existing database and run the database upgrade steps using make upgrade-database.

We recommend this approach because of the large number of changes to the code base for this major release. We moved some things to new locations and old files are not removed as part of the upgrade process. These old files will still be detected by RT in some cases and will cause issues.

Installing a fresh code base will also allow you to evaluate your local modifications and configuration changes as you migrate to 5.0. If you have changes made directly to the RT code, it's a good time to look at the hooks RT provides for custom code in extensions or in the local directory. See docs/writing_extensions.pod for more information.

Database Changes

Notable Changes

Extensions Integrated into RT 5

The following extensions are now part of RT 5. If you previously used any as an extension, you no longer need the extension after upgrading and can remove the Plugin line from your RT configuration.

Changes you may need to apply if you previously used the extension are described below.


If you previously used RT::Extension::ConfigInDatabase as an extension, run the etc/upgrade/upgrade-configurations utility after completing all the other upgrade steps from the README. This will migrate your existing configuration to the new core RT tables.


If you previously used numbers for priority and would like to continue to do so, you can set the new $EnablePriorityAsString option to false. That will disable the new string-based display.

We also now hide Final Priority by default, but if you previously used it and would like to continue to do so, you can add this to the Custom CSS section on the Theme editor:

    .FinalPriority, .TicketFinalPriority {
        display: flex;
    .priority div.value .current-value {
        visibility: visible;
    .priority div.value .current-value .FinalPriority {
        display: inline;

If you would like to now use strings for priority like Low, Medium, High, check the new %PriorityAsString configuration option. RT provides a simple default setting that may be sufficient. Set new values if you would like to customize your priority options.

If you were previously using the PriorityAsString extension, you no longer need the extension installed. The %PriorityAsString> configuration is simplified and consolidated, so check the documentation for details on updating your previous configuration.


The configuration option $AssetSQL_HideSimpleSearch is now $AssetHideSimpleSearch. The configuration option $AssetSearchFormat is now $AssetSimpleSearchFormat.

See the configuration documentation in RT_Config.pm for new configuration options added for AssetSQL and the new asset query builder.


If you previously used RT::Authen::Token as an extension, run the etc/upgrade/upgrade-authtokens utility after completing all the other upgrade steps from the README. This will migrate your existing tokens to the new core RT tables.




This section duplicates upgrading notes for changes included in RT 4.4.5 and RT 5.0.2. These changes are duplicated here for users upgrading from RT 5.0.0 or 5.0.1 who won't run the RT 4.4.5 upgrade.




Update Messages Changed for Consistency

Some parts of RT, notably Bulk Update, previously could show update messages like:

    Ticket 123: Ticket 123: Status changed from 'new' to 'open'

This is fixed in RT 5.0.5. As part of this fix, some JSON responses sent for REST 2 operations are also updated. For example, an Article update message is changed:

    Old: Article More updates using REST: Name changed from...
    New: Article 123: Name changed from...

If you have any automation using REST 2 that checks these JSON response messages, you may need to update your system to match the new format.


Ticket Owner Updates and Notifications

When processing ticket updates, RT previously processed the reply/comment before processing other ticket updates, including owner changes. For RTs configured to send email to some users only when they are the ticket owner, this processing order resulted in new owners not seeing the reply/comment associated with the update that made them the new owner. This could cause confusion, especially if the reply/comment included information specifically addressed to the new owner.

To fix this issue, owner changes are now processed before messages, so new owners will now see the message associated with the change that made them owner.

This will result in new email being sent when it wasn't previously. We believe this fixes the previous incorrect behavior. However, if you relied on this behavior, and don't want the new email, you may need to modify your scrip configurations.

Spreadsheet (TSV) Download Format

The format of some column headers in spreadsheets (TSV files) downloaded from ticket search results has been updated. Specifically custom fields and custom roles no longer show "CustomField.{}" or "CustomRole.{}" in the header. Also, multi-word headers like "EmailAddress" now have spaces added so the header will appear like "Email Address".

This should make headers more readable, but if you have any automated processes that parse the headers, you will need to update your parsing code.

Running RT with MariaDB and MySQL 5.7

RT uses the perl module DBD::mysql to connect to MySQL-type databases, and before version 5.001, it worked with older MySQL versions like 5.7, newer versions like 8, and all versions of MariaDB. Starting with DBD::mysql 5.001, it supports only MySQL 8 and newer.

To align with this change, RT's configure script now has two new options available for --with-db-type. To run with MySQL 5.7 or older, use mysql5. To run with MariaDB, use MariaDB. These will configure the installer to use an older, compatible version of DBD::mysql.

If you install a newer version of DBD::mysql by mistake, you can uninstall it or manually force install a version older than 5.001.

Unlimited Option in SearchResultsPerPage Configuration

RT 5.0.4 added @SearchResultsPerPage as a configuration option to allow admins to control the options presented in the "Rows per page" dropdown in the Query Builder. When it was added, the "Unlimited" option was automatically added to the list of options configured. This prevented admins from removing the "Unlimited" option from the list, so this has been updated in RT 5.0.6 to use the configured options only with no other options added automatically.

If you previously set a custom @SearchResultsPerPage and you want to keep the "Unlimited" option, update your configuration and add "0" to your list.

← Back to index