• UPGRADING FROM RT 4.2.0 and greater
• UPGRADING FROM 4.4.0 AND EARLIER
• UPGRADING FROM 4.4.1 AND EARLIER
• UPGRADING FROM 4.4.2 AND EARLIER

UPGRADING FROM RT 4.2.0 and greater

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

• RT now natively supports external authentication systems like LDAP and custom database setups. For new users wishing to use this functionality, see the RT::Authen::ExternalAuth::LDAP or RT::Authen::ExternalAuth::DBI documentation.

  Users of the existing RT::Authen::ExternalAuth extension should remove RT::Authen::ExternalAuth from the plugins list. Please also remove local/plugins/RT-Authen-ExternalAuth from your RT installation.

• RT::Extension::LDAPImport has been moved into core RT.

  Users of the existing LDAPImport extension should remove RT::Extension::LDAPImport from the plugins list. Please adjust any cronjobs or external scripts which invoke local/plugins/RT-Extension-LDAPImport/bin/rtldapimport to instead invoke sbin/rt-ldapimport. Please also remove local/plugins/RT-Extension-LDAPImport from your RT installation.

• As of 4.4, the RT::Extension::Assets functionality has been moved to core RT. New and upgrading users will automatically get all Assets functionality. Assets documentation can be found at docs/assets.pod. A tutorial on customizing your Assets install can be found at docs/customizing/assets/tutorial.pod.

  To cleanly hide it from upgrading RT installs, the Assets menu is controlled by the right ShowAssetsMenu. This right is only grantable globally to groups or users. If you were previously using the Assets extension, you can grant the ShowAssetsMenu right to Privileged or another role or group to make the menu visible.

  Users who are currently using the RT::Extension::Assets extension should remove RT::Extension::Assets from the plugin list and run the etc/upgrade/upgrade-assets utility after completing all the other upgrade steps from the README. Please also remove local/plugins/RT-Extension-Assets from your RT installation.

• As of 4.4, SLA tracking is also a core feature, so SLA is a core field on tickets for queues on which SLA tracking is enabled. Please see the SLA section in RT_Config.pm as well as docs/customizing/sla.pod for details on configuring RT's SLA feature.

  Users currently using RT::Extension::SLA should do the following to migrate to core SLA functionality after running the main RT code and database upgrade steps successfully:

  • Remove RT::Extension::SLA from your plugin list in RT_SiteConfig.pm

  • Run the upgrade script etc/upgrade/upgrade-sla

  • Update the format of your %ServiceAgreements configuration

    You can keep the same configuration, but it is now set with a Set call like all standard RT features, the leading RT:: is removed, and the = becomes a ,. You can see examples in docs/customizing/sla.pod.

  • Update the format of your %ServiceBusinessHours configuration

    If you have a Business Hours configuration, update your configuration in RT_SiteConfig.pm with the same changes as described above for %ServiceAgreements.

  • (Optional) Remove the directory local/plugins/RT-Extension-SLA

    You can remove this directory and all of its contents from your RT installation to uninstall the previous extension code

  Note that since SLA is now a core ticket value, it is currently not possible to have different levels per queue as was previously possible when using multiple SLA custom fields. Currently all queues share the same set of levels defined in %ServiceAgreements.

• RT can now natively store attachments outside the database, either on disk, in Dropbox, or on Amazon S3. For more information see RT::ExternalStorage and %ExternalStorage in RT_Config.pm.

  Users who are currently using RT::Extension::ExternalStorage should remove it from the plugin list. Please adjust any cronjobs or external scripts which invoke local/plugins/RT-Extension-ExternalStorage/bin/extract-attachments to instead invoke sbin/rt-externalize-attachments. Please also remove local/plugins/RT-Extension-ExternalStorage from your RT installation.

• RT now has the functionality from RT::Extension::ParentTimeWorked built in, with some modifications. In the ParentTimeWorked extension, when a child ticket's TimeWorked field was updated, the parent ticket's TimeWorked field was also incremented. Starting with RT 4.4.2, the time from child tickets is available in the Total Time Worked field and the Time Worked value for the parent ticket is independent.

  RT now also has built-in functionality to show time worked per user.

  For RT 4.4.0 and 4.4.1, these functions were enabled via scrips. New installs had these scrips by default. Upgrades got them too, but set as disabled so they didn't interfere with your existing configuration. These functions are now dynamic and no longer require these scrips.

  See "UPGRADING FROM 4.4.1 AND EARLIER" for additional details on the changes introduced in 4.4.2.

  Users who are currently using RT::Extension::ParentTimeWorked should remove it from the plugin list. Please also remove local/plugins/RT-Extension-ParentTimeWorked from your RT installation.

