Master to 4.2.8
[usit-rt.git] / docs / UPGRADING-4.2
1 =head1 UPGRADING FROM RT 4.0.0 and greater
2
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.
9
10 =over
11
12 =item *
13
14 The L<RT_Config/$UseSQLForACLChecks> option defaults to on.  This provides
15 a number of improvements, most notably no longer showing pages of empty results
16 if the user doesn't have permissions to view the tickets in question.
17 It may, in some cases, have performance impacts, but these have been
18 found to be minimal in existing 4.0 installs.
19
20 =item *
21
22 The C<$LogToScreen> config setting is now named
23 L<< "C<$LogToSTDERR>"|RT_Config/"$LogToSyslog, $LogToSTDERR" >> which
24 better describes what the log level controls.  Setting C<$LogToScreen> will
25 still work, but an informational notice will be issued on server start telling
26 you about the rename.  To avoid this you should set C<$LogToSTDERR> instead.
27
28 =item *
29
30 The link direction and type maps are consolidated into RT::Link.  If you
31 wrote local customizations or extensions utilizing C<%RT::Ticket::LINKDIRMAP>,
32 C<%RT::Ticket::LINKTYPEMAP>, C<RT::Ticket-E<gt>LINKDIRMAP>,
33 C<RT::Ticket-E<gt>LINKTYPEMAP>, or C<%RT::Record::LINKDIRMAP>, you will need to
34 switch to C<%RT::Link::DIRMAP> and C<%RT::Link::TYPEMAP>.
35
36 =item *
37
38 C<$LinkTransactionsRun1Scrip> is removed.  If you were relying on this behavior
39 (by setting it to 1), you should adjust your scrips to ignore one of the link
40 transactions.
41
42 =item *
43
44 The C<$AttachmentUnits> option was removed in preference of always displaying in
45 megabytes, kilobytes, or bytes as appropriate.  The option was incompletely
46 implemented and controlled display in the attachments list but not history.
47
48 =item *
49
50 MakeClicky handlers added via a callback are now passed an "object" key in
51 the parameter hash instead of "ticket".  The object may be any L<RT::Record>
52 subclass.
53
54 =item *
55
56 C<$MessageBoxWrap> was removed.  Wrapping is now always C<SOFT>.  If you want hard
57 line breaks, enter them manually.
58
59 =item *
60
61 C<ShowUser> handlers (C</Elements/ShowUser*>) have moved out of Mason components
62 and into C<RT::User> methods.  Any custom username formats will need to be
63 reimplemented as C<RT::User> methods.  Renaming should follow that of the core
64 components:
65
66     /Elements/ShowUserConcise => RT::User->_FormatUserConcise
67     /Elements/ShowUserVerbose => RT::User->_FormatUserVerbose
68
69 The C<_FormatUser*> methods are passed a hash containing the keys C<User> and
70 C<Address>, which have the same properties as before.
71
72 =item *
73
74 Rich text (HTML) messages are now preferred for display.  If you prefer plain
75 text messages, set L<RT_Config/$PreferRichText> to 0.
76
77 =item *
78
79 User email addresses are now validated by default and multiple,
80 comma-separated addresses for a single user are no longer allowed.  Existing
81 users with invalid addresses will continue to work until the next time they
82 are updated by an administrator on the modify user page.  If you prefer no
83 address validation, set L<RT_Config/$ValidateUserEmailAddresses> to 0.
84
85 =item *
86
87 The C<smtp> option for L<RT_Config/$MailCommand>, along with the associated
88 C<$SMTPServer>, C<$SMTPFrom>, and C<$SMTPDebug> options, has been removed
89 because it did not guarantee delivery.  Instead, use a local MTA for
90 outgoing mail, via the 'sendmailpipe' setting to C<$MailCommand>.
91
92 =item *
93
94 The L<RT_Config/@JSFiles> config now only keeps additional JavaScript filenames; if
95 you had copied C<@JSFiles> to add extra entries in your C<RT_SiteConfig.pm>,
96 remove the core JS from the list, or RT will serve those files
97 multiple times.
98
99 =item *
100
101 The C<$DeferTransactionLoading> option was combined into the new option
102 L<RT_Config/$ShowHistory>. If you had enabled C<$DeferTransactionLoading>,
103 you may want to set C<$ShowHistory> to C<click>.  However, C<$ShowHistory>
104 provides a new mode, C<delay>, which is the default and may be a more
105 appealing alternative to C<click>.
106
107 =item *
108
109 A C<Status> transaction is now recorded when a ticket status changes as a
110 result of a queue change.  Scrips with conditions relying on Status changes
111 may start to trigger on these transitions; previously these Status changes
112 never triggered scrips.
113
114 =item *
115
116 The C<Googleish> search has been renamed to C<Simple>. If you were
117 using this in an L<< C<rt-crontool> >> cronjob or had used a
118 C<Googleish_Local.pm> to add features, you will need to convert to
119 using L<RT::Search::Simple> instead.
120
121 =item *
122
123 On merge, RT retains transactions from both tickets. Previously, RT
124 also recorded explicit time change transactions during a
125 merge to adjust the total time spent. This caused the total time
126 spent, as summed from transactions, to be different from the ticket's
127 overall time spent. This has been fixed: time is adjusted during the
128 merge commit itself, removing the need for the confusing
129 extra transactions, and keeping the summed time spent consistent.
130
131 In order to fix the history records of old ticket you can run the following
132 command:
133
134     perl -I /opt/rt4/local/lib/ -I /opt/rt4/lib/ etc/upgrade/time-worked-history.pl
135
136 This command deletes records from the Transactions table. This script can only fix
137 TimeWorked mismatches, but not TimeLeft or TimeEstimated.
138
139 =item *
140
141 A new action, "Open Inactive Tickets", has been added, and on new
142 installs the default scrip "On Correspond Open Tickets" has been
143 replaced by "On Correspond Open Inactive Tickets".  The key difference
144 between "Open Tickets" and "Open Inactive Tickets" is that the latter
145 will not adjust the status of a ticket if it is already active.  This
146 is particularly useful when creating complex workflows using
147 Lifecycles.
148
149 =item *
150
151 CSS is no longer processed through Mason; it's served by a proper static file
152 handler.  If you used the C<Begin> or C<End> callbacks of C<main.css> in the
153 aileron, web2, or ballard themes, you should transition to the
154 L<RT_Config/@CSSFiles> config option. If you need to target specific themes,
155 you can use the class set on the E<lt>C<body>E<gt> element (for example:
156 body.aileron).  See F<docs/customizing/styling_rt.pod> for more information
157 on custom styles.
158
159 =item *
160
161 There are now HTML versions of the standard plain text templates.  Running
162 make upgrade as described in the F<README> will insert the new templates into
163 existing installs.  While new installs use the HTML templates by default,
164 upgrades from older versions don't automatically switch to the HTML versions.
165 To switch existing scrips, run:
166
167     /opt/rt4/etc/upgrade/switch-templates-to html
168
169 To switch from HTML back to text, run:
170
171     /opt/rt4/etc/upgrade/switch-templates-to text
172
173 =item *
174
175 The Articles menu is now a top-level menu item and display is controlled by
176 the right C<ShowArticlesMenu>.  This right is only grantable globally to groups
177 or users.  During the upgrade, the new right will be automatically granted to
178 Privileged users so that the menu doesn't disappear for anyone previously
179 using it.  You may wish to revoke the right from Privileged and grant it
180 more selectively.
181
182 =item *
183
184 The Owner drop-down now only includes privileged users (no matter if
185 unprivileged users have been granted the OwnTicket right) because
186 configurations which have unprivileged Owners are exceedingly rare,
187 and granting Everyone the OwnTicket right is a common cause of
188 performance problems.  Unprivileged Owners (if they exist) may still
189 be set using the Autocompleter.
190
191 =item *
192
193 The functionality that changed the ticket status to Open when the Started
194 date is set has been moved to a Scrip called 'On transaction and SetStarted
195 Open Ticket'. If you do not depend on this functionality, the Scrip can
196 be deleted.
197
198 =item *
199
200 New installs will notify Ccs and one-time Ccs/Bccs on create and Owners on
201 create and correspond.  Upgraded installations will not.  If you'd like to
202 adjust your scrips to match the new install behavior, create and edit the
203 following scrips from the admin scrip page:
204
205 To notify Ccs on create, on the 'Create a global scrip' page:
206
207   Description: On Create Notify Ccs
208   Condition:   On Create
209   Action:      Notify Ccs
210   Template:    Correspondence in HTML
211
212 To notify one-time Ccs/Bccs on create, on the 'Create a global scrip' page:
213
214   Description: On Create Notify Other Recipients
215   Condition:   On Create
216   Action:      Notify Other Recipients
217   Template:    Correspondence in HTML
218
219 To notify Owners on create, click 'On Create Notify AdminCcs'. Change the
220 fields listed below to their corresponding values:
221
222   Description: On Create Notify Owner and AdminCcs
223   Action:      Notify Owner and AdminCcs
224
225 To notify Owners on correspond, click 'On Correspond Notify AdminCcs'. Change
226 the fields listed below to their corresponding values:
227
228   Description: On Correspond Notify Owner and AdminCcs
229   Action:      Notify Owner and AdminCcs
230
231 =item *
232
233 Notifications to AdminCcs on approvals are now handled via the New Pending
234 Approval template in the hidden ___Approvals queue.  If you customized the
235 Transaction template, you should port your changes to New Pending Approval.
236
237 =item *
238
239 On Oracle, sessions are now stored in the database by default instead of
240 on-disk.  If you wish to preserve the original behavior, ensure that
241 L<RT_Config/$WebSessionClass> is set in your C<RT_SiteConfig.pm>:
242
243     Set($WebSessionClass, "Apache::Session::File");
244
245 =item *
246
247 Configuration options dealing with "external authentication" have been
248 renamed to reduce confusion with the common extension
249 L<RT::Authen::ExternalAuth>.  The old names will work, but produce
250 deprecation warnings.  The old names, and their new counterparts, are:
251
252     WebExternalAuth           => WebRemoteUserAuth
253     WebExternalAuthContinuous => WebRemoteUserContinuous
254     WebFallbackToInternalAuth => WebFallbackToRTLogin
255     WebExternalGecos          => WebRemoteUserGecos
256     WebExternalAuto           => WebRemoteUserAutocreate
257     AutoCreate                => UserAutocreateDefaultsOnLogin
258
259 =item *
260
261 Due to many long-standing bugs and limitations, the "Offline Tool" was
262 removed.
263
264 =item *
265
266 To increase security against offline brute-force attacks, RT's default
267 password encryption has been switched to the popular bcrypt() key
268 derivation function.  Passwords cannot be automatically bulk upgraded to
269 the new format, but will be replaced with bcrypt versions upon the first
270 successful login.
271
272 =item *
273
274 We updated default "Forward" and "Forward Ticket" templates to support
275 customizing messages on forward. They will be updated automatically if you
276 didn't change them before.
277
278 But in case you have changed them already, you need to update them manually.
279 You can use $ForwardTransaction to refer to the customized message in the
280 templates, e.g. "Forward" template could be updated to:
281
282 { $ForwardTransaction->Content =~ /\S/ ? $ForwardTransaction->Content : "This is a forward of transaction #".$Transaction->id." of ticket #". $Ticket->id }
283
284 =item *
285
286 RT has generated RT-Ticket: RT-Originator: and Managed-By: headers in
287 compliance with RFC2822/6648 but we've discovered that some smarthost
288 providers are requiring strict adherence to RFC822 which mandates X-
289 prefixes on these headers. We've made this change in 4.2 for users
290 relying on those providers.
291
292 Any external scripts which were parsing on these RT mail headers will
293 need to be updated.
294
295 =item *
296
297 GnuPG and S/MIME are no longer enabled in F<RT_Config.pm> merely by the
298 presence of the C<gpg> or C<openssl> binaries.  Systems which depended
299 on C<configure> enabling these in F<RT_Config.pm> implicitly will need
300 to pass C<--enable-gpg> to C<configure>, or alter their
301 C<RT_SiteConfig.pm> to enable the functionality explicitly.
302
303 =item *
304
305 In TicketSQL, "Starts = '1970-01-01'" will no longer find tickets with
306 no Starts date set.  Instead, use "Starts IS NULL".  As a direct
307 consequence, "Starts < 'today'" will no longer also find tickets with no
308 Starts date; use "Starts < 'today' OR Starts IS NULL" to have the
309 equivalent results in RT 4.2.
310
311 =back
312
313 =head1 UPGRADING FROM 4.2.3 AND EARLIER
314
315 RT 4.2.4's upgrade scripts contain two fixes to normalize upgraded RTs
316 with those installed new from a release of RT 4.2.
317
318 We neglected to add the "Open Inactive Tickets" action mentioned earlier
319 in this documents. It was available to fresh installs but not on
320 upgrades. This Scrip Action is now created if needed.
321
322 RT expects the ___Approvals queue to have a special value in the
323 Disabled column so that it is hidden B<but> tickets can still be created
324 (normal disabled Queues disallow ticket creation).  Users who enabled
325 and then disabled the Queue on earlier releases will have the incorrect
326 Disabled value, so we fix that.  A similar problem applies to the
327 lifecycle, which must be set to the internal "approvals" lifecycle --
328 which is not listed as an option.  RT 4.2.4 also includes enhancements
329 to the Queue admin page for ___Approvals to prevent editing things which
330 might cause problems.
331
332 =head1 UPGRADING FROM 4.2.5 AND EARLIER
333
334 RT 4.2.6 includes a new Scrip Action "Notify Owner or AdminCc". This
335 action will send the given correspondence to the Owner, if not Nobody,
336 otherwise it will notify the AdminCcs. If using this, you will likely
337 want to modify or remove the Notify Owner and AdminCcs scrip to avoid
338 duplicate notifications. This Scrip Action is not used in any default
339 Scrips at this time.
340
341 =head1 UPGRADING FROM 4.2.6 AND EARLIER
342
343 The C<$LogoImageHeight> and C<$LogoImageWidth> configuration options
344 have been overridden by CSS since 4.0.0, and thus did not affect
345 display.  They have been removed, and setting them will trigger an
346 informational message that setting them is ineffective.
347
348 =cut