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