• UPGRADING FROM RT 4.0.0 and greater
• UPGRADING FROM 4.2.3 AND EARLIER
• UPGRADING FROM 4.2.5 AND EARLIER
• UPGRADING FROM 4.2.6 AND EARLIER

UPGRADING FROM RT 4.0.0 and greater

The 4.2 release is a major upgrade and as such there are more changes than in a minor bugfix release (e.g., 4.0.13 to 4.0.14) 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.

• The "$UseSQLForACLChecks" in RT_Config option defaults to on. This provides a number of improvements, most notably no longer showing pages of empty results if the user doesn't have permissions to view the tickets in question. It may, in some cases, have performance impacts, but these have been found to be minimal in existing 4.0 installs.

• The $LogToScreen config setting is now named "$LogToSTDERR" which better describes what the log level controls. Setting $LogToScreen will still work, but an informational notice will be issued on server start telling you about the rename. To avoid this you should set $LogToSTDERR instead.

• The link direction and type maps are consolidated into RT::Link. If you wrote local customizations or extensions utilizing %RT::Ticket::LINKDIRMAP, %RT::Ticket::LINKTYPEMAP, RT::Ticket->LINKDIRMAP, RT::Ticket->LINKTYPEMAP, or %RT::Record::LINKDIRMAP, you will need to switch to %RT::Link::DIRMAP and %RT::Link::TYPEMAP.

• $LinkTransactionsRun1Scrip is removed. If you were relying on this behavior (by setting it to 1), you should adjust your scrips to ignore one of the link transactions.

• The $AttachmentUnits option was removed in preference of always displaying in megabytes, kilobytes, or bytes as appropriate. The option was incompletely implemented and controlled display in the attachments list but not history.

• MakeClicky handlers added via a callback are now passed an "object" key in the parameter hash instead of "ticket". The object may be any RT::Record subclass.

• $MessageBoxWrap was removed. Wrapping is now always SOFT. If you want hard line breaks, enter them manually.

• ShowUser handlers (/Elements/ShowUser*) have moved out of Mason components and into RT::User methods. Any custom username formats will need to be reimplemented as RT::User methods. Renaming should follow that of the core components:

      /Elements/ShowUserConcise => RT::User->_FormatUserConcise
      /Elements/ShowUserVerbose => RT::User->_FormatUserVerbose

  The _FormatUser* methods are passed a hash containing the keys User and Address, which have the same properties as before.

• Rich text (HTML) messages are now preferred for display. If you prefer plain text messages, set "$PreferRichText" in RT_Config to 0.

• User email addresses are now validated by default and multiple, comma-separated addresses for a single user are no longer allowed. Existing users with invalid addresses will continue to work until the next time they are updated by an administrator on the modify user page. If you prefer no address validation, set "$ValidateUserEmailAddresses" in RT_Config to 0.

• The smtp option for "$MailCommand" in RT_Config, along with the associated $SMTPServer, $SMTPFrom, and $SMTPDebug options, has been removed because it did not guarantee delivery. Instead, use a local MTA for outgoing mail, via the 'sendmailpipe' setting to $MailCommand.

• The "@JSFiles" in RT_Config config now only keeps additional JavaScript filenames; if you had copied @JSFiles to add extra entries in your RT_SiteConfig.pm, remove the core JS from the list, or RT will serve those files multiple times.

• The $DeferTransactionLoading option was combined into the new option "$ShowHistory" in RT_Config. If you had enabled $DeferTransactionLoading, you may want to set $ShowHistory to click. However, $ShowHistory provides a new mode, delay, which is the default and may be a more appealing alternative to click.

• A Status transaction is now recorded when a ticket status changes as a result of a queue change. Scrips with conditions relying on Status changes may start to trigger on these transitions; previously these Status changes never triggered scrips.

• The Googleish search has been renamed to Simple. If you were using this in an rt-crontool cronjob or had used a Googleish_Local.pm to add features, you will need to convert to using RT::Search::Simple instead.

