rt/docs/UPGRADING-4.0

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