Upgrade to 4.2.8
[usit-rt.git] / docs / UPGRADING-3.8
1 =head1 UPGRADING FROM 3.8.8 AND EARLIER
2
3 Previous versions of RT used a password hashing scheme which was too easy to
4 reverse, which could allow attackers with read access to the RT database to
5 possibly compromise users' passwords.  Even if RT does no password
6 authentication itself, it may still store these weak password hashes -- using
7 ExternalAuth does not guarantee that you are not vulnerable!  To upgrade
8 stored passwords to a stronger hash, run:
9
10     perl etc/upgrade/vulnerable-passwords
11
12 We have also proved that it's possible to delete a notable set of records from
13 Transactions table without losing functionality. To delete these records, run
14 the following script:
15
16     perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/shrink_transactions_table.pl
17
18 If you chose not to run the shrink_cgm_table.pl script when you upgraded to
19 3.8, you should read more about it below and run it at this point.
20
21 The default for $MessageBoxWrap is now SOFT and $MessageBoxWidth is now unset
22 by default.  This means the message box will expand to fill all the available
23 width.  $MessageBoxWrap is also overridable by the user now.  These changes
24 accommodate the new default two column layout for ticket create and update
25 pages.  You may turn this layout off by setting $UseSideBySideLayout to 0.  To
26 retain the original behavior, set $MessageBoxWrap to HARD and $MessageBoxWidth
27 to 72.
28
29
30 =head1 UPGRADING FROM 3.8.7 AND EARLIER
31
32 RT's ChartFont option has been changed from a string to a hash which lets you
33 specify per-language fonts. RT now comes with a better default font for
34 charts, too.  You should either update your 'ChartFont' option to match the
35 new format, or consider trying the new default.
36
37 RT now gives you more precise control over the order in which custom fields
38 are displayed.  This change requires some small changes to your currently
39 saved custom field orders.  RT will automatically clean up your existing
40 custom fields when you run the standard database upgrade steps.  After that
41 cleanup, you should make sure that custom fields are ordered in a way that you
42 and your users find pleasing.
43
44
45 =head1 UPGRADING FROM 3.8.6 AND EARLIER
46
47 For MySQL and Oracle users: if you upgraded from a version of RT earlier than
48 3.7.81, you should already have a CachedGroupMembers3 index on your
49 CachedGroupMembers table.  If you did a clean install of RT somewhere in the
50 3.8 release series, you most likely don't have this index.  You can add it
51 manually with:
52
53   CREATE INDEX CachedGroupMembers3 on CachedGroupMembers (MemberId, ImmediateParentId);
54
55
56 =head1 UPGRADING FROM 3.8.5 AND EARLIER
57
58 You can now forward an entire Ticket history (in addition to specific
59 transactions) but this requires a new Template called "Forward Ticket".  This
60 template will be added as part of the standard database upgrade step.
61
62 Custom fields with categories can optionally be split out into hierarchical
63 custom fields.  If you wish to convert your old category-based custom fields,
64 run:
65
66     perl etc/upgrade/split-out-cf-categories
67
68 It will prompt you for each custom field with categories that it finds, and
69 the name of the custom field to create to store the categories.
70
71 If you were using the LocalizedDateTime RT::Date formatter from custom code,
72 and passing a DateFormat or TimeFormat argument, you need to switch from the
73 strftime methods to the cldr methods; that is,
74 'full_date_format' becomes 'date_format_full'.
75
76 You may also have done this from your RT_SiteConfig.pm, using:
77
78     Set($DateTimeFormat, {
79         Format => 'LocalizedDateTime',
80         DateFormat => 'medium_date_format',
81     );
82
83 Which would need to be changed to:
84
85     Set($DateTimeFormat, {
86         Format => 'LocalizedDateTime',
87         DateFormat => 'date_format_medium',
88     );
89
90
91 =head1 UPGRADING FROM 3.8.3 AND EARLIER
92
93 Arguments to the NotifyGroup Scrip Action will be updated as part of the
94 standard database upgrade process.
95
96
97 =head1 UPGRADING FROM 3.8.2 AND EARLIER
98
99 A new scrip condition, 'On Reject', has been added.
100
101
102 =head1 UPGRADING FROM 3.8.1 AND EARLIER
103
104 When using Oracle, $DatabaseName is now used as SID, so RT can connect without
105 environment variables or tnsnames.ora file. Because of this change, your RT
106 instance may loose its ability to connect to your DB; to resolve this, you
107 will need to update RT's configuration and restart your web server.  Example
108 configuration:
109
110     Set($DatabaseType, 'Oracle');
111     Set($DatabaseHost, '192.168.0.1');
112     # undefined port => will try both 1526 and 1521
113     Set($DatabasePort, undef);
114     # ORACLE SID
115     Set($DatabaseName, 'XE');
116     # user for RT in Oracle, RT's tables in his schema
117     Set($DatabaseUser, 'test');
118     # above user's password
119     Set($DatabasePassword, 'test');
120
121 If you want a user to be able to access the Approvals tools (a.k.a.  the
122 Approvals tab), you must grant that user the "ShowApprovalsTab" right.
123
124
125 =head1 UPGRADING FROM 3.8.0 AND EARLIER
126
127 The TicketSQL syntax for bookmarked tickets has been changed.  Specifically,
128 the new phrasing is "id = '__Bookmarked__'", rather than the old
129 "__Bookmarks__".  The old form will remain, for backwards compatibility.  The
130 standard database upgrade process will only automatically change the
131 global 'Bookmarked Tickets' search
132
133
134 =head1 UPGRADING FROM 3.7.85 AND EARLIER
135
136 We have proved that it is possible to delete a large set of records from the
137 CachedGroupMembers table without losing functionality; in fact, failing to do
138 so may result in occasional problems where RT miscounts users, particularly in
139 the chart functionality.  To delete these records run the following script:
140
141     perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/shrink_cgm_table.pl
142
143 After you run this, you will have significantly reduced the number of records
144 in your CachedGroupMembers table, and may need to tell your database to
145 refresh indexes/statistics.  Please consult your DBA for specific instructions
146 for your database.
147
148
149 =head1 UPGRADING FROM 3.7.81 AND EARLIER
150
151 RT::Extension::BrandedQueues has been integrated into core, and the handling
152 of subject tags has changed as a consequence.  You will need to modify any of
153 your email templates which use the $rtname variable, in order to make them
154 respect the per-queue subject tags. To edit your templates, log into RT as
155 your administrative user, then click:
156
157     Configuration -> Global -> Templates -> Select -> <Some template name>
158
159 The only template which ships with RT which needs updating is the "Autoreply"
160 template, which includes this line:
161
162     "There is no need to reply to this message right now.  Your ticket has
163     been assigned an ID of [{$rtname} #{$Ticket->id()}]."
164
165 Change this line to read:
166
167     "There is no need to reply to this message right now.  Your ticket has
168     been assigned an ID of { $Ticket->SubjectTag }."
169
170 If you were previously using RT::Extension::BrandedQueues, you MUST uninstall
171 it before upgrading.
172
173 RT::Action::LinearEscalate extension has been integrated into core, so you
174 MUST uninstall it before upgrading.
175
176 RT::Extension::iCal has been integrated into core, so you MUST uninstall it
177 before upgrading. In addition, you must run etc/upgrade/3.8-ical-extension
178 script to convert old data.
179
180
181 =head1 UPGRADING FROM 3.7.80 AND EARLIER
182
183 Added indexes to CachedGroupMembers for MySQL and Oracle.  If you have
184 previously installed RTx-Shredder, you may already have these indexes.  You
185 can see the indexes by looking at etc/upgrade/3.7.81/schema.*
186
187 These indexes may take a very long time to create.