Master to 4.2.8

[usit-rt.git] / docs / UPGRADING-4.0

=head1 UPGRADING FROM BEFORE 4.0.0

=head2 Common issues

RT now defaults to a database name of rt4 and an installation root of
/opt/rt4.

If you are upgrading, you will likely want to specify that your database is
still named rt3 (or import a backup of your database as rt4 so that you can
feel more confident making the upgrade).

You really shouldn't install RT4 into your RT3 source tree (/opt/rt3) and
instead should be using make install to set up a clean environment.  This will
allow you to evaluate your local modifications and configuration changes as
you migrate to 4.0.

If you choose to force RT to install into /opt/rt3, or another existing RT 3.x
install location, you will encounter issues because we removed the _Overlay
files (such as Ticket_Overlay.pm) and relocated other files.  You will need to
manually remove these files after the upgrade or RT will fail.  After making a
complete backup of your /opt/rt3 install, you might use a command like the
following to remove the _Overlay files:

    find /opt/rt3/lib/ -type f -name '*_Overlay*' -delete

RT has also changed how web deployment works; you will need to review
F<docs/web_deployment.pod> for current instructions.  The old
`fastcgi_server`, `webmux.pl`, and `mason_handler.*` files will not
work with RT 4.0, and should be removed to reduce confusion.

If you deploy RT with mod_perl, Apache will no longer start with C<SetHandler>
set to `perl-script`. F<docs/web_deployment.pod> contains the
new configuration.

RT::Extension::CustomField::Checkbox has been integrated into core, so you
MUST uninstall it before upgrading. In addition, you must run
etc/upgrade/4.0-customfield-checkbox-extension script to convert old data.

=head2 RT_SiteConfig.pm

You will need to carefully review your local settings when moving from 3.8 to
4.0.

If you were adding your own custom statuses in earlier versions of RT, using
ActiveStatus or InactiveStatus you will need to port these to use the new
Lifecycles functionality.  You can read more about it in RT_Config.pm.  In
most cases, you can do this by extending the default active and inactive
lists.


=head2 Upgrading sessions on MySQL

In 4.0.0rc2, RT began shipping an updated schema for the sesions table that
specificies a character set as well as making the table InnoDB.  As part of
the upgrade process, your sessions table will be dropped and recreated with
the new schema.


=head2 Upgrading from installs with RTFM

RT4 now includes an Articles functionality, merged from RTFM.  You should not
install and enable the RT::FM plugin separately on RT 4.  If you have existing
data in RTFM, you can use the etc/upgrade/upgrade-articles script to upgrade
that data.

When running normal upgrade scripts, RT will warn if it finds existing RTFM
tables that contain data and point you to the upgrade-articles script.

This script should be run from your RT tarball.  It will immediately begin
populating your new RT4 tables with data from RTFM.  If you have browsed in
the RT4 UI and created new classes and articles, this script will fail
spectacularly.  Do *not* run this except on a fresh upgrade of RT.

You can run this as

  etc/upgrade/upgrade-articles

It will ouput a lot of data about what it is changing.  You should review this
for errors.

If you are running RTFM 2.0 with a release of RT, there isn't currently an
upgrade script that can port RTFM's internal CustomField and Transaction data
to RT4.

You must also remove RT::FM from your @Plugins line in RT_SiteConfig.pm.


=head2 Removals and updates

The deprecated classes RT::Action::Generic, RT::Condition::Generic and
RT::Search::Generic have been removed, but you shouldn't have been using them
anyway. You should have been using RT::Action, RT::Condition and RT::Search,
respectively.

=over

=item *

The "Rights Delegation" and "Personal Groups" features have been removed.

=item *

Replace the following code in templates:

    [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]

with

    { $Ticket->SubjectTag }

=item *

Unique names are now enforced for user defined groups.  New groups cannot be
created with a duplicate name and existing groups cannot be renamed to an
in-use name.  The admin interface will warn about existing groups with
duplicate names.  Although the groups will still function, some parts of the
interface (rights management, subgroup membership) may not work as expected
with duplicate names.  Running

    /opt/rt4/sbin/rt-validator --check

will report duplicate group names, and running it with --resolve will fix
duplicates by appending the group id to the name.

Nota Bene: As a result of differing indexes in the schema files, Postgres and
SQLite RT databases have enforced group name uniqueness for many years at the
database level.

=back


=head2 Ticket content searches (full text search)

Since 4.0.0, RT's ticket content search is disabled by default because of
performance issues when used without full text indexing.  For details on how to
re-enable it with (or without) full text indexing, see
F<docs/full_text_indexing.pod>.



