UPGRADING

Upgrading from RTIR 1.2.0 or earlier
-------------------------------------

Best Practical Solutions will provide upgrade support to
RTIR Working Group members upgrading from RTIR 1.2 or older.
Please contact customer-development@bestpractical.com.

General upgrade instructions
----------------------------

0) VERY IMPORTANT: Make a backup of your database.
   This upgrade makes changes to the database. If you don't
   make a backup and something doesn't go as planned, you may
   lose data.

1) Upgrade your RT installation to RT 4.0.6 or newer following
   its upgrade instructions. Make sure you follow all of the
   steps and upgrade both the code and the database.

   As noted in the RT documentation, it is recommended that you
   use a fresh directory when upgrading to RT 4.0, like /opt/rt4,
   rather than upgrading on top of your RT 3 installation.
   A lot of files have been deleted and moved around in RTIR 3.0,
   so don't copy old RTIR's files.

2) Test your upgraded RT. You should be able to start the server,
   log in, use the RT web interface, create tickets, send email to
   RT, receive mail from RT, etc.

3) Make another backup of the DB, so you can return to this step
   if something goes wrong.

4) Install the new version of RTIR. (DO NOT RUN "make initdb")

5) Update RTIR's database.

    Type:

        ls etc/upgrade

    For each item in that directory whose name is greater than
    your previously installed RTIR version, you must run upgrade
    commands.

    Each step is described below and may have additional instructions.
    Read them before running upgrade commands.

    For example, if you had RTIR 1.1.1 then you should read the
    instructions under "Applying changes from etc/upgrade/1.1.3"
    below, run the commands, then do the same with 1.9.0 directory
    and greater until you have run all of the commands.

    *Note* that even if there is no etc/upgrade/<some version>
    directory for a particular version, you must still read the
    instructions below for all remaining versions greater than or
    equal to the version you're upgrading from. Some upgrades
    may require manual changes or describe important changes in
    the RTIR you should be aware of. Missing a set of upgrade
    instructions can result in strange behavior that can be very hard
    to diagnose.

    If the upgrade directory has any schema files, run:

        /opt/rt4/sbin/rt-setup-database --dba <dba> \
            --prompt-for-dba-password --action schema \
            --datadir etc/upgrade/<version>

    If the upgrade directory has a file named 'content' then run:

        /opt/rt4/sbin/rt-setup-database --dba <dba> \
            --prompt-for-dba-password --action insert \
            --datadir etc/upgrade/<version>

6) Re-analyze and re-optimize your database tables.

   When you have completed all of the upgrade steps, you will
   likely need to update any optimizations you have done since the
   underlying tables have probably changed.


Upgrading from 2.6.x and earlier
--------------------------------

0) Primary and very dangerous update steps are implemented
   in F<etc/upgrade/2.9.0/content>. It's highly recommended
   that you save a DB backup before applying this script.

1) RT 4.0 introduces a new feature, lifecycles, which allowed
   us to replace RTIR's four State custom fields with four RTIR
   specific lifecycles, delete the previous custom fields, and use
   RT's Status field.

   This means that you have to review all customizations and
   replace any reference to State custom fields with Status.
   You should check templates, and scrips' conditions and actions.

   For example the following code should be replaced:

        $ticket->FirstCustomFieldValue('State');

   With:

        $ticket->Status;

   Almost every format string in the $RTIRSearchResultFormats option
   had '__CustomField.{State}__' replaced with __Status__.
   Note this change as you port over your previous configuration
   files, and update your config if you have customizations.

   Format strings of all saved searches are updated with
   with above change, but the regular expression doesn't attempt
   to be too clever and may skip some edge cases.

   Read more about lifecycles in RT's and RTIR's configuration
   files.

2) To keep history intact, the upgrade script turns changes of
   the custom fields into changes of Status field. It's a big
   change to Tickets, Transactions and ObjectCustomFieldValues
   tables with updates and deletes mostly. Again, it's important
   to have a known good backup.