• On merge, RT retains transactions from both tickets. Previously, RT also recorded explicit time change transactions during a merge to adjust the total time spent. This caused the total time spent, as summed from transactions, to be different from the ticket's overall time spent. This has been fixed: time is adjusted during the merge commit itself, removing the need for the confusing extra transactions, and keeping the summed time spent consistent.

  In order to fix the history records of old ticket you can run the following command:

      perl -I /opt/rt4/local/lib/ -I /opt/rt4/lib/ etc/upgrade/time-worked-history.pl

  This command deletes records from the Transactions table. This script can only fix TimeWorked mismatches, but not TimeLeft or TimeEstimated.

• A new action, "Open Inactive Tickets", has been added, and on new installs the default scrip "On Correspond Open Tickets" has been replaced by "On Correspond Open Inactive Tickets". The key difference between "Open Tickets" and "Open Inactive Tickets" is that the latter will not adjust the status of a ticket if it is already active. This is particularly useful when creating complex workflows using Lifecycles.

• CSS is no longer processed through Mason; it's served by a proper static file handler. If you used the Begin or End callbacks of main.css in the aileron, web2, or ballard themes, you should transition to the "@CSSFiles" in RT_Config config option. If you need to target specific themes, you can use the class set on the <body> element (for example: body.aileron). See docs/customizing/styling_rt.pod for more information on custom styles.

• There are now HTML versions of the standard plain text templates. Running make upgrade as described in the README will insert the new templates into existing installs. While new installs use the HTML templates by default, upgrades from older versions don't automatically switch to the HTML versions. To switch existing scrips, run:

      /opt/rt4/etc/upgrade/switch-templates-to html

  To switch from HTML back to text, run:

      /opt/rt4/etc/upgrade/switch-templates-to text

• The Articles menu is now a top-level menu item and display is controlled by the right ShowArticlesMenu. This right is only grantable globally to groups or users. During the upgrade, the new right will be automatically granted to Privileged users so that the menu doesn't disappear for anyone previously using it. You may wish to revoke the right from Privileged and grant it more selectively.

• The Owner drop-down now only includes privileged users (no matter if unprivileged users have been granted the OwnTicket right) because configurations which have unprivileged Owners are exceedingly rare, and granting Everyone the OwnTicket right is a common cause of performance problems. Unprivileged Owners (if they exist) may still be set using the Autocompleter.

• The functionality that changed the ticket status to Open when the Started date is set has been moved to a Scrip called 'On transaction and SetStarted Open Ticket'. If you do not depend on this functionality, the Scrip can be deleted.

• New installs will notify Ccs and one-time Ccs/Bccs on create and Owners on create and correspond. Upgraded installations will not. If you'd like to adjust your scrips to match the new install behavior, create and edit the following scrips from the admin scrip page:

  To notify Ccs on create, on the 'Create a global scrip' page:

    Description: On Create Notify Ccs
    Condition:   On Create
    Action:      Notify Ccs
    Template:    Correspondence in HTML

  To notify one-time Ccs/Bccs on create, on the 'Create a global scrip' page:

    Description: On Create Notify Other Recipients
    Condition:   On Create
    Action:      Notify Other Recipients
    Template:    Correspondence in HTML

  To notify Owners on create, click 'On Create Notify AdminCcs'. Change the fields listed below to their corresponding values:

    Description: On Create Notify Owner and AdminCcs
    Action:      Notify Owner and AdminCcs

  To notify Owners on correspond, click 'On Correspond Notify AdminCcs'. Change the fields listed below to their corresponding values:

    Description: On Correspond Notify Owner and AdminCcs
    Action:      Notify Owner and AdminCcs

• Notifications to AdminCcs on approvals are now handled via the New Pending Approval template in the hidden ___Approvals queue. If you customized the Transaction template, you should port your changes to New Pending Approval.

