[Rt-commit] [rtir] 01/01: Create docs directory and move UPGRADING and RTIR docs
Jim Brandt
jbrandt at bestpractical.com
Mon May 6 14:29:16 EDT 2013
This is an automated email from the git hooks/post-receive script.
jbrandt pushed a commit to branch 2.9/rtir-docs-dir
in repository rtir.
commit f4c0817d99e534585f721d76599c4ec42a793e89
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Mon May 6 13:36:32 2013 -0400
Create docs directory and move UPGRADING and RTIR docs
---
UPGRADING | 368 -------------------------
{lib/RT/IR => docs}/AdministrationTutorial.pod | 16 +-
{lib/RT/IR => docs}/Constituencies.pod | 4 +-
{lib/RT/IR => docs}/DocIndex.pod | 2 +-
{lib/RT/IR => docs}/Tutorial.pod | 8 +-
docs/UPGRADING | 103 +++++++
docs/UPGRADING-2.4 | 158 +++++++++++
docs/UPGRADING-2.6 | 69 +++++
docs/UPGRADING-3.0 | 142 ++++++++++
9 files changed, 487 insertions(+), 383 deletions(-)
diff --git a/UPGRADING b/UPGRADING
deleted file mode 100644
index 272be8e..0000000
--- a/UPGRADING
+++ /dev/null
@@ -1,368 +0,0 @@
-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 at 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.
diff --git a/lib/RT/IR/AdministrationTutorial.pod b/docs/AdministrationTutorial.pod
similarity index 97%
rename from lib/RT/IR/AdministrationTutorial.pod
rename to docs/AdministrationTutorial.pod
index 79b2e52..291703b 100644
--- a/lib/RT/IR/AdministrationTutorial.pod
+++ b/docs/AdministrationTutorial.pod
@@ -208,7 +208,7 @@ the same way.
Keeps the Due date of incidents in sync with the most due child.
-See L</Service Level Agreements> below for details on automating
+See L</"Service Level Agreements (SLAs)"> below for details on automating
Due dates, and L<RT::Action::RTIR_SetDueIncident> for details
about action of the scrip.
@@ -275,14 +275,14 @@ It's OK to disable this scrip.
Applies to the Incident Reports, Blocks, Incidents and Investigations queues.
-Uses the Constituency algorithms discussed in L<RT::IR::Constituencies> to
+Uses the Constituency algorithms discussed in L<RT::IR::Constituencies> to
set and propagate changes to the Constituency custom field. On ticket
-creation, Constituency is set based on the parent ticket, the
-X-RT-Mail-Extension header (see L<RT::IR::Constituencies>) or the default set
+creation, Constituency is set based on the parent ticket, the
+X-RT-Mail-Extension header (see L<RT::IR::Constituencies>) or the default set
in your F<RTIR_Config.pm>
When linking tickets or changing the Constituency custom field, this
-scrip ensures that the change is propagated based on your choice of
+scrip ensures that the change is propagated based on your choice of
_RTIR_Constituency_Propagation in your F<RTIR_Config.pm>
=item SetConstituencyGroup
@@ -329,7 +329,7 @@ See the documentation for L<RT::Extension::TicketAging>
During normal operation RT/RTIR never deletes data from the database.
Since RT 3.7 the RTx::Shredder extension has been integrated into
RT. This extension can remove data such as users or tickets
-from the RT/RTIR system. You can find documentation for this
+from the RT/RTIR system. You can find documentation for this
extension in L<RT::Shredder> by running `perldoc lib/RT/Shredder.pm`
or on the Best Practical website at
L<http://bestpractical.com/rt/docs/latest/RT/Shredder.html>.
@@ -362,7 +362,7 @@ automatically choose it instead of asking the user.
If a user has no trusted keys, then the web interface will warn and refuse to
send him an encrypted message. This is ultimately due to limitations in GnuPG:
we cannot encrypt a message with an untrusted key. Managing the trust levels
-of keys must be done outside of RT as there is not currently key management
+of keys must be done outside of RT as there is not currently key management
support available.
=head3 Missing passphrase
@@ -375,7 +375,7 @@ A missing passphrase occurs when GPG Agent is unresponsive or the passphrase
is wrong in F<RTIR_SiteConfig.pm>. Note that you can use either GPG Agent or
set the passphrase in the site config, you need not do both.
-=head2 Service Level Agreements (SLA)
+=head2 Service Level Agreements (SLAs)
RTIR used to have a simple Service Level Agreements (SLA) implementation.
L<RT::Extension::SLA> was prototyped on it, but vastly improved. In RTIR 3.0
diff --git a/lib/RT/IR/Constituencies.pod b/docs/Constituencies.pod
similarity index 99%
rename from lib/RT/IR/Constituencies.pod
rename to docs/Constituencies.pod
index 9600d8a..2830d53 100644
--- a/lib/RT/IR/Constituencies.pod
+++ b/docs/Constituencies.pod
@@ -25,7 +25,7 @@ in a single RTIR instance with shared workflows and global
configuration that applies to all constituencies. This guide
will help you configure RTIR to manage multiple constituencies.
-=head2 Definitions
+=head2 Definitions
A constituency is defined by:
@@ -253,7 +253,7 @@ unless it's also empty. The last fallback address is the C<$CorrespondAddress>
in the RT's configuration file.
It is important to note that these additional rights do not also
-add new mailing rules.
+add new mailing rules.
=head2 Presetting Constituency from Email
diff --git a/lib/RT/IR/DocIndex.pod b/docs/DocIndex.pod
similarity index 97%
rename from lib/RT/IR/DocIndex.pod
rename to docs/DocIndex.pod
index 5ff5011..b3492af 100644
--- a/lib/RT/IR/DocIndex.pod
+++ b/docs/DocIndex.pod
@@ -2,7 +2,7 @@
RTIR's documentation can be found in POD form in the lib/RT/IR/
subdirectory of your RTIR install. Some things may be documented
-with specific tools (such as rt-mailgate) or with RT's standard
+with specific tools (such as rt-mailgate) or with RT's standard
documentation. Other topics will be documented in
the perl modules that comprise RTIR
diff --git a/lib/RT/IR/Tutorial.pod b/docs/Tutorial.pod
similarity index 99%
rename from lib/RT/IR/Tutorial.pod
rename to docs/Tutorial.pod
index 6bf3891..1eddadd 100644
--- a/lib/RT/IR/Tutorial.pod
+++ b/docs/Tutorial.pod
@@ -5,7 +5,7 @@
RTIR automatically creates four RT queues for tracking incidents: Incident
Reports, Incidents, Investigations and Blocks.
-=head3 Incident Reports
+=head3 Incident Reports
Incident Reports is where new reports appear. When a user sends email to the
address you set up, RTIR automatically creates an Incident Report (IR), and
@@ -73,7 +73,7 @@ merge an IR into an Investigation. Note that if you
merge an IR into an Investigation, the Investigation will always
be used as the target ticket.
-If the merge completes successfully, you'll be redirected to the
+If the merge completes successfully, you'll be redirected to the
target ticket's display page.
When the merge page doesn't have the ticket you're looking for,
@@ -125,8 +125,8 @@ apply. In the normal course of work, this operation should be avoided.
=head3 Splitting Tickets
The Split operation allows you to create a new ticket from an existing one.
-When you click the Split tab, you get a new ticket creation form
-with information pre-filled from the original ticket, for example Subject,
+When you click the Split tab, you get a new ticket creation form
+with information pre-filled from the original ticket, for example Subject,
Owner, Correspondents(Requestors), Ccs, AdminCs, as well as the original ticket's
history, formatted as text in the message box. You can change any and all
values before splitting off the new ticket.
diff --git a/docs/UPGRADING b/docs/UPGRADING
new file mode 100644
index 0000000..7744a70
--- /dev/null
+++ b/docs/UPGRADING
@@ -0,0 +1,103 @@
+=head1 Upgrading RTIR
+
+This document provides general instructions for upgrading
+RTIR to the most recent version regardless of the version you
+are currently using. In addition to these instructions, you should look
+in the version-specific UPGRADING files provided in this distribution
+for additional upgrade steps. Instructions for upgrading RT
+are provided with the RT distribution.
+
+RT and RTIR are commercially-supported software. If you need help
+upgrading your RTIR instance or need other services related to RT
+or RTIR, please get in touch with us at <sales at bestpractical.com>.
+
+=head1 General Upgrade Instructions
+
+=over
+
+=item 1
+
+B<VERY IMPORTANT!> Make a backup of your database.
+These upgrade scripts often make changes to the database. If you don't
+make a backup and something doesn't go as planned, you may
+lose data.
+
+=item 2
+
+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.
+
+=item 3
+
+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.
+
+=item 4
+
+Make another backup of the DB, so you can return to this step
+if something goes wrong.
+
+=item 5
+
+Install the new version of RTIR. B<DO NOT> run C<make initdb>.
+
+=item 6
+
+Update RTIR's database.
+
+Type:
+
+ ls etc/upgrade
+
+For each item in that directory whose name is greater than
+your previously installed RTIR version (a later 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 L<UPGRADING-2.4/"Applying Changes from upgrade/1.1.3">,
+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 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
+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 C<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 C<content> then run:
+
+ /opt/rt4/sbin/rt-setup-database --dba <dba> \
+ --prompt-for-dba-password --action insert \
+ --datadir etc/upgrade/<version>
+
+=item 7
+
+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.
+
+=back
+
+=cut
diff --git a/docs/UPGRADING-2.4 b/docs/UPGRADING-2.4
new file mode 100644
index 0000000..8bd3399
--- /dev/null
+++ b/docs/UPGRADING-2.4
@@ -0,0 +1,158 @@
+=head1 Upgrading to 2.4
+
+The following describes some of the key components of the upgrade
+to RTIR 2.4 from all previous versions of RTIR.
+
+The F<etc/upgrade/upgrade.pl> script is mentioned several times
+for different versions. You only need to run it once and the most
+recent version is now included in the RTIR distribution.
+
+=head1 Upgrading from 2.3.17 and Earlier
+
+=head2 RT Extension Location
+
+The layout of files in RT's directories was changed in RT 3.8.0.
+Each extension is now installed in its own directory and is activated
+using the @Plugins option in the RT config.
+
+=head2 RTFM's Response Custom Field
+
+RTFM's Response custom field 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;
+
+=head1 Upgrading from 2.3.15 and Earlier
+
+There was an error in an earlier version of the F<etc/upgrade/upgrade.pl>
+script where it could skip some incidents during upgrade. Run the new version
+of this script, especially if you never ran it or ran with earlier versions
+of 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.
+
+=head1 Applying Changes from upgrade/2.3.0
+
+Run the upgrade scripts where we split out incidents owned by Nobody and
+the Current User on the most-due views on the homepage.
+
+=head1 Applying Changes from upgrade/2.1.1
+
+Run the upgrade scripts where we add several scrips that set 'Started'
+date of tickets in RTIR.
+
+=head1 Applying Changes from upgrade/2.1.0
+
+Run the upgrade scripts where we do following:
+
+=over
+
+=item 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.
+
+=item 2
+
+The constituency field we apply to all RTIR's queues too and
+and add several scrips to track values of the field.
+
+=back
+
+=head1 Applying Changes from upgrade/1.9.0
+
+Run the upgrade scripts where we do following:
+
+=over
+
+=item 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.
+
+=item 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.
+
+=item 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
+
+=item 4
+
+The new 'BlockRemoved' template has been added in the Blocks
+queue. Check its content.
+
+=back
+
+=head1 Applying Changes from upgrade/1.1.3
+
+Run the upgrade scripts where we install several new actions,
+conditions and scrips that had been introduced in RTIR 1.1.3.
+Also, we change the action for 'SetDueReopen' scrips.
+
+=head1 Applying Changes from upgrade/1.1.1
+
+Run the upgrade scripts where we do following:
+
+=over
+
+=item 1
+
+Switch from 'UserDefined' actions and conditions
+to modules, so all code is in the lib directory. If you changed
+the code of the scrips then you have to port changes.
+
+=item 2
+
+Run the F<etc/upgrade/upgrade.pl> script. This script updates Due Dates
+on active incidents where they are not set and sets them to the most
+recent due date of the active children.
+
+=back
+
+=head1 Applying Changes from upgrade/1.0.3
+
+Run the upgrade scripts where we grant the ShowTemplate right to
+the DutyTeam group.
+
+=head1 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. Do the following:
+
+=over
+
+=item 1
+
+IMPORTANT! Back up any modifications that you've made to the
+F</opt/rt3/local/html/RTIR> directory.
+
+=item 2
+
+Remove the old RTIR files and install everything into clean directory
+as described in the install instructions. B<Do not> run the database
+init step.
+
+=back
+
+=cut
diff --git a/docs/UPGRADING-2.6 b/docs/UPGRADING-2.6
new file mode 100644
index 0000000..4d7af19
--- /dev/null
+++ b/docs/UPGRADING-2.6
@@ -0,0 +1,69 @@
+=head1 Upgrading to 2.6
+
+The following describes some of the key components of the upgrade
+to RTIR 2.6 from previous versions of RTIR, specifically
+from RTIR 2.4. The other UPGRADING documents contain details
+for previous versions.
+
+=head1 Upgrading from 2.4.x and Earlier
+
+=head2 _RTIR_ Prefix Removed
+
+_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>
+
+=head3 Custom Field Updates in Saved Searches
+
+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
+
+=head3 Custom Field Updates in Templates
+
+Some standard RTIR templates contain code to insert values of
+CFs into emails. It is impossible to safely 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_'
+
+=head3 Custom Fields Configuration
+
+The _RTIR_*_default options in the config have been merged together
+into the RTIR_CustomFieldDefaults hash. Change your site config
+accordingly.
+
+=head1 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}]
+
+=cut
diff --git a/docs/UPGRADING-3.0 b/docs/UPGRADING-3.0
new file mode 100644
index 0000000..9b100aa
--- /dev/null
+++ b/docs/UPGRADING-3.0
@@ -0,0 +1,142 @@
+=head1 Upgrading to 3.0
+
+The following describes some of the key components of the upgrade
+to RTIR 3.0 from previous versions of RTIR, specifically
+from RTIR 2.6. The other UPGRADING documents contain details
+for previous versions.
+
+=head2 Database
+
+The update steps implemented in the upgrade script
+F<etc/upgrade/2.9.0/content> make significant changes to the
+database and its data. It's highly recommended that you save
+a DB backup before applying this script.
+
+=head2 Lifecycles
+
+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 standard 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:
+
+ $ticket->FirstCustomFieldValue('State');
+
+should be replaced 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.
+
+You can read more about lifecycles in RT's and RTIR's configuration
+files.
+
+=head2 Search Result Formats
+
+In addition to the changes for Status, new format strings are
+provided for $RTIRSearchResultFormats: ListIncidents and LookupTool.
+
+=head2 Changes to Ticket History
+
+To keep history intact, the upgrade script turns changes of
+the previous State custom fields into Status field changes. This
+a big change to the Tickets, Transactions and ObjectCustomFieldValues
+tables with updates and deletes mostly. Again, it's important
+to have a known good backup.
+
+=head2 Retired Scrip Actions
+
+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.
+
+=head2 Retired Scrip Conditions
+
+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.
+
+=head2 RTIR Queue Summary Portlet
+
+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.
+
+=head2 IP Custom Field
+
+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.
+
+=head2 SLA Support
+
+RTIR had a simple Service Level Agreements (SLA) implementation.
+L<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 L<AdministrationTutorial/"Service Level Agreements (SLA)">.
+
+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
+L<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.).
+
+=cut
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the Rt-commit
mailing list