• UPGRADING FROM RT 4.4.0 and greater
  • Upgrading Recommendations
  • Database Changes
  • Notable Changes
  • Extensions Integrated into RT 5
• UPGRADING FROM 5.0.0 AND EARLIER

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

• For MySQL and MariaDB, the default character set has been updated to utf8mb4 to accommodate more unicode characters including emojis. See README.MySQL and README.MariaDB for details.

• The Id field in some tables is changed from INT to BIGINT to accommodate large RT systems that may hit the maximum number of ids. Because this change touches large RT tables like Transactions and Attachments, this upgrade step may take a while to run.

  You also will need free disk space equal to the size of these tables while running because MySQL, MariaDB, and Postgres will create a temporary copy of the table while running. If you don't have sufficient space, it can cause this step to fail.

Notable Changes

• System configuration options can now be changed by SuperUsers via the web UI. File-based configuration options are still loaded. Changes made via the web UI take precedence over file-based options if both are set.

  If you prefer to keep all configuration in files and disable editing in the web UI, set this option to 0:

      Set($ShowEditSystemConfig, 0);

• The variables which alter the set of HTML elements allowed in HTML scrubbing have moved; they have been renamed, and are now found under RT::Interface::Web::Scrubber.

• The articles interface on tickets has been simplified, now showing only a dropdown for selecting articles. This dropdown converts to an autocomplete box when the dropdown contains more than $DropdownMenuLimit items.

  With this simplified interface, the "hotlist" feature is no longer needed as all articles in classes applied to a given queue are available in the dropdown/autocomplete field. To prevent articles in a class from appearing for a queue, you can unapply the class from that queue.

  The upgrade steps remove the hotlist configuration from your RT database by removing that column from the Articles table. Since the article class must be applied to a queue for the hotlist items to appear, all articles should continue to appear in the new interface.

• The updated rich text editor now shows the browser context menu (right-click menu) by default, so the MessageBoxUseSystemContextMenu configuration option is no longer needed and has been removed.

• Dashboards previously in the Home menu have been moved to the Reports menu. The reports previously in the Reports menu are still there, but you can now edit the Reports menu like the previous Home menu, so you can remove the default reports if you like.

  All other dashboard menu functionality should be the same including editing your own menu, the global settings, and setting a user's menu from the user admin page for that user.

• Accessing RT from a mobile device no longer defaults to the mobile-optimized interface. RT 5.0 is fully responsive so the full UI can be used on mobile devices. Set the configuration option $ShowMobileSite to true to restore the previous behavior.

• RT can now run with GnuPG 2.2. On install or upgrade, it requires the updated version of GnuPG::Interface. make testdeps will test for the correct version. RT should also still run with GnuPG 1.4.x. It is not supported for GnuPG versions 2.0 or 2.1. On some Linux systems, you may need to add a new repo to get an updated GnuPG package with some version of 2.2.

• RT search results now allow inline editing of ticket metadata, greatly improving usability and convenience. Editable fields are now the default for most ticket fields in search results.

  The ticket Owner field sometimes requires extra work to build and can result in slower page load times, so the default Owner format is read-only. To enable inline edit for Owner, update your search to use the format OwnerNameEdit.

  If you experience slower page loads with OwnerNameEdit, you can display Owner as an autocomplete box rather than a dropdown using the AutocompleteOwners configuration option. This may also help other areas of RT in addition to searches.

  We are investigating options to improve the underlying queries. Some users have reported improved performance with the following indexes, at least on Postgres:

     CREATE INDEX ACL2 ON acl (objecttype, objectid);
     CREATE INDEX ACL3 ON acl (principalid, rightname, principaltype);

  We are performing testing and looking for additional feedback before adding these to default RT.

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.

RT::Extension::QuoteSelection

RT::Extension::RightsInspector

RT::Extension::ConfigInDatabase

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.

RT::Extension::CustomRole::Visibility

RT::Extension::PriorityAsString

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.

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.

RT::Extension::AssetSQL

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.

RT::Extension::LifecycleUI

RT::Extension::REST2

RT::Authen::Token

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.

UPGRADING FROM 5.0.0 AND EARLIER

• The extension RT::Extension::FormattedTransaction was added to core. This adds a new RT dependency on the perl module Text::WordDiff, so you will be prompted to install this new module if your system doesn't have it.

• Similar to the note above regarding the Owner field in search results, custom fields in search results also now have inline edit enabled by default, allowing you to change values directly in search results.

  For heavy search result pages with many columns display or many rows, page loads may be slower with this inline edit mode enabled. If you don't need to edit custom field values, you can change search result columns from CustomField.{Foo} to CustomFieldView.{Foo}. That column will then load a view-only field which may improve page load speed.

• In the self service interface, the "Search Articles" box in the menu bar previously was displayed to users who had the global right "ShowArticle". This is now controlled by a new configuration option $SelfServiceShowArticleSearch. This new option defaults to off, so if you currently allow self service users to use article search, enable this option to keep the article search box available.

• System-level saved searches can now be displayed on the RT at a glance page. Previously some users saw errors like:

      Either you have no rights to view saved search system-SavedSearch-34
      or identifier is incorrect

  If you are still seeing that error after updating to RT 5.0.1, edit the page, remove the saved search, save, then add it back again. After saving again, it should appear as expected.

• The System Configuration editor (Admin > Tools > System Configuration > Edit) now uses JSON rather than Perl syntax to represent arrays and hashes. Be sure to enter valid JSON if you wish to modify an array- or hash-valued configuration setting.