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