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
            

Backup everything below $OTRS_HOME (default: OTRS_HOME=/opt/otrs):

Backup the database.

Make sure that you have backed up everything ;-)

Setup new system (optional)

If possible, try this install on a separate machine for testing first.

Install the new release (tar or RPM).

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

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.

Apply the database changes (part 1/2):

shell> cd /opt/otrs/

# 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;
            

Run the migration script (as user 'otrs', 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.1.pl
            

Apply the database changes (part 2/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
            

Refresh the configuration and delete caches. Please run:

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

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.

Restart your services.

e. g. (depends on used services):

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

Now you can log into your system.

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.

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.

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.

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.

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.

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.

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.

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
            

Well done!