# --
# UPGRADING - Upgrading Instructions for OTRS
# Copyright (C) 2001-2012 OTRS AG, http://otrs.org/
# --
# $Id: UPGRADING,v 1.69.2.6 2012/05/31 15:12:17 mb 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 "3.0" to "3.1",
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

Within a single minor version you can skip patch level releases if you want to
upgrade. For instance you can upgrade directly from OTRS 3.1.1 to version
3.1.4. If you need to do such a "patch level upgrade", you should skip steps
9, 11 and 13-19.

Please note that for upgrades from 3.1.beta1 or 3.1.beta2, an additional step 21
is needed!

If you are using Microsoft SQL Server as the DBMS for OTRS, please refer
to the manual, chapter "Upgrading Microsoft SQL Server Data Types" for instructions
how to upgrade the data types used by OTRS
(http://doc.otrs.org/3.1/en/html/upgrading-mssql-datatypes.html).


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=/opt/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 /opt
    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

    In this case the RPM update automatically restores the old configuration files.

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=/opt/otrs)


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

   If the tarball is used, execute:

     shell> cd /opt/otrs/
     shell> bin/otrs.SetPermissions.pl

   with the permissions needed for your system setup.


8) Apply the database changes
   --------------------------

     shell> cd /opt/otrs/


    SCHEMA UPDATE PART 1:
    =====================

    MySQL:
     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
    =========================

    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


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

    Please run:

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


10) Update your web server configuration
    ------------------------------------

    Note: this applies only if you use the Apache web server together with mod_perl2,
    and do not use the configuration file directly from the OTRS installation directory
    (e. g. with a symlink from the Apache configuration directory).

    Please add a new setting to the Apache configuration file for OTRS:

      # set mod_perl2 option for generic interface
      <Location /otrs/nph-genericinterface.pl>
          PerlOptions -ParseHeaders
      </Location>

    Please see the file /opt/otrs/scripts/apache2-httpd.include.conf for an example of
    where this new option needs to be added (inside the <IfModule mod_perl.c> block).

    In this file, you will also note a new section on caching:

    <IfModule mod_headers.c>
        <Directory "/opt/otrs/var/httpd/htdocs/skins/*/*/css-cache">
            <FilesMatch "\.(css|CSS)$">
                Header set Cache-Control "max-age=2592000 must-revalidate"
            </FilesMatch>
        </Directory>

        <Directory "/opt/otrs/var/httpd/htdocs/js/js-cache">
            <FilesMatch "\.(js|JS)$">
                Header set Cache-Control "max-age=2592000 must-revalidate"
            </FilesMatch>
        </Directory>
    </IfModule>

    Please activate this in your local installation too, and make sure that mod_headers
    is installed and active.


11) 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.


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


13) 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.


14) 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/GenericAgent.pm. Please look into
    Kernel/Config/GenericAgent.pm.dist for an example of how to do this.


15) TicketHistory
    -------------

    The TicketHistory type TicketFreeTextUpdate was renamed to
    TicketDynamicFieldUpdate. If you have any custom reporting using this,
    please adjust it.


16) 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.


17) 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.


18) 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.


19) ACL changes
    -----------

    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.

    Please also note that since OTRS 3.1.5, it is possible to match either the values of an existing ticket as
    it is on the database (new setting "PropertiesDatabase"), in addition to the existing match against the current
    values of the form. Details can be found at http://doc.otrs.org/3.1/en/html/acl.html.


20) SMIME file names
    ----------------

    This step is ONLY needed if you use SMIME to encrypt/sign your emails. You need to take this
    step if you upgrade from 3.0.x OR if you upgrade from 3.1.x before 3.1.6 while using OpenSSL 1.x
    to encrypt/sign your emails.

    Between OTRS 3.0.x and 3.1.x, the file naming of private secret file names changed and need to
    be updated. In addition, OpenSSL 0.9.x and 1.x use different algorithms to calculate the
    certificate hash. To update your private secrets and certificate file names, please run this
    command:

    shell> bin/otrs.RefreshSMIMEKeys.pl

    This step must also be taken if you change a running installation from OpenSSL 0.9 to 1.x.


21) Database Upgrade During Beta Phase
    ----------------------------------

    This step is ONLY needed if you upgrade from 3.1.beta1 or 3.1.beta2!

    Please apply the required database changes as follows:

    MySQL:
     shell> cat scripts/DBUpdate-3.1.beta.mysql.sql | mysql -p -f -u root otrs

    PostgreSQL 8.2+:
     shell> cat scripts/DBUpdate-3.1.beta.postgresql.sql | psql otrs

    PostgreSQL, older versions:
     shell> cat scripts/DBUpdate-3.1.beta.postgresql_before_8_2.sql | psql otrs


22) Well done!
    ----------
