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