Overview

File UPGRADING.SUSE of Package otrs

Upgrading OTRS from 4 to 5
===========================

These instructions are for people upgrading OTRS from 4 to 5 or from a 5
to a later patchlevel release 5 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 4 first
(1.1->1.2->1.3->2.0->2.1->2.2->2.3->2.4->3.0->3.1->3.2->3.3->4)! You need to perform a full
upgrade to every version in between, including database changes and the upgrading Perl script. 

Please note that if you upgrade from OTRS 2.2 or earlier, you have to take an extra step.

Within a single minor version you can skip patch level releases if you want to upgrade.
For instance you can upgrade directly from OTRS 5 patchlevel 2 to version 5 patchlevel 6.
If you need to do such a "patch level upgrade", you should skip steps 6, 11, 13 and 14. 

It is highly recommended to perform a test update on a separate testing machine first. 


1. Stop all relevant services
-----------------------------

e. g. (depends on used services):

    shell> rcotrs stop
    shell> rcotrs-scheduler stop
    shell> rcapache2 stop

2. Backup everything below @OTRS_ROOT@ (default: OTRS_ROOT=@OTRS_ROOT@)
---------------------------------------------------------------------

- Kernel/Config.pm
- Kernel/Config/GenericAgent.pm
- Kernel/Config/Files/ZZZAuto.pm
- var/*
- as well as the database


3. Make sure that you have backed up everything ;-)
---------------------------------------------------


4. Install the new release (RPM)
--------------------------------

    shell> rpm -Uvh otrs-4.0.*noarch.rpm

The RPM-update will keep the old configuration files.

- Kernel/Config.pm
- Kernel/Config/GenericAgent.pm
- Kernel/Config/Files/ZZZAuto.pm (will be overwritten by itsm)

You must use the new files *.rpmnew

- Kernel/Config.pm.rpmnew

    shell> cp -a Kernel/Config.pm Kernel/Config.pm.backup
    shell> mv Kernel/Config.pm.rpmnew Kernel/Config.pm

Then modify Kernel/Config.pm to adapt your settings (e.g. DB connection)


5. Check needed Perl modules
----------------------------

    shell> @OTRS_ROOT@/bin/otrs.CheckModules.pl


6. Apply the database changes
-----------------------------

     shell> cd @OTRS_ROOT@


### SCHEMA UPDATE

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-4.mysql.sql | mysql -p -f -u root otrs

PostgreSQL 8.2+:

    shell> cat scripts/DBUpdate-to-4.postgresql.sql | psql --set ON_ERROR_STOP=on --single-transaction otrs otrs


### DATABASE MIGRATION SCRIPT

 Run the migration script (as user `otrs`, NOT as `root`):

    shell> scripts/DBUpdate-to-5.pl

 Do not continue the upgrading process if this script did not work properly for you.
 Otherwise data loss may occur.


7. Refresh the configuration cache and delete caches
-----------------------------------------------------

Please run (as user `otrs`, NOT as `root`):

    shell> cd /srv/otrs/
    shell> bin/otrs.Console.pl Maint::Config::Rebuild
    shell> bin/otrs.Console.pl Maint::Cache::Delete


8. Restart your services
-------------------------

e. g. (depends on used services):

    shell> rcapache start
    shell> rcotrs start
    shell> rcotrs-scheduler start

Now you can log into your system.


9. Check installed packages
----------------------------

Note: The OTRS packages of 4 are NOT compatible with OTRS 5, so you have to perform a package upgrade! 

The following packages are automatically uninstalled after the upgrade process (if they where
installed before):

- OTRSGenericInterfaceMappingXSLT


10. Configure NodeIDs (only for multi-frontend clustered setups)
-----------------------------------------------------------------

Note: This step is only needed if you have a clustered setup with several frontend machines.

From OTRS 5 on, every frontend server needs to have its own unique NodeID.
This defaults to 1 and thus does not need to be configured for single-frontend
setups. If you have more than one machine, each machine needs to have this
value set to a unique value between 1 and 999. This configuration needs to be
done in the file Kernel/Config.pm:

$Self->{'NodeID'} =  '2';   # assign a unique value for every frontend server


11. Update and activate cronjobs
---------------------------------

There are two default OTRS cron files in /srv/otrs/var/cron/*.dist, and their
purpose is to make sure that the OTRS Daemon is running. They need to be
activated by copying them without the ".dist" filename extension.

    shell> cd /srv/otrs/var/cron
    shell> for foo in *.dist; do cp $foo `basename $foo .dist`; done
            

To schedule these cron jobs on your system, you can use the script Cron.sh with the otrs user.

    shell> /srv/otrs/bin/Cron.sh start
            

Please note that if you had any custom cron jobs, you should consider moving
them to SysConfig (Daemon -> Daemon::SchedulerCronTaskManager::Task) to have
them executed by the OTRS daemon as well. You might also need to adapt your
custom scripts, because now most OTRS commands are managed by
bin/otrs.Console.pl instead of single scripts.

Note: The console command Dev::Code::Generate::ConsoleCommand can help to
create new console commands for your custom scripts. This command creates a
template where the script logic and its parameters can be adapted.


12: Review your ticket notifications
-------------------------------------

With OTRS 5 ticket notifications are configured differently than in previous
versions. They are now part of the "Event Notifications" that were previously
available as well (now called just "Ticket Notifications"). Your existing
ticket notifications have been migrated into the list of ticket notifications,
but deactivated. You have also received the new default ticket notifications,
active by default.

In case you did not modify the old ticket notifications you don't have to do
anything. If you have made local modifications or translations, you have two
choices: a) you can migrate your modifications to the new ticket notifications
(recommended) or b) you can deactivate the new notifications and activate the
old notifications again.

Please also review the escalation notification recipient settings and see if
they match with your expectations (agents who have the ticket in one of their
custom queues vs. all agents with read permissions). This was configured via a
setting in the file Kernel/Config/GenericAgent.pm (now obsolete) previously and
can now be controlled via the GUI for each notification separately.


13: Update system registration (optional)
------------------------------------------

If the system is already registered with OTRS Group, it is strongly recommended
to update the registration information at this time. This will update the
registered version of the system (among other changes) in the OTRS Group
records, in order to get much accurate information from the cloud services.

If you don't update the registration information manually, it will be done
automatically on a regular basis, but this could happen some hours or days
after. During this period it might be possible to get wrong information from
cloud services like OTRS Business Solution™ updates.

    shell> cd /srv/otrs/
    shell> bin/otrs.Console.pl Maint::Registration::UpdateSend --force
    shell> bin/otrs.Console.pl Maint::Cache::Delete
            

14: Migrate custom Perl based GenericAgent jobs (optional)
-----------------------------------------------------------

This is only relevant if you had any custom GenericAgent jobs in Perl OTRS 4
configuration files such as Kernel/Config/GenericAgent.pm that cannot be handled
with the regular ticket notifications. Such jobs now need to be registered as
OTRS Daemon cron tasks in the SysConfig
    (Daemon -> Daemon::SchedulerCronTaskManager::Task),
in order to be executed on a regular basis.

There are 5 settings in the SysConfig prepared for this purpose
 (Daemon::SchedulerCronTaskManager::Task###GenericAgentFile1 to
 Daemon::SchedulerCronTaskManager::Task###GenericAgentFile5).
If more settings are needed they can be added in a custom SysConfig setting file.

Please replace "<ModuleName>" with the file that contains the custom
GenericAgent jobs configuration, e.g. Kernel::Config::GenericAgent for the file:
Kernel/Config/GenericAgent.pm, set the schedule to match the periodicity as it
was executed before, mark the setting as active and save the changes.
Note

To get more information about other parameters that can be used while running
the GenericAgent jobs, please execute:

    shell> bin/otrs.Console.pl Maint::GenericAgent::Run --help
            

15: Setup bash autocompletion (optional)
-----------------------------------------

All regular OTRS command line operations now happen via the OTRS Console
interface bin/otrs.Console.pl. This provides an auto completion for the bash
shell which makes finding the right command and options much easier.

You can activate the bash autocompletion by installing the package bash-completion.
It will automatically detect and load the file /srv/otrs/.bash_completion for the otrs user.

After restarting your shell, you can just type bin/otrs.Console.pl followed by TAB,
and it will list all available commands. If you type a few characters of the
command name, TAB will show all matching commands. After typing a complete command,
all possible options and arguments will be shown by pressing TAB.
Step 18: Review ticket action screen configurations (optional)

Some ticket action screens like "Note" had default subjects in OTRS 4
(configurable via SysConfig, Ticket::Frontend::AgentTicketNote###Subject in this case).
These default subjects have been removed to reduce the amount of potentially
redundant/meaningless data. You might want to re-add them if they are mandatory for you.


16: Review Ticket Event Module Configurations
----------------------------------------------

Because of a bugfix in OTRS 5s, configuration names for a few ticket event modules had
to be changed. Any possible customizations need to be re-applied. Please review your
settings in SysConfig -> Ticket -> Core::Ticket and check all settings that start with
Ticket::EventModulePost to see if your custiomizations have to be re-applied. This could
be the case if you had activated and configured the event handler to save customer data
in ticket dynamic fields, for example. 


17: Well done!
--------------
openSUSE Build Service is sponsored by
Places