=head1 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. See F for internals changes relevant to extension writers. =over =item * The L 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. =item * The C<$LogToScreen> config setting is now named L<< "C<$LogToSTDERR>"|RT_Config/"$LogToSyslog, $LogToSTDERR" >> which better describes what the log level controls. Setting C<$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 C<$LogToSTDERR> instead. =item * C<$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. =item * The C<$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. =item * C<$MessageBoxWrap> was removed. Wrapping is now always C. If you want hard line breaks, enter them manually. =item * Rich text (HTML) messages are now preferred for display. If you prefer plain text messages, set L to 0. =item * 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 L to 0. =item * The C option for L, along with the associated C<$SMTPServer>, C<$SMTPFrom>, and C<$SMTPDebug> options, has been removed because it did not guarantee delivery. Instead, use a local MTA for outgoing mail, via the 'sendmailpipe' setting to C<$MailCommand>. =item * The L config now only keeps additional JavaScript filenames; if you had copied C<@JSFiles> to add extra entries in your C, remove the core JS from the list, or RT will serve those files multiple times. =item * The C<$DeferTransactionLoading> option was combined into the new option L. If you had enabled C<$DeferTransactionLoading>, you may want to set C<$ShowHistory> to C. However, C<$ShowHistory> provides a new mode, C, which is the default and may be a more appealing alternative to C. =item * A C 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. =item * The C search has been renamed to C. If you were using this in an L<< C >> cronjob or had used a C to add features, you will need to convert to using L instead. =item * 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: /opt/rt4/etc/upgrade/time-worked-history This command deletes records from the Transactions table. This script can only fix TimeWorked mismatches, but not TimeLeft or TimeEstimated. =item * 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. =item * There are now HTML versions of the standard plain text templates. Running make upgrade as described in the F 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 =item * The Articles menu is now a top-level menu item and display is controlled by the right C. 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. =item * 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. =item * 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. =item * 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 =item * 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. =item * 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 L is set in your C: Set($WebSessionClass, "Apache::Session::File"); =item * Configuration options dealing with "external authentication" have been renamed to reduce confusion with the common extension L. 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 =item * Due to many long-standing bugs and limitations, the "Offline Tool" was removed. =item * 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. =item * 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 } =item * 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. =item * GnuPG and S/MIME are no longer enabled in F merely by the presence of the C or C binaries. Systems which depended on C enabling these in F implicitly will need to pass C<--enable-gpg> to C, or alter their C to enable the functionality explicitly. =item * 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. =back =head1 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 B 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. =head1 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. =head1 UPGRADING FROM 4.2.6 AND EARLIER The C<$LogoImageHeight> and C<$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. =head1 UPGRADING FROM 4.2.9 AND EARLIER An additional optional dependency, L, has been added. This allows RT to use C, C, C, or other external tools to render HTML to text. This dependency is not installed by default; however, its use is strongly encouraged, and will resolve issues with blank outgoing emails. =head1 UPGRADING FROM 4.2.10 AND EARLIER The C<$DatabaseRequireSSL> option has never affected whether the database connection was performed using SSL, even under Postgres; the functionality can now be implemented via C<%DatabaseExtraDSN>. C<$DatabaseRequireSSL> has been removed, and setting it will trigger an informational message that setting it is ineffective. The full-text indexing defaults for PostgreSQL have changed; GIN is now the suggested index, as well as storing data in a separate AttachmentsIndex table. Both changes improve lookup speed. For improved search performance, you may wish to drop existing C and C indexes on C, and re-generate the index using C. =head1 UPGRADING FROM 4.2.12 AND EARLIER New deployments install an C that includes a C to allow Unicode to be used in config. You may wish to add a C to the top of your C if you haven't already done so. =cut