Upgrade to 4.0.8 with mod of ExternalAuth + absolute paths to ticket-menu.
[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
dab09ea8
MKG
27docs/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
29be removed to reduce confusion.
30
31
32=head2 RT_SiteConfig.pm
33
34You will need to carefully review your local settings when moving from 3.8 to
354.0.
84fb5b46 36
dab09ea8
MKG
37If you were adding your own custom statuses in earlier versions of RT, using
38ActiveStatus or InactiveStatus you will need to port these to use the new
39Lifecycles functionality. You can read more about it in RT_Config.pm. In
40most cases, you can do this by extending the default active and inactive
41lists.
84fb5b46 42
84fb5b46 43
dab09ea8 44=head2 Upgrading sessions on MySQL
84fb5b46 45
dab09ea8
MKG
46In 4.0.0rc2, RT began shipping an updated schema for the sesions table that
47specificies a character set as well as making the table InnoDB. As part of
48the upgrade process, your sessions table will be dropped and recreated with
49the new schema.
84fb5b46 50
84fb5b46 51
dab09ea8 52=head2 Upgrading from installs with RTFM
84fb5b46 53
dab09ea8
MKG
54RT4 now includes an Articles functionality, merged from RTFM. You should not
55install and enable the RT::FM plugin separately on RT 4. If you have existing
56data in RTFM, you can use the etc/upgrade/upgrade-articles script to upgrade
57that data.
84fb5b46 58
dab09ea8
MKG
59When running normal upgrade scripts, RT will warn if it finds existing RTFM
60tables that contain data and point you to the upgrade-articles script.
84fb5b46 61
dab09ea8
MKG
62This script should be run from your RT tarball. It will immediately begin
63populating your new RT4 tables with data from RTFM. If you have browsed in
64the RT4 UI and created new classes and articles, this script will fail
65spectacularly. Do *not* run this except on a fresh upgrade of RT.
84fb5b46
MKG
66
67You can run this as
68
69 etc/upgrade/upgrade-articles
70
dab09ea8
MKG
71It will ouput a lot of data about what it is changing. You should review this
72for errors.
84fb5b46 73
dab09ea8
MKG
74If you are running RTFM 2.0 with a release of RT, there isn't currently an
75upgrade script that can port RTFM's internal CustomField and Transaction data
76to RT4.
84fb5b46
MKG
77
78You must also remove RT::FM from your @Plugins line in RT_SiteConfig.pm.
79
84fb5b46 80
dab09ea8
MKG
81=head2 Removals and updates
82
83The deprecated classes RT::Action::Generic, RT::Condition::Generic and
84RT::Search::Generic have been removed, but you shouldn't have been using them
85anyway. You should have been using RT::Action, RT::Condition and RT::Search,
86respectively.
87
88=over
89
90=item *
91
92The "Rights Delegation" and "Personal Groups" features have been removed.
84fb5b46 93
dab09ea8
MKG
94=item *
95
96Replace the following code in templates:
84fb5b46
MKG
97
98 [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]
99
100with
101
102 { $Ticket->SubjectTag }
103
dab09ea8
MKG
104=item *
105
106Unique names are now enforced for user defined groups. New groups cannot be
107created with a duplicate name and existing groups cannot be renamed to an
108in-use name. The admin interface will warn about existing groups with
109duplicate names. Although the groups will still function, some parts of the
110interface (rights management, subgroup membership) may not work as expected
111with duplicate names. Running
84fb5b46
MKG
112
113 /opt/rt4/sbin/rt-validator --check
114
dab09ea8
MKG
115will report duplicate group names, and running it with --resolve will fix
116duplicates by appending the group id to the name.
117
118Nota Bene: As a result of differing indexes in the schema files, Postgres and
119SQLite RT databases have enforced group name uniqueness for many years at the
120database level.
121
122=back
84fb5b46 123
84fb5b46 124
b5747ff2 125
dab09ea8
MKG
126=head1 UPGRADING FROM 4.0.5 AND EARLIER
127
128=head2 Schema updates
b5747ff2
MKG
129
130The fix for an attribute truncation bug on MySQL requires a small ALTER TABLE.
131Be sure you run `make upgrade-database` to apply this change automatically.
132The bug primarily manifested when uploading large logos in the theme editor on
dab09ea8
MKG
133MySQL. Refer to etc/upgrade/4.0.6/schema.mysql for the actual ALTER TABLE
134that will be run.
135
136
137=head2 Query Builder
b5747ff2 138
b5747ff2
MKG
139The web-based query builder now uses Queue limits to restrict the set of
140displayed statuses and owners. As part of this change, the %cfqueues
dab09ea8
MKG
141parameter was renamed to %Queues; if you have local modifications to any of
142the following Mason templates, this feature will not function correctly:
b5747ff2
MKG
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