3) Several scrip actions are no longer required because of
   the new lifecycles features, so these action modules and
   all scrips based on them are deleted from directories and
   the DB.

   Started date is properly handled by lifecycles now, so the
   RTIR_SetStartedToNow scrip action is no longer needed.

   IRs and Blocks still have some special status treatment, but
   it is handled by new scrips, so RTIR_SetIncidentReportState
   and RTIR_SetBlockState actions are not needed.

   Investigations and Incidents don't need any special status
   treatment, so RTIR_SetInvestigationState and RTIR_SetIncidentState
   are deleted.

4) Just as some scrip actions have been removed, several scrip
   conditions also are no longer needed.

   The RTIR_RequireStateChange condition gets deleted.

   RTIR_BlockActivation gets deleted as well, however if you
   use it in custom scrips then you can replace it with a StatusChange
   condition that is part of RT. See the example in the upgrade script
   where RTIR's RTIR_ReopenTicket and RTIR_CloseTicket conditions
   get replaced with StatusChange.

5) The /RTIR/Elements/QueueSummary portlet is deleted and replaced with
   RT's Quicksearch. Update your config in case you have a custom setting
   for RTIR_HomepageSettings. Users' preferences are updated automatically.

6) Code from RTIR to support the IP custom field has been merged
   into RT 4.0 and extended to support IPv6. The upgrade script
   changes the type of the IP field.

7) RTIR had a simple Service Level Agreements (SLA) implementation.
   RT::Extension::SLA was prototyped from it, but vastly improved.
   In RTIR 3.0 we delete this basic implementation in favor of
   the extension. The SLA custom field stays as the extension uses it as
   well. However, the dependency on the extension is not mandatory and there
   is no default config for it. Read the tutorial for administrators for
   more info (lib/RT/IR/AdministrationTutorial.pod).

   The following scrip actions and scrips that use them are deleted:

        RTIR_SetDueBySLA
        RTIR_SetDueCorrespond
        RTIR_SetDueReopen
        RTIR_SetDueToNow
        RTIR_UnsetDue
        RTIR_SetStartsByBizHours
        RTIR_SetStartsToNow

   The following config options are no longer valid:

        $SLAModule
        $SLA
        $BusinessHours
        $SLA_Response_InHours
        $SLA_Response_OutOfHours
        $SLA_Reopen_InHours
        $SLA_Reopen_OutOfHours
        SLA key in %RTIR_CustomFieldsDefaults

   The upgrade process itself won't modify any existing due dates, but
   if you are using the older SLA configuration, you need to install
   RT::Extension::SLA and port over your current SLA configuration to
   the new module. If you are installing the module for the first time,
   you will need to run the 'make initdb' step to get the proper scrips
   installed. You should then test with the new SLA configurations in
   a dev environment to verify that due dates are being properly set
   for all relevant actions (create, respond, resolve, etc.).

8) New format strings are provided for $RTIRSearchResultFormats:
   ListIncidents and LookupTool.

Upgrading from 2.4.x and earlier
--------------------------------

1) _RTIR_ prefix has been deleted from all RTIR's custom fields. This
   means you have to update any custom code you have: templates,
   scrips and other customizations which may have name of a custom
   field hardcoded.

   Custom Fields with multiple words in the name and no spaces have
   been renamed, now there is space. These custom fields are:

       HowReported  => How Reported
       ReporterType => Reporter Type
       WhereBlocked => Where Blocked

   All these changes are implemented in F<etc/upgrade/2.5.1/content>

2) Saved searches are affected by the above change and you can convert
   them using a script provided.

       perl -I /opt/rt4/local/lib -I/opt/rt4/lib etc/upgrade/2.5.1/update_saved_searches.pl

3) Some standard RTIR templates contain code to insert values of
   CFs into emails. It is impossible to change these templates
   automatically, so you have to do it manually. To identify templates
   and/or confirm that all has been changed you can use the following
   SQL query:

       SELECT id, Queue FROM Templates WHERE Content LIKE '%_RTIR_%';

   Usually this change is as simple as deleting the _RTIR_ prefix and
   adding a space to the three names mentioned above.

   Some of your code may still use the old names as well, so you'll
   need to update it. The following command might help you identify
   where it's used:

        find dir/ | xargs grep '_RTIR_'

4) _RTIR_*_default options in the config have been merged together
   into the RTIR_CustomFieldDefaults hash. Change your site config
   accordingly.

