• UPGRADING FROM RT 5.0.0 and greater
  • Upgrading Recommendations
  • Database Changes
  • Notable Application Changes
  • Extensions Integrated into RT 6

UPGRADING FROM RT 5.0.0 and greater

The 6.0 release is a major upgrade and as such there are more changes than in a minor bugfix release (e.g., 5.0.1 to 5.0.2) 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-6.0 for internals changes relevant to extension writers, including deprecated code.

Upgrading Recommendations

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

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

Upgrading to RT 6 over an existing RT 5 installation (/opt/rt6) is not recommended and will almost certainly cause issues. Instead, do a fresh install into /opt/rt6 (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 6.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

• Add a notable DB change here.

Notable Application Changes

• RT now uses a library called htmx, which makes AJAX much easier and allows us to completely change the way pages, components, and widgets load and update in RT. You'll see the difference on just about every page in RT starting immediately with the home page. This update gives RT a much more interactive feel and speeds up nearly every interaction.

• RT's sessions have been refactored to be non-blocking to accommodate the change to htmx noted above. Because different parts of the page can now be loaded in parallel, sessions needed to be updated to not expect a single page load.

  This change should be transparent, but may impact custom code.

• Saved searches can now be configured to automatically refresh, independent of the page and other portlets. If you currently use the Refresh feature to reload your entire home page, you can now update your saved search options to refresh each search individually instead. And each search can have a different refresh interval. The user experience is much nicer, and it puts less load on your RT server.

  Each saved search in a dashboard also has a Reload icon you can use to manually reload just that search. If you want to reload only when you are reviewing a search for updates, this new button may work well.

  The Refresh portlet still displays if you have it on your homepage dashboard, but it no longer refreshes the page. It now displays a message explaining the updates to saved searches and how to set the refresh interval there.

  The Refresh option on the search results page has also been removed for the same reason. If you have a search that you want to refresh regularly, create a dashboard with that search and set the refresh on the search.

  The corresponding HomePageRefreshInterval and SearchResultsRefreshInterval configuration options have also been removed.

• The Quick Create portlet has been updated to use htmx, so it creates tickets without a full page reload. It also now supports adding custom fields with configuration, allowing you to add required custom fields. Add custom fields using the %CustomFieldGroupings option.

• Ticket create, display, and update pages, and asset create and display pages are now completely configurable using a new feature called Page Layouts. You can create and save new page layouts, arranging widgets on the page however you want. You can then apply these configurations to your Queues and Catalogs on the respective administration pages.

• Because of the new Page Layouts feature, the UseSideBySideLayout configuration is no longer needed. This option was previously enabled by default and a two column page layout is available. A page layout called "One Column" is also available if you had disabled UseSideBySideLayout and prefer a single-column layout.

  This option was also available as a user-level preference and we don't (yet) have user-level page layouts. If you prefer a single column layout, for now you can appeal to your RT admin to set up your queues with "One Column" or something similar.

• Saved searches, dashboards, and dashboard subscriptions have been refactored to use their own database tables (instead of "Attributes"). Previously removing them required you to delete them completely, now you can disable them instead.

  This also allowed us to create some new pages for seeing and managing Dashboards and Saved Searches. As a SuperUser, you will now see Admin > Global > Dashboards/Saved Searches. On the user admin page, you can see Dashboards and Saved Searches for each user, and there is a corresponding page for each group as well.

  Related rights have also been tweaked:

  • SeeSavedSearch/SeeDashboard and AdminSavedSearch/AdminDashboard are to see and manage *global* saved searches and dashboards.

  • SeeGroupSavedSearch/SeeGroupDashboard and AdminGroupSavedSearch/AdminGroupDashboard are to see and manage *group* saved searches and dashboards.

  • SeeOwnSavedSearch/SeeOwnDashboard and AdminOwnSavedSearch/AdminOwnDashboard are to see and manage user's *own* saved searches and dashboards.

  Since default saved searches (My Tickets, Unowned Tickets, and Bookmarked tickets) now are plain system saved searches, we grant all privileged users SeeSavedSearch so they can see these searches as before.

  When testing your upgrade, we encourage all users to check access to dashboards and saved searches to confirm rights are still set correctly. Note that these rights apply to seeing and accessing just the configured dashboards and saved searches themselves. Rights to see the contents of the searches, like tickets and assets, are defined separately and should not be effected by these changes.

• Simple search (the default search box on the top of the page) now searches subjects and descriptions. It also searches ticket content, and custom field values when you enable full-text search indexes.

  Full-text search on ticket content has been available in RT since RT 4.0. However, the default simple search previously excluded the ticket subject because it interfered with the full-text index. This is now updated, so default searches now include subject and the full-text index is still used.

  You can now also search in custom field content by default if you enable full-text search for custom fields. Enabling it is similar to full-text search for ticket content. If you already have full-text indexes enabled for ticket content, you can run sbin/rt-setup-fulltext-index with the --cf-only option to add custom field indexing.

      sbin/rt-setup-fulltext-index --cf-only

  Then update your %FullTextSearch configuration according to the output of above command. See docs/full_text_indexing.pod for details.

  As part of these updates, RT 6 removes support for Sphinx indexing on MySQL. Sphinx support was added before MySQL had native full-text search. All of the databases supported by RT now have native full-text search and that is the recommended configuration for full-text indexes.

• While it has been possible to use JSChart to generate chart images in the RT UI, because these images are generated client-side it hasn't been possible to include them in dashboard emails.

  It is now possible to use the optional Perl module WWW::Mechanize::Chrome and a compatible server-side web browser to create images of the JSChart graphs for inclusion in emails.

  This is accomplished by setting $EmailDashboardIncludeCharts to '1' and maybe also setting $ChromePath to the path of the executable for your chosen Chrome-based browser.

  This feature has been tested on Linux servers using packaged versions of Chrome, Chromium, Microsoft Edge, and Opera. Other Chrome-based browsers that can run via command-line on a Linux server may also work.

• Inline edit mode is again the default format for the Owner field in ticket search results.

  In RT 5, we changed the default to a view-only version of Owner to improve performance when loading search results. We updated the Owner input to load only when you use it, removing the penalty when loading ticket results, so inline edit mode is the default again.

• The default value for the $ShowHistory configuration option is changed from delay to scroll. This controls how history on tickets is loaded. The scroll option loads blocks at a time as you scroll down the page, which can make the content available more quickly.

  If you often jump to the end of the history to see new updates, we encourage you to disable $OldestTransactionsFirst so the newest transactions appear right at the top of the history when a ticket loads. It can take a short time to get used to the history being reversed with "newest is on top", but life is much better (at least faster) once you adjust.

• [Add info about new ticket and asset configuration options here.]

• The following dependent libraries are updated to the new versions listed below in RT 6. Note that a common change in all javascript libraries and RT itself is dropping support for Internet Explorer. This has allowed developers to use newer javascript features and remove old special code that was just to handle IE-specific behavior.

  • Bootstrap 5.3

  • CKEditor 5

• Dropzone 7.2.0

  The new version supports attachment uploads in secure context only, which is over https or running a developer checkout on localhost. If you need to run without SSL, you can disable Dropzone in the RT configuration.

Extensions Integrated into RT 6

The following extensions are now part of RT 6. 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::ArticleTemplates

You need to set $EnableArticleTemplates to 1 to enable it.

RT::Extension::TimeTracking

Transaction custom fields "Worked Date" and "Actor" are automatically disabled after upgrade. They are not needed any more, so you can use sbin/rt-shredder to totally remove them. E.g. assuming ids of "Worked Date" and "Actor" are 1234 and 5678, respectively, you can shred them using the following command:

    sbin/rt-shredder --plugin 'Objects=CustomField,1234;CustomField,5678'