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 docs/web_deployment.pod for current instructions.  The old `fastcgi_server`,
  28 `webmux.pl`, and `mason_handler.*` files will not work with RT 4.0, and should
  29 be removed to reduce confusion.
  30
  31
  32 =head2 RT_SiteConfig.pm
  33
  34 You will need to carefully review your local settings when moving from 3.8 to
  35 4.0.
  36
  37 If you were adding your own custom statuses in earlier versions of RT, using
  38 ActiveStatus or InactiveStatus you will need to port these to use the new
  39 Lifecycles functionality.  You can read more about it in RT_Config.pm.  In
  40 most cases, you can do this by extending the default active and inactive
  41 lists.
  42
  43
  44 =head2 Upgrading sessions on MySQL
  45
  46 In 4.0.0rc2, RT began shipping an updated schema for the sesions table that
  47 specificies a character set as well as making the table InnoDB.  As part of
  48 the upgrade process, your sessions table will be dropped and recreated with
  49 the new schema.
  50
  51
  52 =head2 Upgrading from installs with RTFM
  53
  54 RT4 now includes an Articles functionality, merged from RTFM.  You should not
  55 install and enable the RT::FM plugin separately on RT 4.  If you have existing
  56 data in RTFM, you can use the etc/upgrade/upgrade-articles script to upgrade
  57 that data.
  58
  59 When running normal upgrade scripts, RT will warn if it finds existing RTFM
  60 tables that contain data and point you to the upgrade-articles script.
  61
  62 This script should be run from your RT tarball.  It will immediately begin
  63 populating your new RT4 tables with data from RTFM.  If you have browsed in
  64 the RT4 UI and created new classes and articles, this script will fail
  65 spectacularly.  Do *not* run this except on a fresh upgrade of RT.
  66
  67 You can run this as
  68
  69   etc/upgrade/upgrade-articles
  70
  71 It will ouput a lot of data about what it is changing.  You should review this
  72 for errors.
  73
  74 If you are running RTFM 2.0 with a release of RT, there isn't currently an
  75 upgrade script that can port RTFM's internal CustomField and Transaction data
  76 to RT4.
  77
  78 You must also remove RT::FM from your @Plugins line in RT_SiteConfig.pm.
  79
  80
  81 =head2 Removals and updates
  82
  83 The deprecated classes RT::Action::Generic, RT::Condition::Generic and
  84 RT::Search::Generic have been removed, but you shouldn't have been using them
  85 anyway. You should have been using RT::Action, RT::Condition and RT::Search,
  86 respectively.
  87
  88 =over
  89
  90 =item *
  91
  92 The "Rights Delegation" and "Personal Groups" features have been removed.
  93
  94 =item *
  95
  96 Replace the following code in templates:
  97
  98     [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]
  99
 100 with
 101
 102     { $Ticket->SubjectTag }
 103
 104 =item *
 105
 106 Unique names are now enforced for user defined groups.  New groups cannot be
 107 created with a duplicate name and existing groups cannot be renamed to an
 108 in-use name.  The admin interface will warn about existing groups with
 109 duplicate names.  Although the groups will still function, some parts of the
 110 interface (rights management, subgroup membership) may not work as expected
 111 with duplicate names.  Running
 112
 113     /opt/rt4/sbin/rt-validator --check
 114
 115 will report duplicate group names, and running it with --resolve will fix
 116 duplicates by appending the group id to the name.
 117
 118 Nota Bene: As a result of differing indexes in the schema files, Postgres and
 119 SQLite RT databases have enforced group name uniqueness for many years at the
 120 database level.
 121
 122 =back
 123
 124
 125
 126 =head1 UPGRADING FROM 4.0.5 AND EARLIER
 127
 128 =head2 Schema updates
 129
 130 The fix for an attribute truncation bug on MySQL requires a small ALTER TABLE.
 131 Be sure you run `make upgrade-database` to apply this change automatically.
 132 The bug primarily manifested when uploading large logos in the theme editor on
 133 MySQL.  Refer to etc/upgrade/4.0.6/schema.mysql for the actual ALTER TABLE
 134 that will be run.
 135
 136
 137 =head2 Query Builder
 138
 139 The web-based query builder now uses Queue limits to restrict the set of
 140 displayed statuses and owners.  As part of this change, the %cfqueues
 141 parameter was renamed to %Queues; if you have local modifications to any of
 142 the following Mason templates, this feature will not function correctly:
 143
 144     share/html/Elements/SelectOwner
 145     share/html/Elements/SelectStatus
 146     share/html/Prefs/Search.html
 147     share/html/Search/Build.html
 148     share/html/Search/Elements/BuildFormatString
 149     share/html/Search/Elements/PickCFs
 150     share/html/Search/Elements/PickCriteria
 151
 152 =head1 UPGRADING FROM 4.0.8 AND EARLIER
 153
 154 =head2 Data upgrades
 155
 156 Previously, the default lifecycle was stored in Queues.Lifecycle as
 157 NULL. To simplify code, RT now stores the string 'default' to match the
 158 name of the Lifecycle.
 159
 160 The 3.9.2 upgrade step removed all enabled Personal Groups, but missed
 161 any disabled groups. We catch and clean up the disabled Personal groups
 162 during the 4.0.9 upgrade step.
 163
 164 =head2 Javascript Changes
 165
 166 If you have set a custom @JSFiles in RT_SiteConfig.pm, you will need to
 167 amend this to include the new jquery.cookie.js file added to
 168 RT_Config.pm.  If you are using an extension that requires manually
 169 tweaking @JSFiles, please contact the developer and ask them to use
 170 RT->AddJavaScript in their extension to avoid these upgrade problems.
 171
 172 If you have @JSFiles set in your RT_SiteConfig.pm but it appears to be
 173 the same as RT_Config.pm (no local js files added) you can safely remove
 174 the whole setting from RT_SiteConfig.pm and allow our default to be
 175 used.