• On Oracle, sessions are now stored in the database by default instead of on-disk. If you wish to preserve the original behavior, ensure that "$WebSessionClass" in RT_Config is set in your RT_SiteConfig.pm:

      Set($WebSessionClass, "Apache::Session::File");

• Configuration options dealing with "external authentication" have been renamed to reduce confusion with the common extension RT::Authen::ExternalAuth. The old names will work, but produce deprecation warnings. The old names, and their new counterparts, are:

      WebExternalAuth           => WebRemoteUserAuth
      WebExternalAuthContinuous => WebRemoteUserContinuous
      WebFallbackToInternalAuth => WebFallbackToRTLogin
      WebExternalGecos          => WebRemoteUserGecos
      WebExternalAuto           => WebRemoteUserAutocreate
      AutoCreate                => UserAutocreateDefaultsOnLogin

• Due to many long-standing bugs and limitations, the "Offline Tool" was removed.

• To increase security against offline brute-force attacks, RT's default password encryption has been switched to the popular bcrypt() key derivation function. Passwords cannot be automatically bulk upgraded to the new format, but will be replaced with bcrypt versions upon the first successful login.

• We updated default "Forward" and "Forward Ticket" templates to support customizing messages on forward. They will be updated automatically if you didn't change them before.

  But in case you have changed them already, you need to update them manually. You can use $ForwardTransaction to refer to the customized message in the templates, e.g. "Forward" template could be updated to:

  { $ForwardTransaction->Content =~ /\S/ ? $ForwardTransaction->Content : "This is a forward of transaction #".$Transaction->id." of ticket #". $Ticket->id }

• RT has generated RT-Ticket: RT-Originator: and Managed-By: headers in compliance with RFC2822/6648 but we've discovered that some smarthost providers are requiring strict adherence to RFC822 which mandates X- prefixes on these headers. We've made this change in 4.2 for users relying on those providers.

  Any external scripts which were parsing on these RT mail headers will need to be updated.

• GnuPG and S/MIME are no longer enabled in RT_Config.pm merely by the presence of the gpg or openssl binaries. Systems which depended on configure enabling these in RT_Config.pm implicitly will need to pass --enable-gpg to configure, or alter their RT_SiteConfig.pm to enable the functionality explicitly.

• In TicketSQL, "Starts = '1970-01-01'" will no longer find tickets with no Starts date set. Instead, use "Starts IS NULL". As a direct consequence, "Starts < 'today'" will no longer also find tickets with no Starts date; use "Starts < 'today' OR Starts IS NULL" to have the equivalent results in RT 4.2.

UPGRADING FROM 4.2.3 AND EARLIER

RT 4.2.4's upgrade scripts contain two fixes to normalize upgraded RTs with those installed new from a release of RT 4.2.

We neglected to add the "Open Inactive Tickets" action mentioned earlier in this documents. It was available to fresh installs but not on upgrades. This Scrip Action is now created if needed.

RT expects the ___Approvals queue to have a special value in the Disabled column so that it is hidden but tickets can still be created (normal disabled Queues disallow ticket creation). Users who enabled and then disabled the Queue on earlier releases will have the incorrect Disabled value, so we fix that. A similar problem applies to the lifecycle, which must be set to the internal "approvals" lifecycle -- which is not listed as an option. RT 4.2.4 also includes enhancements to the Queue admin page for ___Approvals to prevent editing things which might cause problems.

UPGRADING FROM 4.2.5 AND EARLIER

RT 4.2.6 includes a new Scrip Action "Notify Owner or AdminCc". This action will send the given correspondence to the Owner, if not Nobody, otherwise it will notify the AdminCcs. If using this, you will likely want to modify or remove the Notify Owner and AdminCcs scrip to avoid duplicate notifications. This Scrip Action is not used in any default Scrips at this time.

UPGRADING FROM 4.2.6 AND EARLIER

The $LogoImageHeight and $LogoImageWidth configuration options have been overridden by CSS since 4.0.0, and thus did not affect display. They have been removed, and setting them will trigger an informational message that setting them is ineffective.