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) Make a backup of the database. It's very important.

1) It's very recommended to use fresh directory for RT 4.0.
   A lot of files have been deleted and moved around in RTIR 3.0,
   so don't copy old RTIR's files.

2) Install and upgrade database to the RT 4.0.3 or newer following
   its upgrade instructions.

2.1) Test how RT upgrade went. You should be able to start server,
     create tickets and do other things in the RT interface.

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

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

4) 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 check
    instructions under "Applying changes from etc/upgrade/1.1.3"
    section below and run commands, then do the same with 1.9.0 dir
    and greater.

    *Note* that even if there is no etc/upgrade/<some version> dir
    then anyway *you must* read instructions below for all versions
    greater or equal to that you're upgrading from as some upgrades
    may require manual changes or describe important changes in
    the RTIR you should be aware of.

    Commands you should run to upgrade DB using data
    from etc/upgrade/<version> directory: If the dir has any schema
    files then run:

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

    If the dir has a file named 'content' then run:

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

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
   to backup before applying this script.

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

   This means that you have to review all customizations and
   replace use of State custom field with Status, check
   templates, scrips' conditions and actions.

   For example the following code should be replaced:

        $ticket->FirstCustomFieldValue('State');

   With:

        $ticket->Status;

   Almost every format string in $RTIRSearchResultFormats option
   had '__CustomField.{State}__' that is replaced with __Status__.
   You should update config if you have customizations.

   Format strings of all saved searches are updated with
   with above change, but regular expression is trvial and
   may skip some edge cases.

   Read more about lifecycles in RT's and RTIR's configs.

2) To keep history intact 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. Backup is really
   required. Don't forget to re-analyze and optimize tables after
   upgrade.

3) Several scrip actions are not required anymore because of
   switch to lifecycles, so modules of these action and
   all scrips based on them are deleted from directories and
   the DB.

   Started date is properly handled by lifecycles now, no need
   in RTIR_SetStartedToNow scrip action.

   IRs and Blocks still has some special status treatment, but
   it is handled by new scrips, so no need in
   RTIR_SetIncidentReportState and RTIR_SetBlockState actions.

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

4) Situation with scrip conditions is similar to above with
   actions.

   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 StatusChange
   condition that is part of RT. See example in the upgrade script
   where RTIR's RTIR_ReopenTicket and RTIR_CloseTicket conditions
   get replaced with StatusChange.

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

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

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

   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

8) New format strings in $RTIRSearchResultFormats: ListIncidents
   and LookupTool.

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

1) _RTIR_ prefix has been deleted from all RTIR's custom fields. What
   means that you have to update 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>
   file.

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

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

3) Some templates RTIR comes with contain code to insert values of
   CFs into emails. It is impossible to change these templates
   automatically. 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 simple as deleting _RTIR_ prefix and adding
   a space to three names mentioned above.

   Some of your code may still use old names. Make sure to change
   that. The following command might help you identify places:

        find dir/ | xargs grep '_RTIR_'

4) _RTIR_*_default options in the config has been merged together
   into RTIR_CustomFieldDefaults hash. Change 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
   what 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 did that or ran with earlier versions of the RTIR. 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/2.3.0
-------------------------

At these 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 these 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 these 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 into 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
replacement for the NewMessage template. Automated step doesn't delete
old template, you have to check that the new template suites your
needs and may be 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 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 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.