• The support for jsmin (via the $JSMinPath configuration) has been removed in favor of a built-in solution.

• You can now split settings from RT_SiteConfig.pm into separate files under an etc/RT_SiteConfig.d/ directory. All files ending in .pm will be parsed, in alphabetical order, after the main RT_SiteConfig.pm is loaded.

  You also no longer need the 1; at the end of site config files.

• When creating linked tickets from the Links box, Time Worked, Time Estimated, and Time Left will no longer be copied. This simplifies time reporting.

• Custom fields with categories will be split out into hierarchical custom fields.

• Homepage component "Quicksearch" has been renamed to "QueueList" to reflect what it actually is. Please update $HomepageComponents accordingly if you customized it in RT_SiteConfig.pm.

• RT::Interface::Email no longer exports functions.

• Incoming email now always creates users for the From: address. Previously, if the CreateTicket right was not granted to Everyone or Unprivileged, the email would be rejected without a user; now, the user will be created even when the mail is rejected.

• The "@MailPlugins" in RT_Config functionality has been rewritten; mail plugins written for previous versions of RT will not function as expected. See docs/extending/mail_plugins.pod

• The $UnsafeEmailCommands option has been replaced with two mail plugins, RT::Interface::Email::Action::Take and RT::Interface::Email::Action::Resolve.

• The RejectOnUnencrypted option to "%Crypt" in RT_Config has been replaced with a mail plugin, RT::Interface::Email::Authz::RequireEncrypted.

• We added DateTime::Format::Natural support to parse user-entered datetimes, which will be called only when Time::ParseDate fails to parse. You can tell RT to prefer DateTime::Format::Natural in RT_SiteConfig.pm:

      Set($PreferDateTimeFormatNatural, 1);

  You might do this if you prefer its handling of some syntax (e.g. "last month").

• The "Display Columns" section in the Search Builder has been ajaxified, so you don't need to reload the whole page to adjust formatting.

• When corresponding/commenting on tickets, you can include attachments that already exist on the ticket so you don't need to upload them again.

  This functionality was previously provided by the third-party RT::Extension::AddAttachmentsFromTransactions.

• We added a Disabled column to the Articles table, so now instead of deleting articles, we disable them, like other RT records. This helps maintain RT's auditability goals.

  For new deploys we also establish some common defaults for Articles: a General class and a Content textarea custom field.

• We removed the InitialPriority, FinalPriority, and DefaultDueIn columns from the Queues table. In their stead we have a more general ->DefaultValue call, e.g.

      $queue->DefaultValue('InitialPriority')
      $queue->DefaultValue('FinalPriority')
      $queue->DefaultValue('Due')

  Note that "Due" can now be anything that can be parsed as a date.

  With this, we've also added the ability to add default values for "Starts" and custom fields. All of them may be set on a queue's DefaultValues admin page.

• We've added a new config option and preference for HideUnsetFieldsOnDisplay to hide unset fields on the ticket display page. Note that this option does not affect custom fields. If you would like to hide custom fields too, please see RT::Extension::CustomField::HideEmptyValues.

• We've added another option for rendering ticket history: infinite scroll. This loads several items at a time as you scroll down the page. This should improve the perceived performance of ticket display. Users can enable this option by changing the "Show history" preference to "as you scroll". You can also change the system default in RT_SiteConfig.pm just like the existing options with

      Set($ShowHistory, 'scroll');

• RT now ships with keyboard shortcuts, both global (e.g. / to focus on quick search) and page-specific (e.g. x to toggle a checkbox in bulk update). Press ? in your browser to see what shortcuts can be used on the current page.

