Dev -> 4.0.6. Clean upgrade from 4.0.5-5.
[usit-rt.git] / docs / UPGRADING-4.0
CommitLineData
84fb5b46
MKG
1Common Issues
2
3RT now defaults to a database name of rt4 and an installation root of /opt/rt4.
4
5If you are upgrading, you will likely want to specify that your database
6is still named rt3 (or import a backup of your database as rt4 so that
7you can feel more confident making the upgrade).
8
9You really shouldn't install RT4 into your RT3 source tree (/opt/rt3)
10and instead should be using make install to set up a clean environment.
11This will allow you to evaluate your local modifications and configuration
12changes as you migrate to 4.0.
13
14If you choose to force RT to install into /opt/rt3, or another existing RT 3.x
15install location, you will encounter issues because we removed the _Overlay
16files (such as Ticket_Overlay.pm) and relocated other files. You will
17need to manually remove these files after the upgrade or RT will fail.
18After making a complete backup of your /opt/rt3 install, you might use a
19command like the following to remove the _Overlay files:
20
21 find /opt/rt3/lib/ -type f -name '*_Overlay*' -delete
22
23RT has also changed how web deployment works; you will need to review
24docs/web_deployment.pod for current instructions. The old
25`fastcgi_server`, `webmux.pl`, and `mason_handler.*` files will not
26work with RT 4.0, and should be removed to reduce confusion.
27
28*******
29RT_SiteConfig.pm
30
31You will need to carefully review your local settings when moving from
323.8 to 4.0.
33
34If you were adding your own custom statuses in earlier versions of RT,
35using ActiveStatus or InactiveStatus you will need to port these to use
36the new Lifecycles functionality. You can read more about it in
37RT_Config.pm. In most cases, you can do this by extending the default
38active and inactive lists.
39
40*******
41Upgrading sessions on MySQL
42
43In 4.0.0rc2, RT began shipping an updated schema for the sesions table
44that specificies a character set as well as making the table InnoDB. As
45part of the upgrade process, your sessions table will be dropped and
46recreated with the new schema.
47
48*******
49UPGRADING FROM RT 3.8.x and RTFM 2.1 or greater
50
51RT4 now includes an Articles functionality, merged from RTFM.
52You should not install and enable the RT::FM plugin separately on RT 4.
53If you have existing data in RTFM, you can use the etc/upgrade/upgrade-articles
54script to upgrade that data.
55
56When running normal upgrade scripts, RT will warn if it finds existing
57RTFM tables that contain data and point you to the upgrade-articles script.
58
59This script should be run from your RT tarball. It will immediately
60begin populating your new RT4 tables with data from RTFM. If you have
61browsed in the RT4 UI and created new classes and articles, this script
62will fail spectacularly. Do *not* run this except on a fresh upgrade of
63RT.
64
65You can run this as
66
67 etc/upgrade/upgrade-articles
68
69It will ouput a lot of data about what it is changing. You should
70review this for errors.
71
72If you are running RTFM 2.0 with a release of RT, there isn't currently an upgrade
73script that can port RTFM's internal CustomField and Transaction data to RT4.
74
75You must also remove RT::FM from your @Plugins line in RT_SiteConfig.pm.
76
77*******
78The deprecated classes RT::Action::Generic, RT::Condition::Generic and RT::Search::Generic
79have been removed, but you shouldn't have been using them anyway. You should have been using
80RT::Action, RT::Condition and RT::Search, respectively.
81
82* The "Rights Delegation" and "Personal Groups" features have been removed.
83
84* Replace the following code in templates:
85
86 [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]
87
88with
89
90 { $Ticket->SubjectTag }
91
92* Unique names are now enforced for user defined groups. New groups cannot be
93 created with a duplicate name and existing groups cannot be renamed to an
94 in-use name. The admin interface will warn about existing groups with
95 duplicate names. Although the groups will still function, some parts of the
96 interface (rights management, subgroup membership) may not work as expected
97 with duplicate names. Running
98
99 /opt/rt4/sbin/rt-validator --check
100
101 will report duplicate group names, and running it with --resolve will fix
102 duplicates by appending the group id to the name.
103
104 Nota Bene: As a result of differing indexes in the schema files, Postgres and
105 SQLite RT databases have enforced group name uniqueness for many years at the
106 database level.
107
108*******
b5747ff2
MKG
109
110UPGRADING FROM 4.0.5 and earlier - Changes:
111
112The fix for an attribute truncation bug on MySQL requires a small ALTER TABLE.
113Be sure you run `make upgrade-database` to apply this change automatically.
114The bug primarily manifested when uploading large logos in the theme editor on
115MySQL. Refer to etc/upgrade/4.0.6/schema.mysql for the actual ALTER TABLE that
116will be run.
117
118*******
119The web-based query builder now uses Queue limits to restrict the set of
120displayed statuses and owners. As part of this change, the %cfqueues
121parameter was renamed to %Queues; if you have local modifications to any
122of the following Mason templates, this feature will not function
123correctly:
124
125 share/html/Elements/SelectOwner
126 share/html/Elements/SelectStatus
127 share/html/Prefs/Search.html
128 share/html/Search/Build.html
129 share/html/Search/Elements/BuildFormatString
130 share/html/Search/Elements/PickCFs
131 share/html/Search/Elements/PickCriteria