]>
Commit | Line | Data |
---|---|---|
af59614d MKG |
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 | ||
320f0092 MKG |
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 | ||
af59614d MKG |
311 | =back |
312 | ||
c33a4027 MKG |
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 | ||
af59614d | 348 | =cut |