Upgrading from 2.4.4 and earlier
--------------------------------

SubjectTag was ignored in RTIR templates, so users could be confused.
Find all templates with the following text:

    [{$rtname} #{$Ticket->id}]

And replace it with:

    [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]

Upgrading from 2.3.17 and earlier
---------------------------------

1) Layout of files in RT's directories have been changed in RT 3.8.0.
   Each extension is installed in its own directory and is activated
   using @Plugins options in the RT config.

2) By accident RTFM's CustomField Response could be created with MaxValues = 0
   which is incorrect and should be changed to 1. Run the following query to
   update the DB.

    UPDATE CustomFields SET MaxValues = 1 WHERE
            Name = 'Response'
            AND Type = 'Text'
            AND LookupType = 'RT::FM::Class-RT::FM::Article'
            AND MaxValues = 0;

Upgrading from 2.3.15 and earlier
---------------------------------

There was an error in the etc/upgrade/upgrade.pl script. It could skip
some incidents during upgrade. Run this script again, especially if you
never ran it or ran with earlier versions of the RTIR. This script
updates Due dates on active incidents where it's not set and sets it to
the most recent due date of the active children.

Applying changes from upgrade/2.3.0
-----------------------------------

At this step no special actions are required. Run the upgrade scripts where we
split out incidents owned by Nobody and the Current User on the most-due views
on the homepage.

Applying changes from upgrade/2.1.1
-----------------------------------

At this step no special actions are required. Run the upgrade
scripts where we add several scrips that set 'Started' date
of tickets in the RTIR.

Applying changes from upgrade/2.1.0
-----------------------------------

At this step no special actions are required. Run the upgrade
scripts where we do following things:

1) Apply the _RTIR_IP CF to all RTIR's queues and convert it to
   multiple type. Also, we add several scrips to parse IP addresses
   from incomming mails and to fill those into the CF.

2) The constituency field we apply to all RTIR's queues too and
   and add several scrips to track values of the field.

Applying changes from upgrade/1.9.0
-----------------------------------

1) The LaunchMessage template in the Investigations queue
   has been renamed to Autoreply without any changes of the content.
   This upgrade step is automated, but may fail if you've changed
   the LaunchMessage template.

2) In the Blocks queue an Autoreply template has been added. This is
   a replacement for the NewMessage template. The automated step
   doesn't delete the old template. You have to check that the new
   template suits your needs, maybe copy customizations from the old
   one, then delete the NewMessage template.

3) NotifyOnLaunch and NotifyOnCreate scrips have been deleted in
   the Implementations and the Blocks queues respectively. You have to
   use the default RT's Autoreply scrip instead or create autoreply
   scrips in these queues if the global one is disabled or doesn't exist.
   You need the following scrip in the queues:

   On Create AutoReply to Requestors with Template Autoreply

4) The new 'BlockRemoved' template has been added in the Blocks
   queue. Check its content.

Applying changes from upgrade/1.1.3
-----------------------------------

No special steps required, just run the upgrade scripts. Everything
is automated. At this step we install several new actions,
conditions and scrips that had been introduced in the RTIR 1.1.3.
Also, we change action of the 'SetDueReopen' scrips.

Applying changes from upgrade/1.1.1
-----------------------------------

1) At this step we switch from 'UserDefined' actions and conditions
   to modules, so all code would be in the lib directory. If you changed
   the code of the scrips then you have to port changes.

2) Run the etc/upgrade/upgrade.pl script. This script updates Due Dates
   on active incidents where it's not set and set to the most recent due
   date of the active children.

Applying changes from upgrade/1.0.3
-----------------------------------

No special steps required, just run upgrade scripts. Everything
is automated. At this step we grant the ShowTemplate right to
the DutyTeam group.

Upgrading from RTIR 1.0.0:
--------------------------

RTIR now installs in RT's local/plugins/RT-IR directory rather than local/html,
making local modifications to RTIR easier.

1) IMPORTANT! Back up any modifications that you've made to the
   /opt/rt3/local/html/RTIR directory.

2) Remove the old RTIR files or better install everything into clean directory
   as described in the beginning of this file.