File UPGRADING.SuSE of Package otrs
# --
# UPGRADING - Upgrading Instructions for OTRS
# Copyright (C) 2001-2012 OTRS AG, http://otrs.org/
# --
# $Id: UPGRADING,v 1.66 2012/02/07 14:10:57 mg Exp $
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see
# the enclosed file COPYING for license information (AGPL). If you
# did not receive this file, see http://www.gnu.org/licenses/agpl.txt.
# --
These instructions are for people upgrading OTRS "3.1" to "3.2",
and applies both for RPM and source code (tarball) upgrades.
If you are running a lower version of OTRS you have to follow the upgrade path
to 3.0 first (1.1->1.2->1.3->2.0->2.1->2.2->2.3->2.4->3.0->3.1 ...)!
Please note that if you upgrade from OTRS 2.2 or earlier, you have to
take an extra step; please read http://bugs.otrs.org/show_bug.cgi?id=6798
If you need to do a "patch level upgrade", which is an upgrade for instance
from OTRS version 3.2.1 to 3.2.3, you should skip steps 7, 8, 10 and 12-19.
1) Stop all relevant services
--------------------------
e. g. (depends on used services):
shell> rccron stop
shell> rcpostfix stop
shell> rcapache2 stop
shell> rcotrs stop
2) Backup everything below $OTRS_HOME (default: OTRS_HOME=/srv/otrs)
-----------------------------------------------------------------
o Kernel/Config.pm
o Kernel/Config/GenericAgent.pm
o Kernel/Config/Files/ZZZAuto.pm
o var/*
o as well as the database
3) Make sure that you have backed up everything ;-)
------------------------------------------------
4) Setup new system (optional)
---------------------------
If possible try this install on a separate machine for testing first.
5) Install the new release (RPM)
------------------------------------
shell> rpm -Uvh otrs-3.1.x-?.noarch.rpm
The RPM-update will keep the old configuration files.
o Kernel/Config.pm
o Kernel/Config/GenericAgent.pm
o Kernel/Config/Files/ZZZAuto.pm (will be overwritten by itsm)
You must use the new files *.rpmnew
o Kernel/Config.pm.rpmnew
cp -a Kernel/Config.pm Kernel/Config.pm.backup
mv Kernel/Config.pm.rpmnew Kernel/Config.pm
then modify Kernel/Config.pm to adapt settings (e.g. DB connection)
6) Own themes
----------
Note: The OTRS themes between 3.0 and 3.1 are NOT compatible, so don't
use your old themes!
Themes are located under $OTRS_HOME/Kernel/Output/HTML/*/*.dtl
(default: OTRS_HOME=/srv/otrs)
7) Apply the database changes
--------------------------
shell> cd $OTRS_HOME
SCHEMA UPDATE PART 1:
=====================
MySQL:
Note: new tables created in the MySQL UPGRADING process will be created with the
default table storage engine set in your MySQL server.
In MySQL 5.5 the new default type is InnoDB.
If existing tables, e.g. "users", have the table storage engine e.g. MyISAM,
then an error will be displayed when creating the foreign key constraints.
You have two options: you can change the default storage engine of MySQL back to MyISAM
so that new tables will have the same engine as the existing tables,
or change the existing tables to use InnoDB as storage engine.
Any problems with regards to the storage engine will be reported by the
`otrs.CheckDB.pl` script, so please run it to check for possible issues.
shell> bin/otrs.CheckDB.pl
shell> cat scripts/DBUpdate-to-3.1.mysql.sql | mysql -p -f -u root otrs
PostgreSQL 8.2+:
shell> cat scripts/DBUpdate-to-3.1.postgresql.sql | psql otrs
PostgreSQL, older versions:
shell> cat scripts/DBUpdate-to-3.1.postgresql_before_8_2.sql | psql otrs
NOTE: If you use PostgreSQL 8.1 or earlier, you need to activate the new
legacy driver for these older versions. Do this by adding a new
line to your Kernel/Config.pm like this:
$Self->{DatabasePostgresqlBefore82} = 1;
DATABASE MIGRATION SCRIPT
=========================
Run the migration script (as user `otrs`, NOT as `root`):
shell> scripts/DBUpdate-to-3.1.pl
Do not continue the upgrading process if this script did not work properly
for you. Otherwise data loss may occur.
SCHEMA UPDATE PART 2:
=====================
MySQL:
shell> cat scripts/DBUpdate-to-3.1-post.mysql.sql | mysql -p -f -u root otrs
PostgreSQL 8.2+:
shell> cat scripts/DBUpdate-to-3.1-post.postgresql.sql | psql otrs
PostgreSQL, older versions:
shell> cat scripts/DBUpdate-to-3.1-post.postgresql_before_8_2.sql | psql otrs
8) Refresh the configuration cache and delete caches
-------------------------------------------------
Please run:
shell> bin/otrs.RebuildConfig.pl
shell> bin/otrs.DeleteCache.pl
9) Restart your services
---------------------
e. g. (depends on used services):
shell> /etc/init.d/apache start
shell> /etc/init.d/postfix start
shell> /etc/init.d/cron start
shell> /etc/init.d/otrs-scheduler start
shell> /etc/init.d/otrs start
Now you can log into your system.
10) Check installed packages
------------------------
In the package manager, check if all packages are still marked as
correctly installed or if any require reinstallation or even a package upgrade.
11) Check for encoding issues
-------------------------
OTRS 3.1 only allows UTF-8 as internal charset.
Non-UTF-8 installations of OTRS must switch to UTF-8.
12) Escalation events
-----------------
If you want to use the new escalation events in your system, you need to
activate the corresponding GenericAgent job in
Kernel/Config/GenericAcent.pm.
Please look into Kernel/Config/GenericAgent.pm.dist
for an example of how to do this.
13) TicketHistory
-------------
The TicketHistory type TicketFreeTextUpdate was renamed to
TicketDynamicFieldUpdate. If you have any custom reporting using this,
please adjust it.
14) Ticket event handlers
---------------------
The Event name TicketFreeTextUpdate_$Counter was renamed to
TicketDynamicFieldUpdate_$FieldName.
If you have any custom event handlers for these events, please adapt them.
15) DynamicField user preferences module
------------------------------------
If you had one or more active custom settings for "PreferencesGroups###Freetext",
you need to adapt them to work with the new DynamicFields engine. The PrefKey
setting must be changed to "UserDynamicField_DynamicField", where the part after
the _ is the name of the dynamic field. Existing values would need to be renamed
in the database as well.
16) Custom free field default value event handler
---------------------------------------------
If you used the event handler Ticket::EventModulePost###TicketFreeFieldDefault
(not active by default), you'll need to migrate its configuration to the new
setting Ticket::EventModulePost###TicketDynamicFieldDefault.
The configuration of this is slightly different; where you had to specify a
Counter indicating the TicketFreeText number previously, now you need to
specify the name of the DynamicField (for migrated fields, this will be
DynamicField_TicketFreeKey$Counter and DynamicField_TicketFreeText$Counter.
You need two separate entries now if you want to set both the key and the
text field.
17) FreeText/Time based ACLs
------------------------
If you have any ACLs defined which involve freetext or freetime fields,
you need to adjust these ACL definitions.
Please have a look at http://doc.otrs.org/3.1/en/html/acl.html. There you
can find a list of all possible ACL settings. In general, you need to add
the prefix "DynamicField_" to existing free field definitions, and you can
add a new "DynamicField" section to the "Properties" list for situations
when a ticket does not exist yet.
18) Well done!
----------