• We added a modern file uploader (Dropzone, http://www.dropzonejs.com). Now it's much easier to upload multiple files at a time, by dragging them into the page.

  The legacy attachment is still available when the modern uploader fails to load.

• We added two meta-statuses to TicketSQL: __Active__ and __Inactive__, so you no longer need to explicitly list all the active or inactive statuses like:

      Status = 'new' or Status = 'open' or Status = 'stalled'

  Now you can simply write:

      Status = '__Active__'

• We added an "Entry Hint" to custom fields. Previously, we used the custom field's FriendlyType as its hint, but now it is replaced by the per-CF customizable EntryHint field.

• RT now has support for custom roles, along the lines of Requestor, Owner, Cc, and AdminCc. You can select whether a custom role may have only a single member or multiple members (though you cannot change the role's arity after it's been created). You can assign custom roles to queues much like custom fields. Rights may be granted on custom roles globally or per-queue, and they may be searched in TicketSQL and the search builder with syntax like the following:

      CustomRole.{Engineer}.EmailAddress LIKE 'bestpractical.com'
      CustomRole.{3} = '__CurrentUser__'

  Finally you may notify custom roles in scrips by creating a RT::Action::Notify with an Argument containing the role name or RT::CustomRole-#. By default, custom roles will be added as Cc on outgoing mail but you can set them as To or Bcc by using a new slash syntax:

      AdminCc, Engineer
      Owner, RT::CustomRole-3/To, Cc
      Engineer/To, Sales/Bcc

  Custom role members can be added at the queue level (for multi-member roles) as well as on individual tickets (for both single-member and multi-member roles).

• Users can now select which days of the week they'd like Daily dashboard subscriptions to be mailed to them. This removes the now-duplicate M-F subscription type and makes the Daily subscription type respect new per-day checkboxes.

• We've dropped several never-used columns on the Users and Tickets tables and several columns that haven't been used in a very long time. The first 4.4 upgrade step makes sure there is no content in these fields, just in case an extension or local customization had appropriated any of them.

  For Users, we've dropped EmailEncoding, WebEncoding, ExternalContactInfoId, ContactInfoSystem, ExternalAuthId, AuthSystem, and PGPKey. (Note: GPG keys have always been stored in attributes on the User record in RT, never in the PGPKey column)

  For Tickets, we've dropped IssueStatement, Resolution, and Disabled.

• Users now receive a warning message when they type the word "attach" without having attached anything to the ticket, much like many mail clients offer. This should help cut down on the "oops, I forgot the attachment" followup mails.

• We've upgraded our version of jQuery from 1.9.1 to 1.11.3 and jQuery UI from 1.10.0 to 1.11.4.

  https://jqueryui.com/upgrade-guide/1.10/ https://jqueryui.com/upgrade-guide/1.11/

• We've upgraded our version of CKEditor from 4.0.1 to 4.5.3.

• In rights management pages, sections with rights assigned now have a gray callout.

• We've removed the Type column for Groups, which was redundant. Domain identifies the type of group.

• We've removed the ObjectId for Principals, which was redundant, as it should always be the same as id.

• We've added a new config option %ReferrerComponents to customize how referrer whitelists and blacklists work.

• We now place tmpfiles generated during email parsing under /tmp, which should allow the system tmp-cleaner to purge any dangling files, and eases configuration of RT under SELinux.

• Squelching now applies to all updates in the request, instead of only the initial correspond/comment transaction.

• We removed the unused "on merge" lifecycle property, as merged tickets cannot be found via searches or charts.

• We now allow ModifyTicket to change nobody to someone else, without OwnTicket.

  Previously, we required OwnTicket if the ticket was currently unowned, no matter if you were taking it yourself or assigning it to someone else.

  We now allow nobody -> self with OwnTicket and (ModifyTicket, ReassignTicket, or TakeTicket), and nobody -> someone else with ModifyTicket or ReassignTicket. This also closes a bug where TakeTicket and OwnTicket was enough to change the owner from Nobody to someone else.

• We now no longer large round number of hours worked into days, since "7 days worked" may imply only 56 business hours instead of 168 real hours.

• We've added a ticket timer feature for automatically keeping track of time. This feature pops open a small JavaScript window with a very much trimmed down RT interface.

• On ticket display pages we now make the queue name a hyperlink to a search for all active tickets in that queue.

• There is a new widget on the ticket display page that allows you to create a ticket in a different queue that will automatically be linked to the given ticket. In the Links section on the display page, choose the type of link and the queue, and click Create. The create ticket form will be opened. When the ticket is created, it will be linked to the previous ticket.

• IPv6 custom field values are now displayed in compressed form, for clarity. Searching and updating handle both representations as you'd expect.

UPGRADING FROM 4.4.0 AND EARLIER

• The Dashboard subscription recipient options have been greatly expanded from a single text field (which happened to support multiple email address separated with a comma) to a robust user/group search. There is a database upgrade step for migrating the old "Recipient" textbox values.

• In versions of RT before 4.4.1, under certain conditions Saved Charts were not completely saved to the database, which led to them not showing up when added to dashboards. There is a database upgrade step that fixes such charts so they will now show up on dashboards, and of course the underlying bug has been corrected.

• We updated default RT searches that previously specified 'new' and 'open' (and sometimes, 'stalled') status to use the new Status='__Active__' and Status='__Inactive__' syntax where appropriate. For new RT installs, this means the default RT at a Glance searches will now work with custom lifecycles without updating these searches.

  For existing RT sites, you may want to update the "highest priority tickets I own" and 'newest unowned tickets' system searches to use Status='__Active__' rather than specific statuses.

• Users may now select a specific language for dashboard email subscriptions. Administrators can customize the method by which dashboard email language is chosen (including specifying an ultimate fallback other than English) with the @EmailDashboardLanguageOrder RT_Config option.

  This may change which language users receive their dashboards in. To fix this, users may need to specify their language explicitly on their "About Me" page. Administrators may also want to set up a default language that matches their userbase better than RT's default of English.

• The "hide unset fields" preference now also hides unset custom fields, obsoleting RT::Extension::CustomField::HideEmptyValues. The implementation was also changed from omitting HTML tags for such fields to adding an `.unset` class name and hiding such fields with CSS.

• Long attachment lists now show only the five newest attachments with an AJAX "Show all" link. This should improve the performance and usability of both ticket display and ticket reply pages.

• rt-crontool used with multiple actions may have been sending email to the wrong recipients; we've fixed this issue (by reloading the template object for each action) so please double check that such cronjobs are still sending mail to the right people.

• We now explicitly depend on the Pod::Select Perl module since it was removed from the Perl core starting in 5.18. If you're on a recent version of Perl you will most likely need to install this dependency.

• We now automatically enable ExternalAuth when the ExternalSettings config is declared, so you may remove Set($ExternalAuth, 1); from your config.

• We've deprecated the /Admin/CustomFields/Modify.html callback named AfterUpdateCustomFieldValue. It will be removed in RT 4.6.

UPGRADING FROM 4.4.1 AND EARLIER

• Changes to Time Worked Handling

  As noted above, in RT 4.4 we pulled in some time tracking features from extensions, specifically adding time worked on child tickets to the parent and showing time worked per user. In RT 4.4.2, we made some important changes to this functionality.

  The new features were installed but disabled for upgrades, so these changes are most important to RT users who installed RT starting with version 4.4.0 or 4.4.1, or who users who upgraded from a previous RT and then manually enabled the time tracking scrips.

  • Parent Time Worked

    Based on feedback from users and our own experience, we determined that updating the Time Worked value on the parent ticket made it difficult to differentiate time recorded from children tickets from time recorded directly on the parent ticket. To clarify the history for these time entries, we created a new dynamic value called Total Time Worked that is a sum of Time Worked from the parent and all child tickets. You can activate this feature with the $DisplayTotalTimeWorked configuration option in RT_SiteConfig.pm.

    We generate this when displaying the ticket and we no longer update Time Worked on the parent ticket. This change also has the advantage that Total Time Worked automatically updates when a child ticket is added or removed. Total Time Worked is also available as a column for reports generated with the Query Builder.

    Important: If you were previously using the parent time worked feature, the Time Worked value on parent tickets already contains time from child tickets. Total Time Worked will therefore be incorrect since it will add up all children then add the parent time (which already has the child time). You can choose to keep using the scrip and not show Total Time Worked, or update Time Worked on the parent ticket to have just parent time worked.

    Contact Best Practical at contact@bestpractical.com if you have questions about these changes.

  • Time Worked by User

    For the user time summary feature, we found some odd cases where a time value would not get recorded (if the scrip was mistakenly disabled, for example). In these cases, since the data was stored internally, it was difficult to update the user time values. We have made this feature dynamic so the user time information for the current ticket is generated when the ticket is displayed.

    If you previously used this feature, the user time data stored in an attribute on each ticket will still be in the database. Since it is only visible directly in the database, you can safely ignore it. However, if you want to remove it, you can locate these records with the following:

        SELECT id, Name FROM Attributes WHERE ObjectType = 'RT::Ticket' AND Name = 'TimeWorked';

    You can delete these records from the Attributes table using a DELETE and the same WHERE clause. Always make sure you have a known good backup of your database before making updates.

• RT now has the functionality from RT::Extension::AdminConditionsAndActions built in. Users who are currently using this extension should remove it from the plugin list. Please also remove local/plugins/RT-Extension-AdminConditionsAndActions from your RT installation.

UPGRADING FROM 4.4.2 AND EARLIER

• The MessageRef parameter of the default callback of /Elements/MessageBox now contains the reference to the message content as the name implies.