X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=rt%2Fdocs%2FUPGRADING-4.2;fp=rt%2Fdocs%2FUPGRADING-4.2;h=76aa96d156931cec9631d1757f1cb3b701229f4d;hp=0000000000000000000000000000000000000000;hb=1c538bfabc2cd31f27067505f0c3d1a46cba6ef0;hpb=4f5619288413a185e9933088d9dd8c5afbc55dfa diff --git a/rt/docs/UPGRADING-4.2 b/rt/docs/UPGRADING-4.2 new file mode 100644 index 000000000..76aa96d15 --- /dev/null +++ b/rt/docs/UPGRADING-4.2 @@ -0,0 +1,337 @@ +=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; GiST 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. + +=cut