1 =head1 UPGRADING FROM RT 4.0.0 and greater
3 The 4.2 release is a major upgrade and as such there are more changes
4 than in a minor bugfix release (e.g., 4.0.13 to 4.0.14) and some of these
5 changes are backward-incompatible. The following lists some of the notable
6 changes, especially those that might require you to change a configuration
7 option or other setting due to a change in RT. Read this section carefully
8 before you upgrade and look for changes to features you currently use.
10 See F<devel/docs/UPGRADING-4.0> for internals changes relevant to
17 The L<RT_Config/$UseSQLForACLChecks> option defaults to on. This provides
18 a number of improvements, most notably no longer showing pages of empty results
19 if the user doesn't have permissions to view the tickets in question.
20 It may, in some cases, have performance impacts, but these have been
21 found to be minimal in existing 4.0 installs.
25 The C<$LogToScreen> config setting is now named
26 L<< "C<$LogToSTDERR>"|RT_Config/"$LogToSyslog, $LogToSTDERR" >> which
27 better describes what the log level controls. Setting C<$LogToScreen> will
28 still work, but an informational notice will be issued on server start telling
29 you about the rename. To avoid this you should set C<$LogToSTDERR> instead.
33 C<$LinkTransactionsRun1Scrip> is removed. If you were relying on this behavior
34 (by setting it to 1), you should adjust your scrips to ignore one of the link
39 The C<$AttachmentUnits> option was removed in preference of always displaying in
40 megabytes, kilobytes, or bytes as appropriate. The option was incompletely
41 implemented and controlled display in the attachments list but not history.
45 C<$MessageBoxWrap> was removed. Wrapping is now always C<SOFT>. If you want hard
46 line breaks, enter them manually.
50 Rich text (HTML) messages are now preferred for display. If you prefer plain
51 text messages, set L<RT_Config/$PreferRichText> to 0.
55 User email addresses are now validated by default and multiple,
56 comma-separated addresses for a single user are no longer allowed. Existing
57 users with invalid addresses will continue to work until the next time they
58 are updated by an administrator on the modify user page. If you prefer no
59 address validation, set L<RT_Config/$ValidateUserEmailAddresses> to 0.
63 The C<smtp> option for L<RT_Config/$MailCommand>, along with the associated
64 C<$SMTPServer>, C<$SMTPFrom>, and C<$SMTPDebug> options, has been removed
65 because it did not guarantee delivery. Instead, use a local MTA for
66 outgoing mail, via the 'sendmailpipe' setting to C<$MailCommand>.
70 The L<RT_Config/@JSFiles> config now only keeps additional JavaScript filenames; if
71 you had copied C<@JSFiles> to add extra entries in your C<RT_SiteConfig.pm>,
72 remove the core JS from the list, or RT will serve those files
77 The C<$DeferTransactionLoading> option was combined into the new option
78 L<RT_Config/$ShowHistory>. If you had enabled C<$DeferTransactionLoading>,
79 you may want to set C<$ShowHistory> to C<click>. However, C<$ShowHistory>
80 provides a new mode, C<delay>, which is the default and may be a more
81 appealing alternative to C<click>.
85 A C<Status> transaction is now recorded when a ticket status changes as a
86 result of a queue change. Scrips with conditions relying on Status changes
87 may start to trigger on these transitions; previously these Status changes
88 never triggered scrips.
92 The C<Googleish> search has been renamed to C<Simple>. If you were
93 using this in an L<< C<rt-crontool> >> cronjob or had used a
94 C<Googleish_Local.pm> to add features, you will need to convert to
95 using L<RT::Search::Simple> instead.
99 On merge, RT retains transactions from both tickets. Previously, RT
100 also recorded explicit time change transactions during a
101 merge to adjust the total time spent. This caused the total time
102 spent, as summed from transactions, to be different from the ticket's
103 overall time spent. This has been fixed: time is adjusted during the
104 merge commit itself, removing the need for the confusing
105 extra transactions, and keeping the summed time spent consistent.
107 In order to fix the history records of old ticket you can run the following
110 /opt/rt4/etc/upgrade/time-worked-history
112 This command deletes records from the Transactions table. This script can only fix
113 TimeWorked mismatches, but not TimeLeft or TimeEstimated.
117 A new action, "Open Inactive Tickets", has been added, and on new
118 installs the default scrip "On Correspond Open Tickets" has been
119 replaced by "On Correspond Open Inactive Tickets". The key difference
120 between "Open Tickets" and "Open Inactive Tickets" is that the latter
121 will not adjust the status of a ticket if it is already active. This
122 is particularly useful when creating complex workflows using
127 There are now HTML versions of the standard plain text templates. Running
128 make upgrade as described in the F<README> will insert the new templates into
129 existing installs. While new installs use the HTML templates by default,
130 upgrades from older versions don't automatically switch to the HTML versions.
131 To switch existing scrips, run:
133 /opt/rt4/etc/upgrade/switch-templates-to html
135 To switch from HTML back to text, run:
137 /opt/rt4/etc/upgrade/switch-templates-to text
141 The Articles menu is now a top-level menu item and display is controlled by
142 the right C<ShowArticlesMenu>. This right is only grantable globally to groups
143 or users. During the upgrade, the new right will be automatically granted to
144 Privileged users so that the menu doesn't disappear for anyone previously
145 using it. You may wish to revoke the right from Privileged and grant it
150 The Owner drop-down now only includes privileged users (no matter if
151 unprivileged users have been granted the OwnTicket right) because
152 configurations which have unprivileged Owners are exceedingly rare,
153 and granting Everyone the OwnTicket right is a common cause of
154 performance problems. Unprivileged Owners (if they exist) may still
155 be set using the Autocompleter.
159 The functionality that changed the ticket status to Open when the Started
160 date is set has been moved to a Scrip called 'On transaction and SetStarted
161 Open Ticket'. If you do not depend on this functionality, the Scrip can
166 New installs will notify Ccs and one-time Ccs/Bccs on create and Owners on
167 create and correspond. Upgraded installations will not. If you'd like to
168 adjust your scrips to match the new install behavior, create and edit the
169 following scrips from the admin scrip page:
171 To notify Ccs on create, on the 'Create a global scrip' page:
173 Description: On Create Notify Ccs
176 Template: Correspondence in HTML
178 To notify one-time Ccs/Bccs on create, on the 'Create a global scrip' page:
180 Description: On Create Notify Other Recipients
182 Action: Notify Other Recipients
183 Template: Correspondence in HTML
185 To notify Owners on create, click 'On Create Notify AdminCcs'. Change the
186 fields listed below to their corresponding values:
188 Description: On Create Notify Owner and AdminCcs
189 Action: Notify Owner and AdminCcs
191 To notify Owners on correspond, click 'On Correspond Notify AdminCcs'. Change
192 the fields listed below to their corresponding values:
194 Description: On Correspond Notify Owner and AdminCcs
195 Action: Notify Owner and AdminCcs
199 Notifications to AdminCcs on approvals are now handled via the New Pending
200 Approval template in the hidden ___Approvals queue. If you customized the
201 Transaction template, you should port your changes to New Pending Approval.
205 On Oracle, sessions are now stored in the database by default instead of
206 on-disk. If you wish to preserve the original behavior, ensure that
207 L<RT_Config/$WebSessionClass> is set in your C<RT_SiteConfig.pm>:
209 Set($WebSessionClass, "Apache::Session::File");
213 Configuration options dealing with "external authentication" have been
214 renamed to reduce confusion with the common extension
215 L<RT::Authen::ExternalAuth>. The old names will work, but produce
216 deprecation warnings. The old names, and their new counterparts, are:
218 WebExternalAuth => WebRemoteUserAuth
219 WebExternalAuthContinuous => WebRemoteUserContinuous
220 WebFallbackToInternalAuth => WebFallbackToRTLogin
221 WebExternalGecos => WebRemoteUserGecos
222 WebExternalAuto => WebRemoteUserAutocreate
223 AutoCreate => UserAutocreateDefaultsOnLogin
227 Due to many long-standing bugs and limitations, the "Offline Tool" was
232 To increase security against offline brute-force attacks, RT's default
233 password encryption has been switched to the popular bcrypt() key
234 derivation function. Passwords cannot be automatically bulk upgraded to
235 the new format, but will be replaced with bcrypt versions upon the first
240 We updated default "Forward" and "Forward Ticket" templates to support
241 customizing messages on forward. They will be updated automatically if you
242 didn't change them before.
244 But in case you have changed them already, you need to update them manually.
245 You can use $ForwardTransaction to refer to the customized message in the
246 templates, e.g. "Forward" template could be updated to:
248 { $ForwardTransaction->Content =~ /\S/ ? $ForwardTransaction->Content : "This is a forward of transaction #".$Transaction->id." of ticket #". $Ticket->id }
252 RT has generated RT-Ticket: RT-Originator: and Managed-By: headers in
253 compliance with RFC2822/6648 but we've discovered that some smarthost
254 providers are requiring strict adherence to RFC822 which mandates X-
255 prefixes on these headers. We've made this change in 4.2 for users
256 relying on those providers.
258 Any external scripts which were parsing on these RT mail headers will
263 GnuPG and S/MIME are no longer enabled in F<RT_Config.pm> merely by the
264 presence of the C<gpg> or C<openssl> binaries. Systems which depended
265 on C<configure> enabling these in F<RT_Config.pm> implicitly will need
266 to pass C<--enable-gpg> to C<configure>, or alter their
267 C<RT_SiteConfig.pm> to enable the functionality explicitly.
271 In TicketSQL, "Starts = '1970-01-01'" will no longer find tickets with
272 no Starts date set. Instead, use "Starts IS NULL". As a direct
273 consequence, "Starts < 'today'" will no longer also find tickets with no
274 Starts date; use "Starts < 'today' OR Starts IS NULL" to have the
275 equivalent results in RT 4.2.
279 =head1 UPGRADING FROM 4.2.3 AND EARLIER
281 RT 4.2.4's upgrade scripts contain two fixes to normalize upgraded RTs
282 with those installed new from a release of RT 4.2.
284 We neglected to add the "Open Inactive Tickets" action mentioned earlier
285 in this documents. It was available to fresh installs but not on
286 upgrades. This Scrip Action is now created if needed.
288 RT expects the ___Approvals queue to have a special value in the
289 Disabled column so that it is hidden B<but> tickets can still be created
290 (normal disabled Queues disallow ticket creation). Users who enabled
291 and then disabled the Queue on earlier releases will have the incorrect
292 Disabled value, so we fix that. A similar problem applies to the
293 lifecycle, which must be set to the internal "approvals" lifecycle --
294 which is not listed as an option. RT 4.2.4 also includes enhancements
295 to the Queue admin page for ___Approvals to prevent editing things which
296 might cause problems.
298 =head1 UPGRADING FROM 4.2.5 AND EARLIER
300 RT 4.2.6 includes a new Scrip Action "Notify Owner or AdminCc". This
301 action will send the given correspondence to the Owner, if not Nobody,
302 otherwise it will notify the AdminCcs. If using this, you will likely
303 want to modify or remove the Notify Owner and AdminCcs scrip to avoid
304 duplicate notifications. This Scrip Action is not used in any default
307 =head1 UPGRADING FROM 4.2.6 AND EARLIER
309 The C<$LogoImageHeight> and C<$LogoImageWidth> configuration options
310 have been overridden by CSS since 4.0.0, and thus did not affect
311 display. They have been removed, and setting them will trigger an
312 informational message that setting them is ineffective.
314 =head1 UPGRADING FROM 4.2.9 AND EARLIER
316 An additional optional dependency, L<HTML::FormatExternal>, has been
317 added. This allows RT to use C<w3m>, C<elinks>, C<html2text>, or other
318 external tools to render HTML to text. This dependency is not installed
319 by default; however, its use is strongly encouraged, and will resolve
320 issues with blank outgoing emails.
322 =head1 UPGRADING FROM 4.2.10 AND EARLIER
324 The C<$DatabaseRequireSSL> option has never affected whether the
325 database connection was performed using SSL, even under Postgres; the
326 functionality can now be implemented via C<%DatabaseExtraDSN>.
327 C<$DatabaseRequireSSL> has been removed, and setting it will trigger an
328 informational message that setting it is ineffective.
330 The full-text indexing defaults for PostgreSQL have changed; GiST is now
331 the suggested index, as well as storing data in a separate
332 AttachmentsIndex table. Both changes improve lookup speed. For
333 improved search performance, you may wish to drop existing C<tsvector>
334 and C<GIN> indexes on C<Attachments>, and re-generate the index using
335 C<rt-setup-fulltext-index>.