Upgrading OTRS 5 to OTRS 6 on Debian


We are assuming you have a working OTRS 5 install, upgraded to the latest version of 5. At the time of writing, this is version 5.0.25.

Warning

Before upgrading, take a backup of the database, the install and if possible, a snapshot can be very useful in quickly returning to a previous version. Also, it's highly recommended to do this on a test server first.

Note

As what the official info says on upgrading from version 5: You can update from any OTRS 5 patch level to the latest available OTRS 6 patch level release.


1. Get the new version

Download the latest version and unpack it:

$ wget https://ftp.otrs.org/pub/otrs/otrs-6.0.2.tar.gz
$ tar xzvf otrs-6.0.2.tar.gz

2. Stop the services

Stop all related services:

    invoke-rc.d cron stop
    invoke-rc.d nginx stop
    invoke-rc.d postfix stop

or

    systemctl stop cron
    systemctl stop nginx
    systemctl stop postfix

Stop OTRS cron jobs and the daemon (in this order):

/opt/otrs/bin/Cron.sh stop otrs
su -c "/opt/otrs/bin/otrs.Daemon.pl stop" -s /bin/bash otrs

Stop the program. On this install we use supervisorctl to keep the OTRS processes active and running.:

supervisorctl stop all

Check the processes so no OTRS related processes remain active:

ps aux

3. Create otrs-prev

Create a symlink to the new "old" version:

rm otrs-prev
ln -s otrs-5.0.25 otrs-prev

Create a symlink to the new version:

rm /opt/otrs
ln -s otrs-6.0.2 otrs

4. Restore old config

Copy the old config to opt (optional):

cp /opt/otrs-prev/Kernel/Config.pm /opt/otrs/Kernel
cp /opt/otrs-prev/Kernel/Config/Files/ZZZAuto.pm /opt/otrs/Kernel/Config/Files/

Restore articles:

cp -R /opt/otrs-prev/var/article/* /opt/otrs/var/article

Restore ticketcounter:

cp -R /opt/otrs-prev/var/log/TicketCounter.log /opt/otrs/var/log

I have some scripts to reload the instance and so on, so I need to copy these as well. If you don't, skip this step.

cp -R /opt/otrs-prev/links /opt/otrs/links
cp -R /opt/otrs-prev/myscripts /opt/otrs/myscripts
cp -R /opt/otrs-prev/*.sh /opt/otrs/

You should check the scripts and see if they still work.

Check the cron daemon file:

cp /opt/otrs/var/cron/otrs_daemon.dist /opt/otrs/var/cron/otrs_daemon

Restore skins. Since this is a major version change, rebuilding them from scratch based on the standard files would be a good idea. If you don't want to do this, copy the old skins over and see if they work.:

mv /opt/otrs/var/httpd/htdocs/skins/Agent/default /opt/otrs/var/httpd/htdocs/skins/Agent/default_new
cp -R /opt/otrs-prev/var/httpd/htdocs/skins/Agent/default /opt/otrs/var/httpd/htdocs/skins/Agent
cp -R /opt/otrs-prev/var/httpd/htdocs/skins/Agent/myagent /opt/otrs/var/httpd/htdocs/skins/Agent

mv /opt/otrs/var/httpd/htdocs/skins/Customer/default /opt/otrs/var/httpd/htdocs/skins/Customer/default_new
cp -R /opt/otrs-prev/var/httpd/htdocs/skins/Customer/default /opt/otrs/var/httpd/htdocs/skins/Customer
cp -R /opt/otrs-prev/var/httpd/htdocs/skins/Customer/mycustomer /opt/otrs/var/httpd/htdocs/skins/Customer

To load the skins, we have 2 files. But the XML configuration file format changed. Files need to be migrated. From the manual.

Note

OTRS 6 uses a new XML configuration file format and the location of configuration files moved from Kernel/Config/Files to Kernel/Config/Files/XML. To convert existing XML configuration files to the new format and location, you can use the following tool that is part of the OTRS framework.

New version of OTRS needs a new perl library, which you might have to install before running the migrate command:

apt policy libdatetime-perl
apt install libdatetime-perl

Migrate the XML files:

su -c "/opt/otrs/bin/otrs.Console.pl Dev::Tools::Migrate::ConfigXMLStructure --source-directory Kernel/Config/Files" -s /bin/bash otrs

If the xml files are succesfuly migrated, you can delete the original files but check if the new ones exists before doing so.

For restoring the theme/HTML customizations, the same is true as for the skins. If you want to try your theme out if you have one:

cp -R /opt/otrs-prev/Kernel/Output/HTML/Templates/my_theme /opt/otrs/Kernel/Output/HTML/Templates/

Create var/run folder:

mkdir /opt/otrs/var/run
chown -R otrs:www-data /opt/otrs/var/run
chmod -R g+w /opt/otrs/var/run

Set permissions on the files:

/opt/otrs/bin/otrs.SetPermissions.pl --web-group=www-data

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

su -c "/opt/otrs/scripts/DBUpdate-to-6.pl" -s /bin/bash otrs
Migration started ...

Checking requirements ...

   Requirement check for: Check framework version ...
   Requirement check for: Check required Perl version ...
   Requirement check for: Check required database version ...
   Requirement check for: Check database charset ...
   Requirement check for: Check required Perl modules ...
   Requirement check for: Check if database has been backed up ...

       Did you backup the database? [Y]es/[N]o: y

   Requirement check for: Upgrade database structure ...
   Requirement check for: Migrating time zone configuration ...


       The currently configured time offset is 1 hours, these are the suggestions for a corresponding OTRS time zone:

       Africa/Algiers
       Africa/Ceuta
       Africa/Lagos
       Africa/Ndjamena
       Africa/Tunis
       CET
       Europe/Amsterdam
       Europe/Andorra
       Europe/Belgrade
       Europe/Berlin
       Europe/Brussels
       Europe/Budapest
       Europe/Copenhagen
       Europe/Gibraltar
       Europe/Luxembourg
       Europe/Madrid
       Europe/Malta
       Europe/Monaco
       Europe/Oslo
       Europe/Paris
       Europe/Prague
       Europe/Rome
       Europe/Stockholm
       Europe/Tirane
       Europe/Vienna
       Europe/Warsaw
       Europe/Zurich
       MET


       It seems that Europe/Brussels should be the correct time zone to set for your OTRS.

       Enter the time zone to use for OTRSTimeZone (leave empty to show a list of all available time zones): Europe/Brussels

       Enter the time zone to use for UserDefaultTimeZone (leave empty to show a list of all available time zones): Europe/Brussels

   Requirement check for: Update calendar appointment future tasks ...
   Requirement check for: Migrate GenericAgent jobs configuration ...
   Requirement check for: Migrate TicketAppointment rules configuration ...
   Requirement check for: Create entries in new article table ...
   Requirement check for: Migrate ArticleType in ProcessManagement Data ...
   Requirement check for: Migrate ArticleType in PostMaster filters ...

Executing tasks ...

   Step 1 of 37: Check framework version ...
   Step 2 of 37: Check required Perl version ...
   Step 3 of 37: Check required database version ...
   Step 4 of 37: Check database charset ...
   Step 5 of 37: Check required Perl modules ...
   Step 6 of 37: Check if database has been backed up ...
   Step 7 of 37: Upgrade database structure ...
   Step 8 of 37: Migrate configuration ...
   Step 9 of 37: Refresh configuration cache after migration of OTRS 5 settings ...
   Step 10 of 37: Migrating ticket storage configuration ...
   Step 11 of 37: Migrating article search index configuration ...
   Step 12 of 37: Migrating ticket zoom customer information widget configuration ...
   Step 13 of 37: Drop deprecated table gi_object_lock_state ...
   Step 14 of 37: Migrate PossibleNextActions setting ...
   Step 15 of 37: Migrating time zone configuration ...
   Step 16 of 37: Create appointment calendar tables ...
   Step 17 of 37: Create ticket number counter tables ...
   Step 18 of 37: Update calendar appointment future tasks ...
   Step 19 of 37: Add basic appointment notification for reminders ...
   Step 20 of 37: Create Form Draft tables ...
   Step 21 of 37: Clean and drop group_user permission_value column ...
   Step 22 of 37: Migrate GenericAgent jobs configuration ...
   Step 23 of 37: Migrate TicketAppointment rules configuration ...
   Step 24 of 37: Migrate Merged Ticket history name values ...
   Step 25 of 37: Migrate ticket statistics ...
   Step 26 of 37: Migrate ticket notifications ...
   Step 27 of 37: Create entries in new article table ...
   Step 28 of 37: Post changes on article related tables ...
   Step 29 of 37: Migrate ArticleType in ProcessManagement Data ...
   Step 30 of 37: Migrate ArticleType in PostMaster filters ...
   Step 31 of 37: Migrate chat articles ...
   Step 32 of 37: Initialize default cron jobs ...
   Copying /opt/otrs/var/cron/aaa_base.dist to /opt/otrs/var/cron/aaa_base...
   done.
   Step 33 of 37: Migrate web service configuration ...
   Step 34 of 37: Uninstall Merged Feature Add-Ons ...
   Step 35 of 37: Clean up the cache ...
   Step 36 of 37: Refresh configuration cache another time ...
   Step 37 of 37: Check SysConfig consistency ...



Migration completed!

Refresh the configuration cache and delete caches:

su -c "/opt/otrs/bin/otrs.Console.pl Maint::Cache::Delete" -s /bin/bash otrs
su -c "/opt/otrs/bin/otrs.Console.pl Maint::Config::Rebuild" -s /bin/bash otrs

Next restart the service index.pl, custom.pl and public.pl. Restart the services:

    invoke-rc.d cron start
    invoke-rc.d nginx start
    invoke-rc.d postfix start

or

    systemctl start cron
    systemctl start nginx
    systemctl start postfix

    su -c "/opt/otrs/bin/otrs.Daemon.pl start"  -s /bin/bash otrs

    supervisorctl start all

Start the OTRS cron:

cd cron
/opt/otrs/bin/Cron.sh start otrs

Log in to the app, and check the installed packages, and upgrade them if necessary. Go to the website and download the packages. Install them via the normal webinterface:

https://portal.otrs.com/otrs/public.pl?Action=PublicDownloads#

It's also possible to update the packages from the command line. See this link Official OTRS 6 update document

5. Rework templates

You could copy the old template and use it, but since the template files might change between major versions, it's better to copy those files first and do your changes again on these files.

Create an new directory in the Template folder. Copy the files from the Standard template to this directory and change the files appropriately. For my template, these were the files I had to change again.:

cd /opt/otrs/Kernel/Output/HTML/Templates
mkdir new_template

-rw-r----- 1 root www-data  2039 dec 17 09:21 AgentNavigationBar.tt
-rw-r----- 1 root www-data 27339 dec 17 09:22 AgentTicketActionCommon.tt
-rw-r----- 1 root www-data   325 dec 17 09:21 AgentTicketNote.tt
-rw-r----- 1 root www-data 31654 dec 17 09:21 AgentTicketOverviewSmall.tt
-rw-r----- 1 root www-data  3678 dec 17 09:22 CustomerFooterJS.tt
-rw-r----- 1 root www-data  9267 dec 17 09:22 CustomerLogin.tt
-rw-r----- 1 root www-data 14188 dec 17 09:22 CustomerTicketZoom.tt
-rw-r----- 1 root www-data  3655 dec 17 09:23 FooterJS.tt
-rw-r----- 1 root www-data  1101 dec 17 09:23 Footer.tt
-rw-r----- 1 root www-data 13262 dec 17 09:23 Login.tt
drwxr-sr-x 3 root www-data  4096 dec 17 09:21 NotificationEvent

-rw-r----- 1 root www-data 7838 dec 17 09:21 NotificationEvent/Email/Default.tt

6. Skins

To handle skins in the new version, the same could be said as for the templates. First copy the files from the standard skin and adjust them to your liking:

mkdir -p /opt/otrs/var/httpd/htdocs/skins/Agent/my_skin/css

The content of my skin directory:

-rw-r----- 1 otrs www-data  2143 dec 17 16:50 Core.Agent.Admin.css
-rw-r----- 1 otrs www-data 15892 dec 17 16:50 Core.Agent.Admin.ProcessManagement.css
-rw-r----- 1 otrs www-data  2554 dec 17 16:50 Core.Agent.Dashboard.css
-rw-r----- 1 otrs www-data   167 dec 17 16:50 Core.Control.css
-rw-r----- 1 otrs www-data  3505 dec 17 16:50 Core.Default.css
-rw-r----- 1 otrs www-data 15390 dec 17 16:50 Core.Form.css
-rw-r----- 1 otrs www-data  5681 dec 17 16:50 Core.Header.css
-rw-r----- 1 otrs www-data  8134 dec 17 16:50 Core.OverviewLarge.css
-rw-r----- 1 otrs www-data  6333 dec 17 16:50 Core.Print.css
-rw-r----- 1 otrs www-data 32160 dec 17 16:50 Core.Responsive.css
-rw-r----- 1 otrs www-data 18377 dec 17 16:50 Core.Table.css
-rw-r----- 1 otrs www-data 20034 dec 17 16:50 Core.TicketDetail.css
-rw-r----- 1 otrs www-data 15975 dec 17 16:50 Core.Widget.css
-rw-r----- 1 otrs www-data  8653 dec 17 16:50 Core.WidgetMenu.css
-rw-r----- 1 otrs www-data   600 dec 17 16:50 Custom.css

7. Errors

7.1. Dynamic fields

When trying to rebuild the cache, I got an error:

Deleting cache...
Done.
Rebuilding the system configuration...
ERROR: OTRS-otrs.Console.pl-Maint::Config::Rebuild-91 Perl: 5.24.1 OS: linux Time: Wed Dec 17 14:07:21 2017

 Message: Setting Ticket::Frontend::AgentTicketEmail###DynamicField Effective value is not correct: 'Content' option not found in Select!

 Traceback (5890):
   Module: Kernel::System::SysConfig::ConfigurationDeploy Line: 3417
   Module: Kernel::System::Console::Command::Maint::Config::Rebuild::Run Line: 69
   Module: (eval) Line: 460
   Module: Kernel::System::Console::BaseCommand::Execute Line: 454
   Module: Kernel::System::Console::InterfaceConsole::Run Line: 80
   Module: /opt/otrs/bin/otrs.Console.pl Line: 38

Error: There was a problem writing ZZZAAuto.pm

We will first try to get rid of the error to get a working OTRS 6. I had a number of Dynamic field entries in my Config.pm/ Check Config.pm and comment out the dynamic field lines:

...
#### Dynamicfields ####
### Invoice ###
$Self->{'Ticket::Frontend::AgentTicketEmail'}->{'DynamicField'} =  {
    'Key' => 'Content',
    'Invoice' => '1',
};

7.2. Queues

After these changes, rebuilding the cache still got an error:

-rwxrwxrwx 1 otrs www-data 295069 dec 17 09:32 ZZZAAuto.pm
...
Rebuilding the system configuration...
ERROR: OTRS-otrs.Console.pl-Maint::Config::Rebuild-10 Perl: 5.24.1 OS: linux Time: Thu Dec 17 09:33:44 2017

 Message: Setting PostmasterDefaultQueue Effective value is not correct: Entity value is invalid(Raw)!

 Traceback (27752):
   Module: Kernel::System::SysConfig::ConfigurationDeploy Line: 3417
   Module: Kernel::System::Console::Command::Maint::Config::Rebuild::Run Line: 69
   Module: (eval) Line: 460
   Module: Kernel::System::Console::BaseCommand::Execute Line: 454
   Module: Kernel::System::Console::InterfaceConsole::Run Line: 80
   Module: /opt/otrs/bin/otrs.Console.pl Line: 38

Error: There was a problem writing ZZZAAuto.pm.

There appear to be 2 invalid settings:

PostmasterDefaultQueue = Raw
Process::DefaultQueue = Raw

$ grep "PostmasterDefaultQueue" Kernel/Config/Files/ZZZAuto.pm
$Self->{'PostmasterDefaultQueue'} =  'Raw';

I solved this by editing Ticket.xml and ProcessManagement.xml. Change the PostmasterDefaultQueue item value from "Raw" to a correct queue type. In this example 1 of the valid queue's is "Niet toegewezen".:

cd /opt/otrs/Kernel/Config/Files/XML/
vi Ticket.xml

...
<Setting Name="PostmasterDefaultQueue" Required="1" Valid="1">
        <Description Translatable="1">Defines the postmaster default queue.</Description>
        <Navigation>Core::Email::PostMaster</Navigation>
        <Value>
                <Item ValueType="Entity" ValueEntityType="Queue" ValueRegex="">Niet toegewezen</Item>
        </Value>
</Setting>

We do the same for DefaultQueue:

vi ProcessManagement.xml
...
<Setting Name="Process::DefaultQueue" Required="1" Valid="1">
        <Description Translatable="1">This option defines the process tickets default queue.</Des
        <Navigation>Core::ProcessManagement</Navigation>
        <Value>
                <Item ValueType="Entity" ValueEntityType="Queue" ValueRegex="">Niet toegewezen</Item>
        </Value>
</Setting>

7.3. Login button

Afterwards, the login button didn't seem to work. Seems like a Javascript problem so we start looking in that direction. Using the dev mode of the browser, it appeared not all javascripts where loaded. This was also because of some custom settings in Config.pm. After commenting these sections, logging in worked again.

7.4. Config.pm

There was some difference between the v5 and v6 Config.pm. I added these lines at the bottom that were also present in the v6 standard Config.pm:

...

# ---------------------------------------------------- #
# needed system stuff (don't edit this)                #
# ---------------------------------------------------- #

use Kernel::Config::Defaults; # import Translatable()
use parent qw(Kernel::Config::Defaults);