Upgrade to 4.0.13
[usit-rt.git] / docs / UPGRADING-4.0
CommitLineData
dab09ea8 1=head1 UPGRADING FROM BEFORE 4.0.0
84fb5b46 2
dab09ea8 3=head2 Common issues
84fb5b46 4
dab09ea8
MKG
5RT now defaults to a database name of rt4 and an installation root of
6/opt/rt4.
84fb5b46 7
dab09ea8
MKG
8If you are upgrading, you will likely want to specify that your database is
9still named rt3 (or import a backup of your database as rt4 so that you can
10feel more confident making the upgrade).
11
12You really shouldn't install RT4 into your RT3 source tree (/opt/rt3) and
13instead should be using make install to set up a clean environment. This will
14allow you to evaluate your local modifications and configuration changes as
15you migrate to 4.0.
84fb5b46
MKG
16
17If you choose to force RT to install into /opt/rt3, or another existing RT 3.x
18install location, you will encounter issues because we removed the _Overlay
dab09ea8
MKG
19files (such as Ticket_Overlay.pm) and relocated other files. You will need to
20manually remove these files after the upgrade or RT will fail. After making a
21complete backup of your /opt/rt3 install, you might use a command like the
22following to remove the _Overlay files:
84fb5b46
MKG
23
24 find /opt/rt3/lib/ -type f -name '*_Overlay*' -delete
25
26RT has also changed how web deployment works; you will need to review
c36a7e1d
MKG
27F<docs/web_deployment.pod> for current instructions. The old
28`fastcgi_server`, `webmux.pl`, and `mason_handler.*` files will not
29work with RT 4.0, and should be removed to reduce confusion.
30
31If you deploy RT with mod_perl, Apache will no longer start with C<SetHandler>
32set to `perl-script`. F<docs/web_deployment.pod> contains the
33new configuration.
dab09ea8
MKG
34
35
36=head2 RT_SiteConfig.pm
37
38You will need to carefully review your local settings when moving from 3.8 to
394.0.
84fb5b46 40
dab09ea8
MKG
41If you were adding your own custom statuses in earlier versions of RT, using
42ActiveStatus or InactiveStatus you will need to port these to use the new
43Lifecycles functionality. You can read more about it in RT_Config.pm. In
44most cases, you can do this by extending the default active and inactive
45lists.
84fb5b46 46
84fb5b46 47
dab09ea8 48=head2 Upgrading sessions on MySQL
84fb5b46 49
dab09ea8
MKG
50In 4.0.0rc2, RT began shipping an updated schema for the sesions table that
51specificies a character set as well as making the table InnoDB. As part of
52the upgrade process, your sessions table will be dropped and recreated with
53the new schema.
84fb5b46 54
84fb5b46 55
dab09ea8 56=head2 Upgrading from installs with RTFM
84fb5b46 57
dab09ea8
MKG
58RT4 now includes an Articles functionality, merged from RTFM. You should not
59install and enable the RT::FM plugin separately on RT 4. If you have existing
60data in RTFM, you can use the etc/upgrade/upgrade-articles script to upgrade
61that data.
84fb5b46 62
dab09ea8
MKG
63When running normal upgrade scripts, RT will warn if it finds existing RTFM
64tables that contain data and point you to the upgrade-articles script.
84fb5b46 65
dab09ea8
MKG
66This script should be run from your RT tarball. It will immediately begin
67populating your new RT4 tables with data from RTFM. If you have browsed in
68the RT4 UI and created new classes and articles, this script will fail
69spectacularly. Do *not* run this except on a fresh upgrade of RT.
84fb5b46
MKG
70
71You can run this as
72
73 etc/upgrade/upgrade-articles
74
dab09ea8
MKG
75It will ouput a lot of data about what it is changing. You should review this
76for errors.
84fb5b46 77
dab09ea8
MKG
78If you are running RTFM 2.0 with a release of RT, there isn't currently an
79upgrade script that can port RTFM's internal CustomField and Transaction data
80to RT4.
84fb5b46
MKG
81
82You must also remove RT::FM from your @Plugins line in RT_SiteConfig.pm.
83
84fb5b46 84
dab09ea8
MKG
85=head2 Removals and updates
86
87The deprecated classes RT::Action::Generic, RT::Condition::Generic and
88RT::Search::Generic have been removed, but you shouldn't have been using them
89anyway. You should have been using RT::Action, RT::Condition and RT::Search,
90respectively.
91
92=over
93
94=item *
95
96The "Rights Delegation" and "Personal Groups" features have been removed.
84fb5b46 97
dab09ea8
MKG
98=item *
99
100Replace the following code in templates:
84fb5b46
MKG
101
102 [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]
103
104with
105
106 { $Ticket->SubjectTag }
107
dab09ea8
MKG
108=item *
109
110Unique names are now enforced for user defined groups. New groups cannot be
111created with a duplicate name and existing groups cannot be renamed to an
112in-use name. The admin interface will warn about existing groups with
113duplicate names. Although the groups will still function, some parts of the
114interface (rights management, subgroup membership) may not work as expected
115with duplicate names. Running
84fb5b46
MKG
116
117 /opt/rt4/sbin/rt-validator --check
118
dab09ea8
MKG
119will report duplicate group names, and running it with --resolve will fix
120duplicates by appending the group id to the name.
121
122Nota Bene: As a result of differing indexes in the schema files, Postgres and
123SQLite RT databases have enforced group name uniqueness for many years at the
124database level.
125
126=back
84fb5b46 127
84fb5b46 128
b5747ff2 129
dab09ea8
MKG
130=head1 UPGRADING FROM 4.0.5 AND EARLIER
131
132=head2 Schema updates
b5747ff2
MKG
133
134The fix for an attribute truncation bug on MySQL requires a small ALTER TABLE.
135Be sure you run `make upgrade-database` to apply this change automatically.
136The bug primarily manifested when uploading large logos in the theme editor on
dab09ea8
MKG
137MySQL. Refer to etc/upgrade/4.0.6/schema.mysql for the actual ALTER TABLE
138that will be run.
139
140
141=head2 Query Builder
b5747ff2 142
b5747ff2
MKG
143The web-based query builder now uses Queue limits to restrict the set of
144displayed statuses and owners. As part of this change, the %cfqueues
dab09ea8
MKG
145parameter was renamed to %Queues; if you have local modifications to any of
146the following Mason templates, this feature will not function correctly:
b5747ff2
MKG
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
403d7b0b
MKG
155
156=head1 UPGRADING FROM 4.0.8 AND EARLIER
157
158=head2 Data upgrades
159
160Previously, the default lifecycle was stored in Queues.Lifecycle as
161NULL. To simplify code, RT now stores the string 'default' to match the
162name of the Lifecycle.
163
164The 3.9.2 upgrade step removed all enabled Personal Groups, but missed
165any disabled groups. We catch and clean up the disabled Personal groups
166during the 4.0.9 upgrade step.
167
168=head2 Javascript Changes
169
170If you have set a custom @JSFiles in RT_SiteConfig.pm, you will need to
171amend this to include the new jquery.cookie.js file added to
172RT_Config.pm. If you are using an extension that requires manually
173tweaking @JSFiles, please contact the developer and ask them to use
174RT->AddJavaScript in their extension to avoid these upgrade problems.
175
176If you have @JSFiles set in your RT_SiteConfig.pm but it appears to be
177the same as RT_Config.pm (no local js files added) you can safely remove
178the whole setting from RT_SiteConfig.pm and allow our default to be
179used.
5b0d0914
MKG
180
181=head1 UPGRADING FROM 4.0.11 AND EARLIER
182
183=head2 Data Upgrades
184
185Previous versions of RT allowed you to create Tickets with a Type of
186'Ticket', 'Approval' or 'Reminder' instead of the correct 'ticket'.
187Existing Types are updated in the database and the RT API now corrects
188these types before insertion.
189
190Site-specific custom types (anything but ticket, reminder or approval)
191are not affected by these changes.