RT 6.0.3 Documentation

UPGRADING-6.0

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 rt5 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/rt5) 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.

Notable Application Changes

Database Changes

As always, all database changes are automated and will be run as part of the upgrade process when you run make upgrade-database. We offer some additional context here in case you need to troubleshoot, or if you have local modifications, or if you're just curious.

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'
RTx::Calendar

Saved searches named "calendar" will need to be updated. Edit the saved searches and change the Display As option to Calendar, then Update the saved search.

Dashboards with a calendar widget will also need to be updated. Edit the dashboards and replace the calendar widget from RTx::Calendar with the saved search that provides the calendar.

If you do not have a saved search named calendar you need to create a saved search that matches the default RTx::Calendar search:

    Query
        ( Status = 'new' OR Status = 'open' OR Status = 'stalled')
        AND ( Owner = '" . $session{CurrentUser}->Id ."' OR Owner = 'Nobody'  )
        AND ( Type = 'reminder' OR 'Type' = 'ticket' )

    Format
        __Starts__,
        __Due__

The calendar has been simplified to eliminate any configuration other than the search format for the saved search. See docs/query_builder.pod for details on configuring calendar saved searches using the search format.

UPGRADING FROM 6.0.0

Toolbar configuration in %MessageBoxRichTextInitArguments updated

The CKEditor toolbar configuration defined in %MessageBoxRichTextInitArguments used the basic format in RT 6.0.0. RT 6.0.1 updates this to the extended format, adding an items entry to toolbar. The toolbar option can accept other options, like shouldNotGroupWhenFull, and this change makes it easier for admins and extension authors to add options without re-writing the entire toolbar configuration.

If you have customized %MessageBoxRichTextInitArguments, we recommend updating your custom configuration to also include the items entry to ensure compatibility with future extensions.

LastUpdated does not update for same value

When attempting to set fields to their current value, RT compares the values, sees that no update is needed, and makes no change and no transaction is recorded. However, in some cases, LastUpdated would still be updated. This was incorrect since the value was not updated again, and could be confusing since it could appear that a ticket or asset had been updated, but no transaction was shown in the history.

This has been fixed and LastUpdated is no longer changed in these cases. This was mostly for direct perl API calls, so the change would be most likely to be noticed for command-line scripts or other automation.

UPGRADING FROM 6.0.1

REST2 interface can be disabled

Since it's not possible to use the REST2 API in a command-line program, RT now loads REST2 libraries only for web server processes. In our testing this saves about 16 MB of memory for CLI processes.

We have also added an option to disable REST2 for web server processes. This saves memory for systems that do not use REST2. The default is still enabled.

    Set($EnableREST2, 0);
Custom Role Visibility moved to Page Layouts

Custom roles previously had a configuration page that allowed you to show or hide that custom role on various pages in RT. With page layouts in RT 6, it's no longer certain what components will be on any given page. Custom role visibility is therefore moved to the individual widgets where the custom role is displayed. Look for the pencil icon on widgets like Message and People and click to set show/hide settings for each custom role.

This new location allows you to set visibility in each page layout, so different queues can have different settings, which was not possible previously.

If you have existing custom role visibility settings, on upgrade from RT 5 you will need to apply those settings to the desired locations in page layouts.

UPGRADING FROM 6.0.2

Dashboard saved searches now use their own Rows settings

In previous versions, when displaying saved searches on dashboards, the homepage used $DefaultSummaryRows configuration option to set the number of rows displayed in each search portlet. All other dashboards defaulted to 50 rows. Users could also set a personal preference for this value on the Logged in as > Settings > Options > Search Options page.

RT now uses the Rows setting configured in each saved search when displaying it on a dashboard. This allows different searches to show different numbers of results.

The default for $DefaultSummaryRows is now undef, which enables this new behavior on the homepage. If this is disruptive for your RT and you want to restore the old default for homepages, set $DefaultSummaryRows to 10, which was the old value. Or, users can update the rows setting in their saved searches, possibly picking a different value for different searches.

Users can now set individual preferences for rows and columns in each saved search in a dashboard by clicking the gear icon. If a user has personal settings, the gear will be filled in, making it easy to see if there are overrides.

Saved searches on dashboards now support pagination and column sorting

Saved searches displayed on dashboards now show pagination controls at the bottom when results span multiple pages. Users can navigate through pages without leaving the dashboard.

Column headers in dashboard search results are now clickable, allowing users to re-sort results by that column. Clicking a column header cycles through ascending, descending, and default sort order. These temporary sort changes are preserved when navigating between pages or when the search auto-refreshes.

Status colors in lifecycles

RT can now display ticket and asset statuses as colored badges. Colors are configured per-status in each lifecycle. To set status colors via the web UI, go to Admin > Lifecycles, select a lifecycle, and in the graphical editor, click on a status name. A modal will pop up allowing you to enable and select a status color.

If you are managing your lifecycles via a configuration file, you can add a new colors key and provide a hex color value for each status.

On new installs, RT's built-in lifecycles (default, approvals, and assets) ship with default colors. For existing systems, you can select new colors after upgrading.

← Back to index

Security contact information
© 2002-2026 Best Practical Solutions LLC.