rt/docs/UPGRADING-4.0

   1 =head1 UPGRADING FROM BEFORE 4.0.0
   2
   3 =head2 Common issues
   4
   5 RT now defaults to a database name of rt4 and an installation root of
   6 /opt/rt4.
   7
   8 If you are upgrading, you will likely want to specify that your database is
   9 still named rt3 (or import a backup of your database as rt4 so that you can
  10 feel more confident making the upgrade).
  11
  12 You really shouldn't install RT4 into your RT3 source tree (/opt/rt3) and
  13 instead should be using make install to set up a clean environment.  This will
  14 allow you to evaluate your local modifications and configuration changes as
  15 you migrate to 4.0.
  16
  17 If you choose to force RT to install into /opt/rt3, or another existing RT 3.x
  18 install location, you will encounter issues because we removed the _Overlay
  19 files (such as Ticket_Overlay.pm) and relocated other files.  You will need to
  20 manually remove these files after the upgrade or RT will fail.  After making a
  21 complete backup of your /opt/rt3 install, you might use a command like the
  22 following to remove the _Overlay files:
  23
  24     find /opt/rt3/lib/ -type f -name '*_Overlay*' -delete
  25
  26 RT has also changed how web deployment works; you will need to review
  27 F<docs/web_deployment.pod> for current instructions.  The old
  28 `fastcgi_server`, `webmux.pl`, and `mason_handler.*` files will not
  29 work with RT 4.0, and should be removed to reduce confusion.
  30
  31 If you deploy RT with mod_perl, Apache will no longer start with C<SetHandler>
  32 set to `perl-script`. F<docs/web_deployment.pod> contains the
  33 new configuration.
  34
  35 RT::Extension::CustomField::Checkbox has been integrated into core, so you
  36 MUST uninstall it before upgrading. In addition, you must run
  37 etc/upgrade/4.0-customfield-checkbox-extension script to convert old data.
  38
  39 =head2 RT_SiteConfig.pm
  40
  41 You will need to carefully review your local settings when moving from 3.8 to
  42 4.0.
  43
  44 If you were adding your own custom statuses in earlier versions of RT, using
  45 ActiveStatus or InactiveStatus you will need to port these to use the new
  46 Lifecycles functionality.  You can read more about it in RT_Config.pm.  In
  47 most cases, you can do this by extending the default active and inactive
  48 lists.
  49
  50
  51 =head2 Upgrading sessions on MySQL
  52
  53 In 4.0.0rc2, RT began shipping an updated schema for the sesions table that
  54 specificies a character set as well as making the table InnoDB.  As part of
  55 the upgrade process, your sessions table will be dropped and recreated with
  56 the new schema.
  57
  58
  59 =head2 Upgrading from installs with RTFM
  60
  61 RT4 now includes an Articles functionality, merged from RTFM.  You should not
  62 install and enable the RT::FM plugin separately on RT 4.  If you have existing
  63 data in RTFM, you can use the etc/upgrade/upgrade-articles script to upgrade
  64 that data.
  65
  66 When running normal upgrade scripts, RT will warn if it finds existing RTFM
  67 tables that contain data and point you to the upgrade-articles script.
  68
  69 This script should be run from your RT tarball.  It will immediately begin
  70 populating your new RT4 tables with data from RTFM.  If you have browsed in
  71 the RT4 UI and created new classes and articles, this script will fail
  72 spectacularly.  Do *not* run this except on a fresh upgrade of RT.
  73
  74 You can run this as
  75
  76   etc/upgrade/upgrade-articles
  77
  78 It will ouput a lot of data about what it is changing.  You should review this
  79 for errors.
  80
  81 If you are running RTFM 2.0 with a release of RT, there isn't currently an
  82 upgrade script that can port RTFM's internal CustomField and Transaction data
  83 to RT4.
  84
  85 You must also remove RT::FM from your @Plugins line in RT_SiteConfig.pm.
  86
  87
  88 =head2 Removals and updates
  89
  90 The deprecated classes RT::Action::Generic, RT::Condition::Generic and
  91 RT::Search::Generic have been removed, but you shouldn't have been using them
  92 anyway. You should have been using RT::Action, RT::Condition and RT::Search,
  93 respectively.
  94
  95 =over
  96
  97 =item *
  98
  99 The "Rights Delegation" and "Personal Groups" features have been removed.
 100
 101 =item *
 102
 103 Replace the following code in templates:
 104
 105     [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]
 106
 107 with
 108
 109     { $Ticket->SubjectTag }
 110
 111 =item *
 112
 113 Unique names are now enforced for user defined groups.  New groups cannot be
 114 created with a duplicate name and existing groups cannot be renamed to an
 115 in-use name.  The admin interface will warn about existing groups with
 116 duplicate names.  Although the groups will still function, some parts of the
 117 interface (rights management, subgroup membership) may not work as expected
 118 with duplicate names.  Running
 119
 120     /opt/rt4/sbin/rt-validator --check
 121
 122 will report duplicate group names, and running it with --resolve will fix
 123 duplicates by appending the group id to the name.
 124
 125 Nota Bene: As a result of differing indexes in the schema files, Postgres and
 126 SQLite RT databases have enforced group name uniqueness for many years at the
 127 database level.
 128
 129 =back
 130
 131
 132 =head2 Ticket content searches (full text search)
 133
 134 Since 4.0.0, RT's ticket content search is disabled by default because of
 135 performance issues when used without full text indexing.  For details on how to
 136 re-enable it with (or without) full text indexing, see
 137 F<docs/full_text_indexing.pod>.
 138
 139
 140
 141 =head1 UPGRADING FROM 4.0.5 AND EARLIER
 142
 143 =head2 Schema updates
 144
 145 The fix for an attribute truncation bug on MySQL requires a small ALTER TABLE.
 146 Be sure you run `make upgrade-database` to apply this change automatically.
 147 The bug primarily manifested when uploading large logos in the theme editor on
 148 MySQL.  Refer to etc/upgrade/4.0.6/schema.mysql for the actual ALTER TABLE
 149 that will be run.
 150
 151
 152 =head2 Query Builder
 153
 154 The web-based query builder now uses Queue limits to restrict the set of
 155 displayed statuses and owners.  As part of this change, the %cfqueues
 156 parameter was renamed to %Queues; if you have local modifications to any of
 157 the following Mason templates, this feature will not function correctly:
 158
 159     share/html/Elements/SelectOwner
 160     share/html/Elements/SelectStatus
 161     share/html/Prefs/Search.html
 162     share/html/Search/Build.html
 163     share/html/Search/Elements/BuildFormatString
 164     share/html/Search/Elements/PickCFs
 165     share/html/Search/Elements/PickCriteria
 166
 167 =head1 UPGRADING FROM 4.0.8 AND EARLIER
 168
 169 =head2 Data upgrades
 170
 171 Previously, the default lifecycle was stored in Queues.Lifecycle as
 172 NULL. To simplify code, RT now stores the string 'default' to match the
 173 name of the Lifecycle.
 174
 175 The 3.9.2 upgrade step removed all enabled Personal Groups, but missed
 176 any disabled groups. We catch and clean up the disabled Personal groups
 177 during the 4.0.9 upgrade step.
 178
 179 =head2 Javascript Changes
 180
 181 If you have set a custom @JSFiles in RT_SiteConfig.pm, you will need to
 182 amend this to include the new jquery.cookie.js file added to
 183 RT_Config.pm.  If you are using an extension that requires manually
 184 tweaking @JSFiles, please contact the developer and ask them to use
 185 RT->AddJavaScript in their extension to avoid these upgrade problems.
 186
 187 If you have @JSFiles set in your RT_SiteConfig.pm but it appears to be
 188 the same as RT_Config.pm (no local js files added) you can safely remove
 189 the whole setting from RT_SiteConfig.pm and allow our default to be
 190 used.
 191
 192 =head1 UPGRADING FROM 4.0.11 AND EARLIER
 193
 194 =head2 Data Upgrades
 195
 196 Previous versions of RT allowed you to create Tickets with a Type of
 197 'Ticket', 'Approval' or 'Reminder' instead of the correct 'ticket'.
 198 Existing Types are updated in the database and the RT API now corrects
 199 these types before insertion.
 200
 201 Site-specific custom types (anything but ticket, reminder or approval)
 202 are not affected by these changes.
 203
 204 =head1 UPGRADING FROM 4.0.13 AND EARLIER
 205
 206 =head2 Outgoing mail From: header
 207
 208 The "Default" key of the C<$OverrideOutgoingMailFrom> config option now,
 209 as previously documented, only applies when no ticket is involved.
 210 Previously it was also used when a ticket was involved but the
 211 associated queue had no specific correspond address.  In such cases the
 212 global correspond address is now used.
 213
 214 The config option C<$SetOutgoingMailFrom> now accepts an email address
 215 as a value which will act as a global default.  This covers the simple
 216 case of sending all bounces to a specific address, without the previous
 217 solution of resorting to defining all queues in
 218 $OverrideOutgoingMailFrom.  Any definitions in the Override option
 219 (including Default) still take precedence.  See
 220 L<RT_Config/$SetOutgoingMailFrom> for more information.
 221
 222 =head2 Reminder statuses
 223
 224 New reminders are now created in the "reminder_on_open" status defined in your
 225 lifecycles.  For the default lifecycle, this means reminders will start as
 226 "open" instead of "new".  This change is for consistency when a completed
 227 reminder is reopened at a later date.  If you use custom lifecycles and added
 228 further transition restrictions, you may need to adjust the L<"reminder_on_open"
 229 setting|RT_Config/reminder_on_open> in your lifecycles.
 230
 231 =head2 Bookmarks
 232
 233 Previously, the list of Bookmarks on your homepage was unlimited (if you
 234 had 100 bookmarked tickets, you would see a 100 item list on your RT at
 235 a Glance).  'Bookmarked Tickets' now uses the same size limits as any
 236 other search on your homepage.  This can be customized using the 'Rows
 237 per box' setting on your RT at a Glance configuration page.
 238
 239 =head2 PostgreSQL 9.2
 240
 241 If you are upgrading an RT from 3.8 (or earlier) to 4.0 on PostgreSQL
 242 9.2, you should make sure that you have installed DBD::Pg 2.19.3 or
 243 higher.  If you start your upgrade without installing a recent-enough
 244 version of DBD::Pg RT will stop the upgrade during the 3.9.8 step and
 245 remind you to upgrade DBD::Pg.  If this happens, you can re-start your
 246 upgrade by running:
 247
 248    ./sbin/rt-setup-database --action insert --datadir etc/upgrade/3.9.8/
 249
 250 Followed by re-running make upgrade-database and answering 3.9.8 when
 251 prompted for which RT version you're upgrading from.