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