=head1 UPGRADING FROM 4.0.5 AND EARLIER

=head2 Schema updates

The fix for an attribute truncation bug on MySQL requires a small ALTER TABLE.
Be sure you run `make upgrade-database` to apply this change automatically.
The bug primarily manifested when uploading large logos in the theme editor on
MySQL.  Refer to etc/upgrade/4.0.6/schema.mysql for the actual ALTER TABLE
that will be run.


=head2 Query Builder

The web-based query builder now uses Queue limits to restrict the set of
displayed statuses and owners.  As part of this change, the %cfqueues
parameter was renamed to %Queues; if you have local modifications to any of
the following Mason templates, this feature will not function correctly:

    share/html/Elements/SelectOwner
    share/html/Elements/SelectStatus
    share/html/Prefs/Search.html
    share/html/Search/Build.html
    share/html/Search/Elements/BuildFormatString
    share/html/Search/Elements/PickCFs
    share/html/Search/Elements/PickCriteria

=head1 UPGRADING FROM 4.0.8 AND EARLIER

=head2 Data upgrades

Previously, the default lifecycle was stored in Queues.Lifecycle as
NULL. To simplify code, RT now stores the string 'default' to match the
name of the Lifecycle.

The 3.9.2 upgrade step removed all enabled Personal Groups, but missed
any disabled groups. We catch and clean up the disabled Personal groups
during the 4.0.9 upgrade step.

=head2 Javascript Changes

If you have set a custom @JSFiles in RT_SiteConfig.pm, you will need to
amend this to include the new jquery.cookie.js file added to
RT_Config.pm.  If you are using an extension that requires manually
tweaking @JSFiles, please contact the developer and ask them to use
RT->AddJavaScript in their extension to avoid these upgrade problems.

If you have @JSFiles set in your RT_SiteConfig.pm but it appears to be
the same as RT_Config.pm (no local js files added) you can safely remove
the whole setting from RT_SiteConfig.pm and allow our default to be
used.

=head1 UPGRADING FROM 4.0.11 AND EARLIER

=head2 Data Upgrades

Previous versions of RT allowed you to create Tickets with a Type of
'Ticket', 'Approval' or 'Reminder' instead of the correct 'ticket'.
Existing Types are updated in the database and the RT API now corrects
these types before insertion.

Site-specific custom types (anything but ticket, reminder or approval)
are not affected by these changes.

=head1 UPGRADING FROM 4.0.13 AND EARLIER

=head2 Outgoing mail From: header

The "Default" key of the C<$OverrideOutgoingMailFrom> config option now,
as previously documented, only applies when no ticket is involved.
Previously it was also used when a ticket was involved but the
associated queue had no specific correspond address.  In such cases the
global correspond address is now used.

The config option C<$SetOutgoingMailFrom> now accepts an email address
as a value which will act as a global default.  This covers the simple
case of sending all bounces to a specific address, without the previous
solution of resorting to defining all queues in
$OverrideOutgoingMailFrom.  Any definitions in the Override option
(including Default) still take precedence.  See
L<RT_Config/$SetOutgoingMailFrom> for more information.

=head2 Reminder statuses

New reminders are now created in the "reminder_on_open" status defined in your
lifecycles.  For the default lifecycle, this means reminders will start as
"open" instead of "new".  This change is for consistency when a completed
reminder is reopened at a later date.  If you use custom lifecycles and added
further transition restrictions, you may need to adjust the L<"reminder_on_open"
setting|RT_Config/reminder_on_open> in your lifecycles.

=head2 Bookmarks

Previously, the list of Bookmarks on your homepage was unlimited (if you
had 100 bookmarked tickets, you would see a 100 item list on your RT at
a Glance).  'Bookmarked Tickets' now uses the same size limits as any
other search on your homepage.  This can be customized using the 'Rows
per box' setting on your RT at a Glance configuration page.

=head2 PostgreSQL 9.2

If you are upgrading an RT from 3.8 (or earlier) to 4.0 on PostgreSQL
9.2, you should make sure that you have installed DBD::Pg 2.19.3 or
higher.  If you start your upgrade without installing a recent-enough
version of DBD::Pg RT will stop the upgrade during the 3.9.8 step and
remind you to upgrade DBD::Pg.  If this happens, you can re-start your
upgrade by running:

   ./sbin/rt-setup-database --action insert --datadir etc/upgrade/3.9.8/

Followed by re-running make upgrade-database and answering 3.9.8 when
prompted for which RT version you're upgrading from.