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 =cut