# --
# UPGRADING - upgrading OTRS
# Copyright (C) 2001-2011 OTRS AG, http://otrs.org/
# --
# $Id: UPGRADING,v 1.49.2.3 2011/04/20 14:18:21 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 from "2.4" to "3.0",
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 2.4 first (1.1->1.2->1.3->2.0->2.1->2.2->2.3->2.4->3.0 ...)!

Please note that if you upgrade from OTRS 2.2 or earlier, you have to
take an extra step; 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.0.3 to 3.0.4, you should skip steps 8, 9, 10, and 13 - 16.


1) Stop all relevant services
   --------------------------

    e. g. (depends on used services):

    shell> /etc/init.d/cron stop
    shell> /etc/init.d/postfix stop
    shell> /etc/init.d/apache stop


2) Backup everything below $OTRS_HOME (default: OTRS_HOME=/var/www/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 (tar or RPM)
   ------------------------------------

   With the tarball:

    shell> cd /var/www
    shell> tar -xzf otrs-x.x.x.tar.gz
    shell> ln -s otrs-x.x.x otrs

    Restore old configuration files.
    o Kernel/Config.pm
    o Kernel/Config/GenericAgent.pm
    o Kernel/Config/Files/ZZZAuto.pm


   With the RPM:

    shell> rpm -Uvh otrs-x.x.x.-01.rpm

    Restore old configuration files is not needed, done by RPM.

6) Own themes
   ----------

   The OTRS themes from 2.4 and 3.0 are _not_ compatible (don't use the old themes)!

   Themes are located under $OTRS_HOME/Kernel/Output/HTML/*/*.dtl (default: OTRS_HOME=/var/www/otrs)


7) Set file permissions
   --------------------

   If the tarball is used, execute:

     shell> cd /var/www/otrs/
     shell> bin/otrs.SetPermissions.pl

   with the permissions needed for your system setup.


8) Apply the database changes (part 1/2):
   --------------------------------------

     shell> cd /var/www/otrs/

    MySQL:
     shell> cat scripts/DBUpdate-to-3.0.mysql.sql | mysql -p -f -u root otrs
    PostgreSQL:
     shell> cat scripts/DBUpdate-to-3.0.postgresql.sql | psql otrs


9) Run the migration script (as OTRS user, _not_ as root):
   -------------------------------------------------------

   You must execute the migration script to migrate some data from the old database
   structure to the new one. Please run

     shell> scripts/DBUpdate-to-3.0.pl


10) Apply the database changes (part 2/2):
    --------------------------------------

    MySQL:
     shell> cat scripts/DBUpdate-to-3.0-post.mysql.sql | mysql -p -f -u root otrs
    PostgreSQL:
     shell> cat scripts/DBUpdate-to-3.0-post.postgresql.sql | psql otrs


11) Refresh the configuration cache and delete caches
    -------------------------------------------------

    Please run:

    shell> bin/otrs.RebuildConfig.pl
    shell> bin/otrs.DeleteCache.pl


12) 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

    Now you can log into your system.


13) Check for encoding issues
    -------------------------

    With OTRS 3.0, the default charset of OTRS was changed from "iso-8859-1" to "utf-8".

    This will only affect you if you didn't specify a charset in Kernel/Config.pm (all
    installations that were made with the web installer have a custom setting there) or
    if you didn't change the default charset in the AdminSysConfig.

    If you experience problems with the new charset, add this line to Kernel/Config.pm:

    $Self->{'DefaultCharset'} = 'iso-8859-1'; # use your previous charset setting here

    In General, using "utf-8" is the recommended mode of running OTRS, and switching from
    other charsets should work well.

    Please note: We recommend to change existing non-UTF-8 installations of OTRS to UTF-8
    with the upgrade to 3.0. All other encodings are now deprecated.

    OTRS 3.1 will only allow UTF-8 as internal charset.


14) Check for Custom Frontend Module Registrations
    ----------------------------------------------

    Starting with OTRS 3.0, application modules may have their own special CSS and/or
    JavaScript. This is part of the so-called frontend module registration of the
    modules in the SysConfig. This may cause problems during the upgrade, because
    locally modified frontend module configuration settings will not catch the updates
    of the new default configuration.

    To check if you are affected, please look at the file Kernel/Config/Files/ZZZAuto.pm
    and look for entries like

    $Self->{'Frontend::Module'}->{'AgentStats'} = { ... };

    These settings should be reset to their default value in Admin -> SysConfig
    (in this case: 'Frontend::Module###AgentStats') with the little "Reset" button
    next to the "Active" checkbox. Then the settings will be reset with the new
    module-specific settings and no longer show up in
    Kernel/Config/Files/ZZZAuto.pm. After this procedure, you may customize these
    settings again, if needed.

    The same procedure must be executed for the setting
    "Frontend::ToolBarModule###1-Ticket::TicketSearchFulltext", as this now also uses
    module specific CSS. If this setting is not activated on your system, you can
    safely omit this step.

15) Check for customized PreferencesGroups entries
    ----------------------------------------------

    With OTRS 3.0, there were a few corrections in PreferencesGroups configuration entries.
    Notably, the keys 'Activ' and 'Colum' were changed to 'Active' and 'Column', respectively.
    You only need to take action if you have customized such settings on your system, otherwise
    they will be updated automatically.

    To check if you are affected, please look at the file Kernel/Config/Files/ZZZAuto.pm
    and look for entries like:

    $Self->{'CustomerPreferencesGroups'}->{'RefreshTime'} =  {
      'Activ' => '0',
      'Colum' => 'Frontend',
      'Data' => {
        '' => 'off',
        '10' => '10 minutes',
        '15' => '15 minutes',
        '2' => ' 2 minutes',
        '5' => ' 5 minutes',
        '7' => ' 7 minutes'
      },
      'Desc' => 'Select your QueueView refresh time.',
      'Label' => 'QueueView refresh time',
      'Module' => 'Kernel::Output::HTML::PreferencesGeneric',
      'PrefKey' => 'UserRefreshTime',
      'Prio' => '4000'
    };

    This needs to be changed as follows:

    $Self->{'CustomerPreferencesGroups'}->{'RefreshTime'} =  {
      'Active' => '0',
      'Column' => 'Frontend',
      'Data' => {
        '' => 'off',
        '10' => '10 minutes',
        '15' => '15 minutes',
        '2' => ' 2 minutes',
        '5' => ' 5 minutes',
        '7' => ' 7 minutes'
      },
      'Desc' => 'Select your QueueView refresh time.',
      'Label' => 'QueueView refresh time',
      'Module' => 'Kernel::Output::HTML::PreferencesGeneric',
      'PrefKey' => 'UserRefreshTime',
      'Prio' => '4000'
    };

16) Customer Database Backend Field Renaming
    ----------------------------------------

    The field 'salutation' in the built-in customer database has been renamed to
    the more appropriate 'title'. If you are using the built-in database data
    source for customers, and you have changed the configuration, for instance
    because you've added fields to the customer table, or because you've enabled
    Customer Company support, you should change the mapping in your Kernel/Config.pm:

    Change this line:

     [ 'UserSalutation', 'Salutation', 'salutation', 1, 0, 'var', '', 0 ],

    to:

     [ 'UserTitle',      'Title',      'title',      1, 0, 'var', '', 0 ],

    Please note that this can also affect any salutations or other templates
    where you've used the string <OTRS_*_UserSalutation>. If you have used this
    string AND you use the built-in customer table, please replace it with
    <OTRS_CURRENT_UserTitle> instead.

17) Optional: Mark Tickets as Read
    ------------------------------

    In OTRS 3.0 there is a new feature: new tickets and new articles which an Agent
    did not read yet are highlighted as 'unread'. For all tickets which were created
    before the upgrade to OTRS 3.0, the 'read' information is missing, and therefore
    these tickets will be marked as 'unread'. If this bothers you, you can use a script
    to set all tickets and articles as read for all agents which have read permissions
    for these tickets. Note that this script may run for a while!

    shell> bin/otrs.MarkTicketAsSeen.pl


18) Well done!
    ----------