3.3. Upgrading the OTRS Framework
From open-support.info
These instructions are for people upgrading OTRS from version 2.4 to 3.0, and apply 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 ...).
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=/opt/otrs):
- Kernel/Config.pm
- Kernel/Config/GenericAgent.pm
- Kernel/Config/Files/ZZZAuto.pm
- var/*
- as well as the database
3. Backup the database.
4. 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 config files.
- Kernel/Config.pm
- Kernel/Config/GenericAgent.pm
- Kernel/Config/Files/ZZZAuto.pm
- With the RPM:
shell> rpm -Uvh otrs-x.x.x.-01.rpm
-
Restore old config files not needed, done by RPM.
6. Own themes
Note: The OTRS themes between 2.4 and 3.0 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.
shell> cd /opt/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
</li>
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
</li>
# 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
</li>
shell> bin/otrs.RebuildConfig.pl shell> bin/otrs.DeleteCache.pl
</li>
e. g. (depends on used services):
shell> /etc/init.d/cron start shell> /etc/init.d/postfix start shell> /etc/init.d/apache start
</li>
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 did not 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';
In general, using "utf-8" is the recommended mode of running OTRS, and switching from "iso-8859-1" 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.
</li>
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.
</li>
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. </li>
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
</li>
