[Rt-commit] [rtir] 01/01: Create docs directory and move UPGRADING and RTIR docs

[Jim Brandt]

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 ffe00eb5d559b5ecd7dad73b7ea84ccfeda1a2ff
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
---
 docs/AdministrationTutorial.pod | 392 ++++++++++++++++++++++++++++++++++++
 docs/Constituencies.pod         | 359 +++++++++++++++++++++++++++++++++
 docs/DocIndex.pod               | 166 ++++++++++++++++
 docs/Tutorial.pod               | 427 ++++++++++++++++++++++++++++++++++++++++
 docs/UPGRADING                  | 103 ++++++++++
 docs/UPGRADING-2.4              | 158 +++++++++++++++
 docs/UPGRADING-2.6              |  69 +++++++
 docs/UPGRADING-3.0              | 142 +++++++++++++
 8 files changed, 1816 insertions(+)

diff --git a/docs/AdministrationTutorial.pod b/docs/AdministrationTutorial.pod
new file mode 100644
index 0000000..e26c788
--- /dev/null
+++ b/docs/AdministrationTutorial.pod
@@ -0,0 +1,392 @@
+=head1 RTIR Administrative Tutorial
+
+=head2 General Configuration
+
+RT and RTIR store many configuration items in configuration files
+on the file system in the etc directory in your RT directory.
+F<RT_Config.pm> and F<RTIR_Config.pm> provide documentation on all available
+configuration options and also set system defaults. You can view these
+files to see what configuration options are available, but don't edit
+these files to change configuration values. The F<RT_SiteConfig.pm> file
+is specifically provided to store your site-specific configurations.
+
+To change a configuration value, copy the Set code from F<RT_Config.pm>
+or F<RTIR_Config.pm> and add it to your F<RT_SiteConfig.pm>. Then set
+your custom configuration values there.
+
+=head2 Blocks Queue
+
+You may disable the Blocks queue by putting the following into your
+RT_SiteConfig.pm config:
+
+    Set($RTIR_DisableBlocksQueue, 1);
+
+You will probably also want to disable the Queue using the RT
+Administrative interface.  Tools -> Configuration -> Queues -> Blocks,
+uncheck Enabled and click Save Changes.
+
+=head2 Status
+
+The various states an incident, IR, investigation, or block can be in, such as
+'open', 'stalled', 'abandoned', etc.
+
+This field contains custom statuses for tickets, and values are different in
+different queues. The status values are set via the C<%Lifecycles> option in
+the RTIR configuration file. You can read more about Lifecycles in the
+F<RT_Config.pm> file.
+
+Status is a critical field for functionality.
+
+For more information, read the description in F<RTIR_Config.pm> and description
+of L</Scrips> below.
+
+=head2 Custom Fields
+
+When RTIR is installed several custom fields are created and applied
+to queues in RTIR. Some of these custom fields are important for
+RTIR functionality and can not be renamed, disabled or un-applied,
+but other fields can be.
+
+=over 4
+
+=item Constituency
+
+The constituency of an incident, IR, investigation, or block.
+
+Additional quite heavy automation is tied to this field. This
+is described in L<Constituencies> doc. Don't rename this field
+if you want to use this functionality.
+
+=item Description
+
+Short description of an Incident.
+
+=item Resolution
+
+How an Incident was or wasn't resolved.
+
+=item Function
+
+Who is handling the Incident.
+
+=item Classification
+
+The type of Incident, such as system compromise or denial of service.
+
+=item How Reported
+
+How the IR got into RTIR.
+
+=item ReporterType
+
+Context for the incident reporter, such as the police, other ISP,
+or external individual.
+
+=item IP
+
+IP addresses related to the incident, IR, investigation, or block.
+
+Don't rename this custom field or it will lose all associated features.
+It's possible to change this CF from multiple values to single value.
+
+See L<Tutorial/'IP'> for more information.
+
+See also L</SetIPFromContent> below.
+
+=item Netmask
+
+Network mask for a Block.
+
+=item Port
+
+Port for a Block.
+
+=item Where Blocked
+
+Where the block is placed.
+
+=item Customer
+
+Customer for an IR or Investigation.
+
+=back
+
+=head2 Managing "RT at a glance" and "RTIR at a glance" pages
+
+In the config you can set the @RTIR_HomepageComponents option to control
+allowed portlets people can add to thier workspace. RT has its own
+option $HomepageComponents so you can list different sets for RT and
+RTIR. See L<Tutorial> for more information.
+
+=head2 Notifications
+
+Almost all email notifications in RT/RTIR are controlled via scrips.
+
+There are three default base actions you can use to notify users:
+
+=over 4
+
+=item Notify
+
+Sends a notification to users. The reply-to field is set
+based on the correspond address. The NotifyActor option also
+influences the set of recipients.
+
+=item Notify As Comment
+
+Similar to 'Notify', but the reply-to field is set based on
+the comment address.
+
+=item Autoreply
+
+A variation of the 'Notify' action which sends email even if the
+NotifyActor option is disabled.
+
+=back
+
+The above actions have multiple variants with different list of recipients,
+for example 'Notify Owner' or 'Notify Requestors'. The list of recipients
+may contain the following values: 'Requestors', 'Owner', 'Ccs', 'AdminCcs'
+and 'Other Recipients'. 'Other Recipients' is the only special case,
+these are users who are listed as one-time recipients on the ticket's
+reply/comment pages. All other entries are watchers of a ticket.
+The list can be a combination of values like 'Owner, Ccs, AdminCcs'.
+
+Here are several examples:
+
+    On Correspond Notify Requestors and Ccs with template Correspondence
+    On Create Autoreply To Requestors with template Autoreply
+    On Owner Change Notify Owner with template Transaction
+
+Text of notifications is controlled using templates where a queue's template
+can override the global one. For example you can create a template 'Correspondence'
+in a queue and all notifications (global or queue specific) will use
+that template instead of the global template.
+
+=head2 Scrips
+
+Scrips run for every transaction on a ticket in RT and RTIR,
+sometimes changing values based on the transaction being
+performed. Transactions are any change to a ticket, whether
+updating a status or replying to a requestor.
+
+=over 4
+
+=item SetHowReported
+
+Applies to the Incident Reports queue.
+On ticket creation, sets the HowReported custom field to a default
+value of Email if it isn't otherwise specified.
+
+=item On Correspond Change Status of the Block
+
+On replies, changes the status of blocks according to a few rules
+that are described in L<RT::Action::RTIR_SetBlockStatus/DESCRIPTION>.
+
+RT's default L<RT::Action::AutoOpen> is disabled for blocks to
+avoid unwanted changes of status from 'pending activation'
+to 'active'.
+
+See also the C<$RTIR_BlockAproveActionRegexp> option
+in the config.
+
+=item On Linking To Incident Activate Report
+
+=item On Correspond (not every) Activate Report
+
+IRs are activated (status changed to first possible active status,
+by default 'open') only when they are linked to an incident.
+These two scrips take care of that.
+
+RT's default L<RT::Action::AutoOpen> is disabled for IRs to avoid
+unwanted changes of status when an IR is not linked. When an IR is
+linked to an Incident, L<RT::Condition::RTIR_RequireReportActivation>
+checks everything that RT's AutoOpen checks and the scrip behaves in
+the same way.
+
+=item Set Due Date On Incident
+
+Keeps the Due date of incidents in sync with the most due child.
+
+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.
+
+=item ResolveAllChildren
+
+Applies to the Incidents queue.
+
+If an incident is changed to an inactive status,
+looks for linked tickets in the Incident Reports, Investigations or Blocks
+queues and resolves them.  If any of these linked tickets are linked
+to other ongoing incidents, a comment is added and they remain unresolved.
+
+=item FixOwnership
+
+Applies to the Incidents queue.
+
+When the Owner of an incident is changed, the Owner of linked children
+tickets are changed to the same owner.
+
+Applies to the Incident Reports, Blocks and Investigations queues.
+
+When the Owner of a ticket in these queues is changed, that change
+is also applied to the linked incident.
+
+=item ReopenIncident
+
+Applies to the Incident Reports, Blocks and Investigations queues.
+
+If the status of a ticket in these queues is changed from rejected or
+resolved, the linked parent incident ticket status is set to open.
+
+=item SetDefaultIncidentResolution
+
+Applies to the Incidents queue.
+
+When an incident's status is changed, if it is changed from an
+inactive status to an active status, the Resolution custom field
+is cleared. If it is changed from an active status to an inactive status
+and the Resolution custom field isn't set manually, it is set
+to the value set in %RTIR_CustomFieldsDefaults in your
+F<RTIR_Config.pm>.
+
+=item NotifyOnClose
+
+Applies to the Blocks queue.
+
+When a block ticket is moved from an active status to an inactive
+status (closed), the requestors on the block are notified using the
+L<Templates/BlockRemoved in Blocks queue> template.
+
+=item SetIPFromContent
+
+Applies to the Incident Reports, Blocks, Incidents and Investigations queues.
+
+Updates the ticket custom field IP to have a list of all IPs and IP ranges
+found in the body of the ticket during Create and Correspond.
+
+If configuration of the CF allows only one value then only first IP
+from the content is used.
+
+It's OK to disable this scrip.
+
+=item SetConstituency
+
+Applies to the Incident Reports, Blocks, Incidents and Investigations queues.
+
+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 
+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 
+_RTIR_Constituency_Propagation in your F<RTIR_Config.pm>
+
+=item SetConstituencyGroup
+
+Applies to the Incident Reports, Blocks, Incidents and Investigations queues.
+
+When tickets are created, or the Constituency custom field is updated,
+this scrip manages the assignment of DutyTeam groups as AdminCcs.
+It makes sure that for a Constituency EDUNET, a DutyTeam group
+named 'DutyTeam EDUNET' is assigned as AdminCc and removes other DutyTeam
+groups from the AdminCc.  L<RT::IR::Constituencies/ACLs> discusses
+how to use these groups.
+
+=back
+
+=head2 Templates
+
+=over 4
+
+=item Autoreply in Blocks queue
+
+This template is sent when a block is created.
+
+=item BlockRemoved in Blocks queue
+
+This template is sent when a block is removed.
+
+=item Autoreply in Investigations queue
+
+This template is sent when a new investigation is launched.
+
+=back
+
+=head2 Locking
+
+See the documentation for L<RT::Extension::TicketLocking>
+
+=head2 Aging
+
+See the documentation for L<RT::Extension::TicketAging>
+
+=head2 Maintaining DB size, deleting entries, restoring deleted data
+
+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 
+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>.
+RT::Shredder's documentation includes information on restoring deleted data
+from backups. RT::Shredder provides SQL commands to reverse any delete
+operations, so any data that it deletes may be restored.
+
+=head2 GnuPG support
+
+GnuPG integration is now a feature of RT.  Configuration
+can be done in your F<RT_SiteConfig.pm>.
+See also the documentation in L<RT::Crypt::GnuPG>.
+
+=head3 Reverification
+
+RTIR supports reverification of incoming email. If a user sends signed mail
+but RTIR doesn't have his public key (or if some other error occurs), then his
+message will be be processed, but there will be "This message is
+unverified" warnings in the UI. Afterwards, RTIR will automatically attempt to
+reverify that message whenever someone views it.
+
+=head3 Key selection
+
+Sometimes a user will have multiple public keys in RTIR's GPG database. When
+that happens, RTIR has the user writing the message decide which key to use
+when sending that user encrypted mail. They are listed as fingerprints along
+with their trust levels. If only one key is valid, then RTIR will
+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 
+support available.
+
+=head3 Missing passphrase
+
+If RTIR is asked to sign an outgoing message and the passphrase is unavailable,
+it will detect this and avoid sending any email. The user will be asked to
+notify a system administrator.
+
+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 (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
+we removed the SLA implementation in the core of RTIR that was in conflict
+with the extension.
+
+If you install and configure L<RT::Extension::SLA> do not apply it to
+the Incidents queue.  You will encounter a race condition between the
+extension and the RTIR scrips that synchronize due dates between
+an incident and its most due active child.  If you need to manage
+incident due dates using the SLA extension, you can disable the RTIR
+scrips that manage due dates on the Incidents queue.
+
+=cut
diff --git a/docs/Constituencies.pod b/docs/Constituencies.pod
new file mode 100644
index 0000000..9600d8a
--- /dev/null
+++ b/docs/Constituencies.pod
@@ -0,0 +1,359 @@
+=head1 Multiple Constituency Functionality
+
+In some cases, your incident response team may provide
+services to multiple different "customers" or constituent
+groups. For example, you my provide incident support for both
+educational and governemental institutions.
+You may have different contact mechanisms for members
+of these groups including different email addresses for reporting
+incidents. For a variety of reasons, it makes sense to identify and
+separately track interactions with these individual constituencies,
+particularly when handling incidents.
+
+However, it also makes sense to use the same tools when
+working on these separate sources of data. Depending on the
+constituency, different users may wish to work on incidents within
+different queues or have access to incident data held within different
+queues. Members on the education response team may not have privileges
+to see information on government incidents, so you need to be able to
+assign user privileges depending on the constituency.
+
+With some additional configuration, RTIR provides a flexible system
+that supports setting up multiple constituencies with different
+incident handling and access rules. These configurations all run
+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 
+
+A constituency is defined by:
+
+=over
+
+=item  *
+
+Its name.
+
+=item  *
+
+Its correspondence email address.
+
+=item *
+  Associated ACLs (rights and permissions for queues, tickets, etc.)
+
+=back
+
+A ticket is assigned a constituency in a few different ways:
+
+=over
+
+=item *
+
+On new incoming incident report, the constituency is preset
+automatically based on the email address the email is sent to
+(the correspond address).
+
+=item *
+
+Any new incidents created from incident reports, or blocks and
+investigations created from incidents, inherit the constituency
+from the launching ticket.
+
+=item *
+
+You can manually assign the constituency to any new tickets created
+in the RTIR web interface.
+
+=item *
+
+You can manually change the constituency of a ticket and all its
+related tickets.
+
+=back
+
+Of course the last two points require that the user has the right to do so,
+according to the ACLs. All tickets must belong to a constituency.
+
+=head1 Implementation Details
+
+=head2 Mandatory
+
+The constituency field is a mandatory field, so users must select a value
+when creating RTIR tickets.
+
+=head2 Constituency Values
+
+Constituency is a custom field that applies to all RTIR queues. The RTIR
+administrator can manage the field and its values via the web interface at
+Tools -> Configuration -> Custom Fields -> click on Constituency custom field.
+At the bottom of the page in the Values section, you can add, delete, and
+rename values, and change the sort order.
+
+However, to get advanced control over constituencies you have to create additional
+objects in the system. The steps below describe how to do this manually. An
+F<add_constituency> script is also provided which helps add new constituency
+values, along with their associated groups and queues. You'll find this in the
+F<etc> directory in your RTIR distribution.
+
+=head2 Managing Constituency Values
+
+In some simple configurations, administrators may use the web interface
+to add, delete, or rename values for the 'Constituency' field, however
+if you need the advanced access control RTIR's Constituencies system
+provides, you need to create several queues and groups for each
+value.
+
+For example the following objects affect the rights users can have to
+the constituency 'EDUNET':
+
+=over
+
+=item * Queue 'Incident Reports - EDUNET'
+
+=item * Queue 'Incidents - EDUNET'
+
+=item * Queue 'Inestigations - EDUNET'
+
+=item * Queue 'Blocks - EDUNET'
+
+=item * Group 'DutyTeam EDUNET'
+
+=back
+
+These queues are used to store limited per-constituency information for
+tickets in the master queue. For example, you
+can set the constituency base correspond and comment addresses.
+
+See L</"Access Control (ACLs)"> below for more about granting rights using
+special queues and groups.
+
+=head2 Constituency Propagation
+
+The C<$_RTIR_Constituency_Propagation> config option determines
+how constituency values are inherited between linked tickets.
+There are three option: 'no', 'inherit' and 'reject'.
+These algorithms are defined in L</Constituency Propagation Options>.
+
+=head3 Introduction
+
+Before discussing constituency propagation in depth let's look at
+the primary ways of setting and changing the Constituency field.
+
+=over
+
+=item Creating a new ticket without links
+
+This is the simplest case. A user creates a new ticket and there is no reference
+to an existing ticket. For example, the user creates
+an IR using the web UI by clicking RTIR -> Incident Reports -> Create,
+fills in values, and leaves the Incident input blank. In this case
+Constituency will be set to the default, set in C<%RTIR_CustomFieldsDefaults>
+in the RTIR configuration, or to the value the user
+selects.
+
+=item Creating a new ticket with a link
+
+RTIR allows users to create new tickets and link them with another
+as a single step. For example a user can create a new IR from an Incident
+or launch an Investigation from it. When a ticket is created based on an
+existing ticket, we can use the core information from the existing ticket,
+including the constituency value. In this case, the configuration option
+defines whether the user is allowed to manually change the constituency
+value.
+
+=item Creating a new ticket with Incident Id
+
+This case is similar to the first case, but the user provides
+an Incident Id in the Incident field. Since the new ticket references
+and existing ticket, constituency logic can come into play as
+noted in the second case.
+
+=item Updating an existing ticket
+
+Users can edit an existing ticket and change the Constituency value,
+and this can affect linked tickets as well. This case in
+particular is controlled by the propagation option you set.
+
+=back
+
+=head3 Constituency Propagation Options
+
+The three propagation algorithms are available:
+
+=head3 no
+
+This is the default algorithm. Any combinations are allowed. Users can link
+tickets with different constituencies. Changing the value on a ticket doesn't
+affect linked tickets. However, reasonable defaults are still used. For example
+when a user creates a new ticket from another one we select constituency of the
+existing ticket by default instead of using the default value from the config.
+
+=head3 reject
+
+This algorithm doesn't allow a user to link tickets with different Constituency
+values.
+
+Users cannot change the Constituency value when creating a new ticket from
+another one.
+
+When linking tickets together, the list of possible constituencies is restricted by
+the constituency of the former ticket, so the user may not choose targets with different
+constituencies.
+
+The Constituency value on an existing ticket can be changed only if
+the ticket is not linked to any other tickets.
+
+=head3 inherit
+
+This algorithm is something in between no and reject. Operations are not
+rejected; instead we prefer the value of a new incident when a user links tickets
+together.
+
+If the user uses New or Launch links on the main view of an incident,
+investigation, incident report or block to create a new linked ticket then
+the creation page contains a predefined value for Constituency and can't be
+changed at this point.
+
+The Constituency value can be changed on existing tickets, even if
+the ticket has other tickets linked to it. In this case, RTIR
+updates all related tickets during the update, so all continue to have
+the same value.
+
+Note that while linking tickets together, the list of possible candidates
+is not restricted by the constituency of the initial ticket, so a user may
+choose targets with different constituencies. In the latter case the incident's
+Constituency value is always preferred.
+
+=head3 Advanced Linking
+
+The Advanced tab allows you to do things that generic RTIR
+interfaces don't, so you can merge arbitrary tickets, move tickets between
+queues and, most important for constitiencies, it
+allows you to link tickets with different constituencies even if
+the propagation algorithm is set to 'reject'.
+
+Permissions (ACLs) are still applied to such operations, but administrators
+should note that by default links don't require bi-directional ACL checking.
+This means a user does not need the ModifyTicket right on the ticket they
+are linking to in order to set up a link. This behavior can be changed using
+the C<$StrictLinkACL> option in RT's configuration.
+
+=head2 Outgoing Mail: "CorrespondAddress" and "CommentAddress"
+
+If you create queues as described in L</Managing Constituency Values>,
+the queue correspondence and comment addresses will override
+the original queue's where possible.
+
+For example, if a user replies to an IR with constituency EDUNET and RTIR
+sends notifications, the correspond address of the 'Incident Reports - EDUNET'
+queue is used in notifications, if one is set. If the field
+is empty, the correspond address of the 'Incident Reports' queue is used
+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.  
+
+=head2 Presetting Constituency from Email
+
+Many mail transfer agents (MTAs) allow you to specify a flag on any incoming
+email message by appending "+flag" after an email address. This option
+is supported by postfix, sendmail, qmail, exim and others, though the "+" delimiter
+has different defaults on some systems and can be customized by a site's systems
+administrator.
+
+RTIR's multiple constituency support uses this extension mechanism to allow
+a single queue to receive mail for multiple constituencies. If you have two
+constituencies, EDUNET and GOVNET, you might set up RTIR's "incident report"
+address as follows in /etc/aliases:
+
+    edu: abuse+edunet
+    gov: abuse+govnet
+    abuse: "|/path/to/rt-mailgate ...mailgate options..."
+
+The rt-mailgate script expects the MTA to set the EXTENSION environment variable
+with a value of "flag." The script adds this value to the incoming message in
+the 'X-RT-Mail-Extension' header field. If an incoming mail has
+'X-RT-Mail-Extension: <valid constituency value>' header field then a new
+ticket is created with Constituency set accordingly.
+
+The Constituency field is mandatory so if the mail gate is not configured
+then the default value from the config is used.
+
+=head2 Access Control (ACLs)
+
+RTIR allows you to grant additional rights to tickets based on their
+constituency by means of "pseudo" queues ("Incidents - EDUNET" for
+the EDUNET constituency on the Incidents queue, for example).
+
+For example, assume you have two constituencies "EDUNET" and "GOVNET".
+Your RTIR instance consists of four queues: Incident Reports,
+Incidents, Investigations and Blocks. To grant the user Edward
+the right to work with EDUNET Incident Reports, you'll need to
+create a new queue, "Incident Reports - EDUNET". Make Edward an
+AdminCc of the new queue, either directly or as a member of a group
+like "DutyTeam EDUNET".
+
+You should grant that user or group the rights you want them to
+have to tickets in the "Incident Reports" queue. It is important
+that you I<not> grant the user or group "queue-wide" rights such as
+"See Queue" or "Create Ticket" in the pseudo-queue as the system
+will apply those rights to the pseudo-queue "Incident Reports -
+EUDNET" and I<not> to the "Incident Reports" queue.
+
+Note that templates, custom fields and scrips can still be applied to
+pseudo queues, but in the current implementation these objects have
+no effect on the RTIR behavior. This may be changed in the future.
+
+=head3 Constituency Specific Groups
+
+For each Constituency value, the RTIR admin can create a group
+'DutyTeam [constituency_value]' using either the web UI or the script.
+
+We've added some automation for such groups. Those groups
+are added as an AdminCc to a ticket according to value of the field
+and you can grant additional rights using this assignment. For example
+if you grant the 'TakeTicket' right to the AdminCc role on the IR queue
+then users that are members of the 'DutyTeam EDUNET' group will have
+this rights on all EDUNET tickets.
+
+Note that this method has some limitations and caveats. Users who
+have enough privileges still can add other users and groups as
+AdminCcs of a ticket and these principals will get the same set of
+additional rights that constituency-specific groups get via the AdminCc
+role. Since this uses the AdminCc role to grant constituency rights,
+you cannot use the role to grant one set of rights to group X and
+another set to group Y.
+
+Also, by default AdminCcs are notified on many ticket actions,
+so this feature can be a little bit noisy for members. You either
+can disable notifications of AdminCcs or disable this functionality.
+
+If you want to disable this functionality you just have to disable
+"SetConstituencyGroup" scrips in RTIR's queues. These scrips add or
+replace group in the AdminCc list when people set or change the ticket's
+constituency. If you still need more control over ACLs then you
+can use the pseudo-queues to add this control.
+
+=head3 DutyTeam Group vs. Constituency Specific Group
+
+By default DutyTeam has almost all rights on all RTIR's queues. This
+group's rights apply to tickets with all constituencies, so if you
+want to give access to group 'DutyTeam EDUNET' on EDUNET tickets only,
+then you don't want to make this group a member of DutyTeam.
+
+In RT/RTIR you cannot deny a right for a subgroup of a group if the
+parent group has it, so you should avoid adding groups into groups with higher
+privileges. We suggest leaving DutyTeam and constituency specific groups
+on the same level, however, you can join them using a new top level
+group.
+
+The same rules apply to user members of groups. Rights of all groups
+a user is a member of are summed up and if he is a member of DutyTeam with
+default of rights then he has more rights than any member of
+a constituency specific group (who is not member of other groups).
+Considering the above suggestion, a good way to manage users is to place
+each user in a constituency specific groups based on their access needs.
+Place users into DutyTeam only if they should work with all constituencies.
+
diff --git a/docs/DocIndex.pod b/docs/DocIndex.pod
new file mode 100644
index 0000000..5ff5011
--- /dev/null
+++ b/docs/DocIndex.pod
@@ -0,0 +1,166 @@
+=head1 RTIR Documentation Index
+
+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 
+documentation.  Other topics will be documented in
+the perl modules that comprise RTIR
+
+=head2 Email
+
+=head3 Create new IR via e-mail
+
+Mailgate help: rt/bin/rt-mailgate --help
+
+=head3 Reply from requestor on IR via e-mail
+
+Mailgate help: rt/bin/rt-mailgate --help
+
+=head3 Encrypting Mail with GnuPG
+
+See L<RT::Crypt::GnuPG> and L<AdministrationTutorial/GnuPG Encryption>
+
+=head3 Create new block via web-interface
+
+L<Tutorial/'Creating a Block'>
+
+=head2 Managing Incident Responses
+
+=head3 Merge IR
+
+L<Tutorial/Merging Tickets>
+
+=head3 Split IR
+
+L<Tutorial/'Splitting tickets'>
+
+=head3 Reject IR
+
+L<Tutorial/'Rejecting an IR'>
+
+=head3 Bulk Reject IR
+
+L<Tutorial/'Rejecting many IRs at once (bulk reject)'>
+
+=head3 Linking IRs to Incidents
+
+=over 4
+
+=item Link IR with new Incident
+
+=item Create new Incident from IR via 'Basics' section
+
+=item Link IR with existing Incident
+
+=back
+
+L<Tutorial/'Linking IRs to Incidents'>
+
+=head2 Reply Reporters Incident
+
+L<Tutorial/'Reply to Reporters'>
+
+=head2 Reply All Incident
+
+L<Tutorial/'Reply to All'>
+
+=head2 Link Incident with new IR
+
+L<Tutorial/'Linking Incidents to IRs, Investigations, etc.'>
+
+=head2 Link Incident with existing IR
+
+L<Tutorial/'Linking Incidents to IRs, Investigations, etc.'>
+
+=head2 Link Incident with new Block
+
+L<Tutorial/'Linking Incidents to IRs, Investigations, etc.'>
+
+=head2 Link Incident with existing Block
+
+L<Tutorial/'Linking Incidents to IRs, Investigations, etc.'>
+
+=head2 Resolve Incident
+
+L<Tutorial/Resolving an Incident>
+
+=head2 Resolve Incident & linked IR's and Investigations
+
+L<Tutorial/Resolving an Incident>
+
+=head2 Quick resolve Incident
+
+L<Tutorial/'Quick Resolve'>
+
+=head2 Abandon Incident
+
+L<Tutorial/'Abandoning Incidents'>
+
+=head3 Bulk Abandon Incidents
+
+L<Tutorial/'Abandoning Incidents', subsection 'Abandoning many Incidents at once (bulk abandon)'>
+
+=head2 Launch Investigation
+
+L<Tutorial/'Linking Incidents to IRs, Investigations, etc.'>
+
+=head2 Correspond with Correspondent
+
+L<Tutorial/'Correspond with Correspondent'>
+
+=head2 Remove Blocks
+
+L<Tutorial/Blocks>
+
+=head2 Activate Blocks
+
+L<Tutorial/Blocks>
+
+=head2 Split Blocks, Split Investigation, Split Incident
+
+L<Tutorial/'Merging Tickets'>
+
+=head2 Merge Blocks, Split Investigation, Split Incident
+
+L<Tutorial/'Merging Tickets'>
+
+=head2 These Actions are part of normal Ticket management in RT
+
+=over 4
+
+=item Create new IR via web-interface
+
+=item Create new Incident via web-interface
+
+=item Reopen Incident
+
+=item Comment Blocks via web-interface
+
+=item Steal Blocks
+
+=item Reply IR via web-interface
+
+=item Comment IR via web-interface
+
+=item Reply from correspondent on Investigation via e-mail
+
+=item Reply from correspondent on Blocks via e-mail
+
+=item Comment on Investigation via web-interface
+
+=item Resolve IR
+
+=item Reopen IR
+
+=item Update Incident via e-mail
+
+=item Comment Incident via web-interface
+
+=item Resolve Investigation
+
+=item Reopen Investigation
+
+=item Steal Investigation
+
+=back
+
diff --git a/docs/Tutorial.pod b/docs/Tutorial.pod
new file mode 100644
index 0000000..6bf3891
--- /dev/null
+++ b/docs/Tutorial.pod
@@ -0,0 +1,427 @@
+=head1 RTIR Tutorial
+
+=head2 Incident Response Workflow
+
+RTIR automatically creates four RT queues for tracking incidents: Incident
+Reports, Incidents, Investigations and Blocks.
+
+=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
+sets its due date according to SLA rules configured by your Administrator.
+New Incident Reports appear on the RTIR main page, ordered by due date.
+
+=head3 Incidents
+
+Once you've verified that a new Incident Report is valid, you can create a new
+Incident from it, or link the IR to an existing Incident. RTIR fills in
+relevant information from the Incident Report, so there's no need to
+cut-and-paste. If you receive multiple reports about the same issue, you can
+link all of these reports to the same parent Incident, to keep them together.
+
+=head3 Investigation
+
+From an existing Incident, you can launch an Investigation to an outside party,
+asking them to look into and/or fix a problem. Once again, relevant
+information from the Incident is filled in when you create the new
+Investigation, so there's no need to cut-and-paste.
+
+=head3 Blocks
+
+Blocks are used to track any blocks placed on the borders of the network. You
+can create them from an existing Incident. Some sites don't require blocks, so
+they may be disabled by your Administrator. Blocks have several states: pending
+activation, active, pending removal, removed. These states can be set from
+sub-menu items on ticket display pages.
+
+=head2 Operations with Tickets
+
+=head3 Creating Tickets
+
+=head4 Suppress Sending Emails
+
+When creating a ticket in RTIR, you can check the
+"Don't send any emails to correspondents" checkbox, which will
+suppress all outgoing emails to all correspondents. Note that
+this works only during creation, and users added later will receive
+emails as normal based on the system configuration.
+
+=head3 Merging Tickets
+
+If it turns out that two Incidents are actually the same
+(which can occur when, for example, dynamic IP addresses are
+involved), they may be merged. The merge operation effectively
+makes one ticket out of two, containing the data and
+correspondence of both. Only tickets within the same queue
+should be merged, with the notable exception of merging an
+Incident Report into an Investigation when a correspondent's
+reply accidentally could not be recognized as such and thus
+got misfiled as new Incident Report.
+
+You can find the Merge link on the ticket display page.
+The Merge page is split into two
+sections. The first one is a list of other children of the parent
+Incident(s) of the current ticket. It's empty if the ticket is
+not linked to any Incidents or if there is no candidate to
+merge into. By default this page contains only active tickets.
+
+The second box contains other tickets you can merge into.
+Tickets are grouped by queue, if it's possible to merge the
+ticket into a ticket in another queue. For example, you can
+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 
+target ticket's display page.
+
+When the merge page doesn't have the ticket you're looking for,
+you can click 'Refine' to adjust the search conditions before
+returning to the merge page by clicking the 'Merge' tab.
+
+After the merge, the IDs of both tickets point to the target
+ticket, so you can still use the old ticket's ID in the subject
+of replies, but RTIR will send new notifications with the ID of
+the merged into ticket.
+
+The merge operation B<can't be reversed> and should be used with
+caution.
+
+=head4 Technical Details
+
+The merge operation is pretty straight forward, everything that
+RT can merge from the source ticket is added to the target ticket.
+When only one value can be selected, RT prefers the value from
+the target ticket, so the result of the action depends on the
+direction of the merge: "merge ticket #1 into #2" is not the same
+as "merge ticket #2 into #1".
+
+When you merge ticket #1 into #2 some properties of ticket #1
+are joined with respective properties of ticket #2: TimeEstimated,
+TimeWorked, TimeLeft, Requestors, Cc and AdminCc and Links.
+Duplicated links or watchers will be condensed; if there
+were links between tickets #1 and #2 then RT will drop them.
+Other fields from ticket #1 are ignored, such as status, queue or
+custom fields of single value type.
+
+By default RTIR shows only active tickets as candidates for the
+merge, so you typically will not merge a ticket into one that's
+been resolved or rejected. However, you can use the Refine Search
+option to find an inactive ticket. If you do so, note that merging
+into a resolved ticket is not the same as explicitly resolving the
+ticket and RTIR will not send notifications or run other scrips.
+
+Users can merge tickets only if they have the right 'ModifyTicket'
+on both tickets.
+
+You can also access RT's standard merge from an RTIR ticket's
+'Advanced' tab. This option allows you to merge any ticket into
+any other, avoiding 'the same queue' and other RTIR restrictions.
+For example, you can merge an Investigation into an IR, or an IR
+into a ticket in non-RTIR queues. Access checks and permissions still
+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, 
+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.
+
+Split tickets can only be created in the same queue as the ticket they're
+split from.
+
+Note that the split action is implemented with the "create" function and if
+your RTIR is configured to notify requestors (correspondents) then email
+will be sent after the split. However you can use "Don't send any emails to
+correspondents" checkbox from the split page to avoid notifications.
+
+=head3 Rejecting an IR
+
+Rejecting means "we're not going to work on this report." There are several
+reasons to do this: the ticket is spam, problem wouldn't be solved, it's
+out of scope, etc. Rejected tickets are still available for
+searches and can be reopened, but RTIR's default interfaces are designed
+to hide such tickets, so people can concentrate on new and open tickets.
+
+When you click the Reject tab on the ticket display page you'll see
+the 'Reject Incident Report' page with a box for a message and other
+common input fields. You can write a message and choose whether it would be
+comment or response. By default correspondents don't receive comments.
+You submit the form and RTIR sets the status of the ticket, records the message
+and unlinks the IR from any Incidents.
+
+If you don't want to write any comment or change any properties of an IR
+when rejecting, you can submit the reject form immediately or
+use the Quick Reject tab and reject the current IR without even opening
+the reject form.
+
+=head4 Rejecting Many IRs at Once (Bulk Reject)
+
+On the RTIR home page at the top right corner of 'New unlinked Incident Reports'
+you'll find a Bulk Reject link, which allows you to reject many tickets
+at once. On the Bulk Reject page, you can check/uncheck all tickets displayed
+or you can select individual IRs. Click the Reject button to reject the selected
+tickets and remain on the Bulk Reject page or click Reject and Return to reject
+the selected tickets and return to the RTIR home page.
+
+A link to Bulk Reject is also available in the menu of searches
+for Incident Reports, so you can go to RTIR's Incident Reports menu,
+refine search conditions, and go to Bulk Reject from the search results
+page.
+
+Using this interface you might unknowingly reject IRs that have links
+to Incidents, so the search results on the Bulk Reject page have a
+'Has Incident?' column which indicates whether an IR is linked to an Incident.
+However this column is informative only and you still can reject IRs
+that are linked to an Incident.
+
+Using the Bulk Reject interface, you can reject IRs you own or that are
+unowned, but you can't reject IRs that are owned by someone else.
+IRs owned by others will be skipped with a warning even if you selected them.
+
+=head3 Abandoning Incidents
+
+This operation is quite similar to rejecting an IR, but when you're
+abandoning an Incident you also reject IRs, resolve Investigations and
+remove Blocks linked to it.
+
+Once you open the Abandon page under the Incidents tab you see a list of its
+children grouped by queue. You can select children with checkboxes and only
+children you've selected will be rejected, resolved or removed.
+
+The Incident's Resolution is set according to the C<%RTIR_CustomFieldsDefaults>
+config option. By default its value is "no resolution reached," however,
+you can choose any value you'd like to.
+
+You can write a message that will be added to the selected children as
+a comment or response according to value of the 'Update Type' field.
+
+When you submit the form, RTIR updates the selected tickets and then checks
+the state of the Incident's children to decide whether it's OK to abandon it
+or not. In the simplest case the Incident you're abandoning has children
+that aren't linked to any other open Incident. RTIR marks the Incident
+as abandoned if all children are inactive (resolved, rejected or removed)
+otherwise you see a notice "State of the Incident left unchanged; not
+all children were updated."
+
+RTIR supports IRs linked to many Incidents and in this case abandoning is
+a little bit trickier. When you're abandoning an Incident linked to an IR
+that is linked to another open Incident, RTIR doesn't reject the IR, but adds
+a comment to the IR noting that the Incident has been abandoned while
+this ticket is still linked to an open Incident and left unchanged. In this
+situation the original Incident is successfully abandoned.
+
+=head4 Abandoning Many Incidents at Once (Bulk Abandon)
+
+The Bulk Abandon subtab under the Incidents tab allows you to abandon
+multiple Incidents at once.
+
+=head3 Locking
+
+B<Note> that this functionality is available only when the
+L<RT::Extension::TicketLocking> extension is installed.
+
+An automatic lock is created whenever a user performs an action on a ticket that
+takes multiple steps (unless a hard lock is already in place for that ticket).
+The following actions produce an auto lock:
+
+    - Edit
+    - Split
+    - Merge
+    - Advanced
+    - Reply
+    - Resolve
+    - Reject
+    - Comment
+    - Remove
+
+Locks are advisory: if a ticket is locked by one user, other users
+will be given a notification (in red) that another user has locked
+the ticket, with the locking user's name and how long he has had
+it locked for, but they will still be allowed to edit and submit
+changes on the ticket.
+
+An auto lock is removed once the user is done with whatever he was doing
+on the page (e.g., when he clicks "Save Changes" on the Edit page).
+It is also removed if the Unlock link is clicked from a page that generated
+an auto lock.
+
+For more information, see L<RT::Extension::TicketLocking>.
+
+=head3 Correspondence
+
+=head4 Reply to Reporters
+
+This operation lets you send a message to all of the parties who created
+IRs. You may exclude individual recipients by removing the check next to
+their name.
+
+=head4 Reply to All
+
+This operation lets you send a message to all of the parties who created
+IRs, those involved in the Investigation, and those involved in the
+Blocks. You may exclude individual recipients by removing the check next
+to their name.
+
+=head4 Correspond with Correspondent
+
+This operation lets you send a message to the parties involved in an
+Investigation. This is available when you "Reply to All" on an Incident.
+
+=head3 Linking
+
+=head4 Linking IRs to Incidents
+
+When creating a new IR, you may enter the ID number of an Incident in the
+"Incident" field. This will create a link from the IR to the Incident.
+
+If you have an existing IR, you can link it to an Incident by clicking the
+"[Link]" button next to the "Incident" field. You may also create new Incidents
+and link them to the IR by clicking the "[New]" button next to the
+"Incident" field in the "The Basics" section of the IR display.
+
+=head4 Linking Incidents to IRs, Investigations, etc.
+
+You may link Incidents with existing Incident Reports, Investigations,
+Blocks, and Articles. On the Incident display page there are sections for
+each of these, each with a C<Link> button and the list of already-linked
+tickets. Clicking on C<Link> lets you link one or more tickets of that type to
+the Incident.
+
+Clicking on C<Create> (or in the case of Investigations, C<Launch>) lets you
+create a new ticket and link it to the Incident automatically.
+
+=head3 Resolution
+
+=head4 Resolving an Incident
+
+Once you open the Resolve page under the Incidents tab you see a list of its
+children grouped by queue and an update form. The children you select
+will be resolved with the incident.
+
+You can write a message that will be added to the selected children as
+a comment or response based on the value of the 'Update Type' field.
+
+When you try to resolve an Incident, RTIR checks the state of that
+Incident's children to decide whether it's OK to resolve it or not. In the
+simplest case, the Incident you're resolving has children that aren't linked to
+any other open Incident. RTIR marks the Incident as resolved if all children are
+inactive (resolved, rejected or removed) otherwise you see a notice "State of the
+Incident left unchanged; not all children were updated."
+
+=head4 Quick Resolve
+
+Incidents and IRs have a "Quick Resolve" feature which changes
+a ticket's status to 'resolved' immediately. No intermediate form is
+presented and you don't need to provide a message, note time worked,
+attach files, etc.
+
+=head3 Investigation
+
+=head4 Launching an Investigation
+
+To launch a new Investigation, create a new ticket in the Investigations queue.
+You will be required to provide one or more correspondents.
+
+=head3 Blocks
+
+=head4 Creating a Block
+
+To create a new Block, create a new ticket in the Blocks queue. You will be
+required to link the Block to an Incident.
+
+=head2 Managing 'RT at glance' and 'RTIR at a glance' Pages
+
+You can add, delete, or reorder portlets on the RT and RTIR at a glance
+pages using preferences. You can either click 'Edit' on the portlets
+or go to Logged in user -> Settings and then go to the section you want
+to customize.
+
+The default home pages are split into two columns, however you can leave
+one column empty if you need a wider one-column layout.
+
+=head3 Available Portlets
+
+=over 4
+
+=item QuickSearch
+
+Lists queues with the number of active tickets in them.
+Allows you to quickly jump to all active tickets in a queue or to tickets
+with a particular status.
+
+=item Other
+
+There are more portlets you can use with self-descriptive names.
+
+=back
+
+=head2 Custom Fields
+
+=head3 IP
+
+This custom field allow you to associate IPs or IP ranges with a ticket.
+You can enter information in several formats:
+
+* IP - single IP with decimal units separated by dot;
+
+* IP range - interval separated with C<->, for example C<192.168.20.0-192.168.20.255>,
+both ends of the interval are included in the range;
+
+* CIDR block - IP range in the CIDR format, for example C<172.16/24>, as you
+can see short form is also supported, RTIR converts ranges in this format
+to the IP range form.
+
+You can set the value of the custom field on create or later with an edit.
+You can enter several values at once, one per line, or comma-separated,
+or you can mix different formats. Values are validated for proper format when
+you submit and any errors are reported. When tickets are created, IPs and CIDR
+blocks are also parsed from the body of the message and added to the ticket.
+
+=head4 Searching by IP
+
+You can use the same input formats to search by IP, CIDR or range. On a query
+builder page you can use the IP field to enter an IP, range or CIDR
+and add the condition to the current query or return back to search results.
+You should see tickets that have at least one IP from the range. But you
+should note that validation of the input is not implemented in the query
+builder so you may enter invalid values. Double check the format if you
+don't see the tickets you expect in search results.
+
+=head2 Glossary
+
+=over 4
+
+=item active ticket
+
+An active ticket in RTIR is a ticket with a status that indicates work will
+still be done on it. RTIR uses this to determine what tickets should be shown
+by default in various searches and pages in the user interface.
+
+The available active statuses are defined as part of the
+RTIR configuration and differ for each queue (see C<%Lifecycles> in
+F<RTIR_Config.pm> and F<RT_Config.pm> for more information). Active tickets
+in the incidents queue, for example, are those with a status of C<open>. In
+the blocks queue, tickets can be C<active> or C<pending removal>. These values
+are configurable and may be different on your system.
+
+=item inactive ticket
+
+An inactive ticket in RTIR is a ticket with a status that indicates work on it
+is complete. RTIR uses this to filter tickets out of various searches and pages
+in the user interface, although the tickets can still be found with searches.
+
+Inactive statuses are defined as part of the
+RTIR configuration and differ for each queue (see C<%Lifecycles> in
+F<RTIR_Config.pm> and F<RT_Config.pm> for more information). Inactive tickets
+in the incidents queue, for example, can be C<resolved> or C<abandoned>. In
+the blocks queue, tickets can have a status of C<removed>. These values
+are configurable and may be different on your system.
+
+=back
+
+=cut
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.