[Rt-commit] rtir branch, 2.9/doc-updates, created. 3.0.0rc1-17-g8c70aaa
Jim Brandt
jbrandt at bestpractical.com
Mon Oct 1 14:39:39 EDT 2012
The branch, 2.9/doc-updates has been created
at 8c70aaa9caa321fdcc1fb01310b3ede611aa2efc (commit)
- Log -----------------------------------------------------------------
commit 1bbce14150e972cc71e3d3f777db6dcdad7a36b1
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Fri Sep 28 15:44:25 2012 -0400
README doc updates
General editing, no siginficant content changes.
diff --git a/README b/README
index ff744bb..795c4b8 100644
--- a/README
+++ b/README
@@ -3,18 +3,18 @@ incident-handling tool designed to provide a simple, effective
workflow for members of CERT and CSIRT teams. It allows team members
to track, respond to and deal with reported incidents and features a
number of tools to make common operations quick and easy. RTIR is
-built on top of "RT," which is also available for free from Best
+built on top of RT, which is also available for free from Best
Practical Solutions at http://www.bestpractical.com/rt/.
-To purchase commercials support, training or custom development for RT
-or RTIR, please contact Best Practical at sales at bestpractical.com.
-
+RT and RTIR are commercially-supported software. To purchase support,
+training, custom development, or professional services, please get in
+touch with us at <sales at bestpractical.com>.
REQUIRED PACKAGES:
------------------
-o RT 4.0.0 or later, configured, installed and tested.
+o RT 4.0.0 or later, configured, installed and tested.
o Net::Whois::RIPE 1.31 or OLDER, later versions broke
backwards compatibility
@@ -32,35 +32,44 @@ Installation instructions:
1) Install RT 4.0.0 or newer following RT's regular installation instructions
-3) Run "perl Makefile.PL" to generate a makefile for RTIR.
+2) Run "perl Makefile.PL" to generate a makefile for RTIR.
+
+3) Install any extra Perl modules RTIR needs that aren't already
+ installed. The output from the previous step will list new
+ modules needed, or if existing modules need to be upgraded to a
+ newer version.
-4) Install any extra Perl modules RTIR needs that aren't already
- installed.
+4) Type "make install".
-5) Type "make install".
+5a) If you are installing RTIR for the first time, initialize the RTIR
+ database by typing "make initdb".
-6) If you are installing RTIR for the first time, initialize the RTIR
- database by typing "make initdb".
+ WARNING: Do not attempt to re-initialize the database if you are
+ upgrading.
- WARNING: Do not attempt to re-initialize the database if you are
- upgrading.
+5b) If you are UPGRADING from a previous installation, read the
+ UPGRADING file for instructions on how to upgrade your
+ database.
-7) Activate RTIR extension in the RT config:
+6) Activate the RTIR extension in the RT_SiteConfig.pm file:
Set(@Plugins, 'RT::IR');
-8) Stop and start your web server.
+7) Stop and start your web server.
+
+
+Additional Extensions:
+----------------------
-9) To maintain Due date of Reports, Investigations and Blocks install
+o To maintain Due date for Reports, Investigations and Blocks, install
RT::Extension::SLA following the installation instructions in that
- extension's README files.
+ extension's README file.
-10) If you want to enable ticket/incident aging, install RT::Extension::TicketAging
- following the installation instructions in that extension's INSTALL and README
- files.
+o If you want to enable ticket/incident aging, install RT::Extension::TicketAging
+ following the instructions in that extension's INSTALL and README files.
-11) If you want to enable ticket locking, install RT::Extension::TicketLocking
- following the installation instructions in that extension's README file.
+o If you want to enable ticket locking, install RT::Extension::TicketLocking
+ following the installation instructions in that extension's README file.
Configuring RTIR
@@ -76,14 +85,12 @@ Configuring RTIR
RT -> Queues -> <Select RTIR's Queue> -> Templates.
RT -> Global -> Templates.
-
3) By default, RT ships with a number of global Scrips. You should use
RT's configuration interface to look through them, and disable any
that aren't apropriate in your environment.
RT -> Queues -> <Select RTIR's Queue> -> Scrips.
RT -> Global -> Scrips.
-
4) Add staff members who handle incidents to the DutyTeam group.
RT -> Configuration -> Groups -> DutyTeam -> Members.
@@ -94,20 +101,23 @@ Configuring RTIR
SETTING UP THE MAIL GATEWAY
---------------------------
-An alias for the Incident Reports queue will need to be made in either
+An alias for the Incident Reports queue will need to be made in either
your global mail aliases file (if you are using NIS) or locally on your
machine.
-
-Add the following lines to /etc/aliases (or your local equivalent) :
-rtir: "|/opt/rt3/bin/rt-mailgate --queue 'Incident Reports' --action correspond --url http://localhost/"
+Add the following lines to /etc/aliases (or your local equivalent):
+
+rtir: "|/opt/rt4/bin/rt-mailgate --queue 'Incident Reports' --action correspond --url http://localhost/"
You should substitute the URL for RT's web interface for "http://localhost/".
-** If you're configuring RTIR with support for multiple constituencies, please
-refer to the instructions in the file lib/RT/IR/Constituencies.pod
+o If your webserver uses SSL, rt-mailgate will require several new
+ Perl libraries. See the RT README for more details on this option.
+
+o See "perldoc /opt/rt4/bin/rt-mailgate" for more info about the rt-mailgate script.
-** Use "perldoc /opt/rt3/bin/rt-mailgate" to get more info about mailgate script.
+o If you're configuring RTIR with support for multiple constituencies, please
+ refer to the instructions in the file lib/RT/IR/Constituencies.pod
Documentation for RTIR
----------------------
commit e3643bf5ab8585104a6d6676f0891ca387e1f9f2
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Fri Sep 28 15:49:16 2012 -0400
Updates to UPGRADING doc
* general editing
* renumbering
* changing rt3 references to rt4
* more information about SLA upgrade
diff --git a/UPGRADING b/UPGRADING
index acca023..495923a 100644
--- a/UPGRADING
+++ b/UPGRADING
@@ -1,31 +1,38 @@
Upgrading from RTIR 1.2.0 or earlier
-------------------------------------
-* Best Practical Solutions will provide upgrade support to
+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) Make a backup of the database. It's very important.
+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) It's very recommended to use fresh directory for RT 4.0.
+1) Upgrade your RT installation to RT 4.0.3 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) Install and upgrade database to the RT 4.0.3 or newer following
- its upgrade instructions.
-
-2.1) Test how RT upgrade went. You should be able to start server,
- create tickets and do other things in the RT interface.
+2) 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.
-2.2) Make another backup of the DB, so you can return to this step
- if something goes wrong.
+3) Make another backup of the DB, so you can return to this step
+ if something goes wrong.
-3) Install the new version of RTIR. (DO NOT RUN "make initdb")
+4) Install the new version of RTIR. (DO NOT RUN "make initdb")
-4) Update RTIR's database.
+5) Update RTIR's database.
Type:
@@ -38,46 +45,54 @@ General upgrade instructions
Each step is described below and may have additional instructions.
Read them before running upgrade commands.
- For example if you had RTIR 1.1.1 then you should check
+ For example, if you had RTIR 1.1.1 then you should read the
instructions under "Applying changes from etc/upgrade/1.1.3"
- section below and run commands, then do the same with 1.9.0 dir
- and greater.
+ 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> dir
- then anyway *you must* read instructions below for all versions
- greater or equal to that you're upgrading from as some upgrades
+ *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.
+ 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.
- Commands you should run to upgrade DB using data
- from etc/upgrade/<version> directory: If the dir has any schema
- files then run:
+ If the upgrade directory has any schema files, run:
- /opt/rt3/sbin/rt-setup-database --dba <dba> \
+ /opt/rt4/sbin/rt-setup-database --dba <dba> \
--prompt-for-dba-password --action schema \
--datadir etc/upgrade/<version>
- If the dir has a file named 'content' then run:
+ If the upgrade directory has a file named 'content' then run:
- /opt/rt3/sbin/rt-setup-database --dba <dba> \
+ /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
- to backup before applying this script.
+ that you save a DB backup before applying this script.
-1) RT 4.0 introduces new feature, lifecycles, what allowed us to
- replace RTIR's four State custom fields with four RTIR
- specific lifecycles, delete these custom fields and use
+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 use of State custom field with Status, check
- templates, scrips' conditions and actions.
+ 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:
@@ -87,65 +102,66 @@ Upgrading from 2.6.x and earlier
$ticket->Status;
- Almost every format string in $RTIRSearchResultFormats option
- had '__CustomField.{State}__' that is replaced with __Status__.
- You should update config if you have customizations.
+ 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 regular expression is trvial and
- may skip some edge cases.
+ 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 configs.
+ Read more about lifecycles in RT's and RTIR's configuration
+ files.
-2) To keep history intact upgrade script turns changes of
+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. Backup is really
- required. Don't forget to re-analyze and optimize tables after
- upgrade.
+ tables with updates and deletes mostly. Again, it's important
+ to have a known good backup.
-3) Several scrip actions are not required anymore because of
- switch to lifecycles, so modules of these action and
+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, no need
- in RTIR_SetStartedToNow scrip action.
+ Started date is properly handled by lifecycles now, so the
+ RTIR_SetStartedToNow scrip action is no longer needed.
- IRs and Blocks still has some special status treatment, but
- it is handled by new scrips, so no need in
- RTIR_SetIncidentReportState and RTIR_SetBlockState actions.
+ 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) Situation with scrip conditions is similar to above with
- actions.
+4) Just as some scrip actions have been removed, several scrip
+ conditions also are no longer needed.
- RTIR_RequireStateChange condition gets deleted.
+ 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 StatusChange
- condition that is part of RT. See example in the upgrade script
+ 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) /RTIR/Elements/QueueSummary portlet deleted and replaced with
- RT's Quicksearch. Update config in case you have custom setting
- for RTIR_HomepageSettings. Users' preferences updated automatically.
+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 IP custom field has been merged
- into RT 4.0 and extended to support IPv6. Upgrade script
- changes type of the IP field.
+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 simple Service Level Agreements (SLA) implementation.
- RT::Extension::SLA was prototyped on it, but heavily improved.
+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. SLA custom field stays as extension uses it as well.
- However, dependency on the extension is not mandatory and there is
- no default config for it. Read tutorial for administrators for
- more info.
+ the 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:
@@ -168,14 +184,23 @@ Upgrading from 2.6.x and earlier
$SLA_Reopen_OutOfHours
SLA key in %RTIR_CustomFieldsDefaults
-8) New format strings in $RTIRSearchResultFormats: ListIncidents
- and LookupTool.
+ 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. What
- means that you have to update custom code you have: templates,
+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.
@@ -187,34 +212,35 @@ Upgrading from 2.4.x and earlier
WhereBlocked => Where Blocked
All these changes are implemented in F<etc/upgrade/2.5.1/content>
- file.
-2) Saved searches are affected by above change and you can convert
+2) Saved searches are affected by the above change and you can convert
them using a script provided.
- perl -I /opt/rt3/local/lib -I/opt/rt3/lib etc/upgrade/2.5.1/update_saved_searches.pl
+ perl -I /opt/rt4/local/lib -I/opt/rt4/lib etc/upgrade/2.5.1/update_saved_searches.pl
-3) Some templates RTIR comes with contain code to insert values of
+3) Some standard RTIR templates contain code to insert values of
CFs into emails. It is impossible to change these templates
- automatically. You have to do it manually. To identify templates
+ 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 simple as deleting _RTIR_ prefix and adding
- a space to three names mentioned above.
+ 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 old names. Make sure to change
- that. The following command might help you identify places:
+ 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 has been merged together
- into RTIR_CustomFieldDefaults hash. Change site config accordingly.
+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:
@@ -226,14 +252,14 @@ And replace it with:
[{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]
Upgrading from 2.3.17 and earlier
--------------------------
+---------------------------------
1) Layout of files in RT's directories have been changed in RT 3.8.0.
Each extension is installed in its own directory and is activated
using @Plugins options in the RT config.
2) By accident RTFM's CustomField Response could be created with MaxValues = 0
- what is incorrect and should be changed to 1, run the following query to
+ which is incorrect and should be changed to 1. Run the following query to
update the DB.
UPDATE CustomFields SET MaxValues = 1 WHERE
@@ -243,76 +269,76 @@ Upgrading from 2.3.17 and earlier
AND MaxValues = 0;
Upgrading from 2.3.15 and earlier
--------------------------
+---------------------------------
There was an error in the etc/upgrade/upgrade.pl script. It could skip
some incidents during upgrade. Run this script again, especially if you
-never did that or ran with earlier versions of the RTIR. This script
-updates Due dates on active incidents where it's not set and set to
+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 these step no special actions are required, run the upgrade scripts where we
+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 these step no special actions are required, run the upgrade
+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 these step no special actions are required, run the upgrade
+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.
+ 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.
+ and add several scrips to track values of the field.
Applying changes from upgrade/1.9.0
--------------------------
+-----------------------------------
1) The LaunchMessage template in the Investigations queue
-has been renamed into Autoreply without any changes of the content.
-This upgrade step is automated, but may fail if you've changed
-the LaunchMessage template.
+ 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
-replacement for the NewMessage template. Automated step doesn't delete
-old template, you have to check that the new template suites your
-needs and may be copy customizations from the old one, then delete
-the NewMessage template.
+ 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 global one is disabled or doesn't exist.
-You need the following scrip in the queues:
+ 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
+ On Create AutoReply to Requestors with Template Autoreply
4) The new 'BlockRemoved' template has been added in the Blocks
-queue. Check its content.
+ queue. Check its content.
Applying changes from upgrade/1.1.3
--------------------------
+-----------------------------------
-No special steps required, just run upgrade scripts. Everything
+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
@@ -323,7 +349,7 @@ Applying changes from upgrade/1.1.1
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
@@ -335,9 +361,8 @@ 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
+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.
-
commit 8c70aaa9caa321fdcc1fb01310b3ede611aa2efc
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Fri Sep 28 15:57:52 2012 -0400
Documentation updates to admin tutorial
diff --git a/lib/RT/IR/AdministrationTutorial.pod b/lib/RT/IR/AdministrationTutorial.pod
index beb2c90..df19d82 100644
--- a/lib/RT/IR/AdministrationTutorial.pod
+++ b/lib/RT/IR/AdministrationTutorial.pod
@@ -1,8 +1,23 @@
=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 by putting the following into your RTIR config:
+You may disable the Blocks queue by putting the following into your
+RT_SiteConfig.pm config:
Set($RTIR_DisableBlocksQueue, 1);
@@ -11,12 +26,15 @@ You may disable the Blocks by putting the following into your RTIR config:
The various states an incident, IR, investigation, or block can be in, such as
'open', 'stalled', 'abandoned', etc.
-This field represent custom status of tickets and values are different in
-different queues. Controlled with C<%Lifecycles> option in the config.
-Critical field for functionality.
+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.
-Read description in the F<RTIR_Config.pm> and description of L</Scrips>
-below.
+For more information, read the description in F<RTIR_Config.pm> and description
+of L</Scrips> below.
=head2 Custom Fields
@@ -33,72 +51,72 @@ 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. If you don't need this
-feature then name custom field differently.
+if you want to use this functionality.
=item Description
-Short description of an Incident
+Short description of an Incident.
=item Resolution
-How an Incident was or wasn't resolved
+How an Incident was or wasn't resolved.
=item Function
-Who is handling the Incident
+Who is handling the Incident.
=item Classification
-The type of Incident, such as system compromise or denial of service
+The type of Incident, such as system compromise or denial of service.
-=item HowReported
+=item How Reported
-How the IR got into RTIR
+How the IR got into RTIR.
=item ReporterType
-Who reported the IR, such as the police or another ISP
+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 loose all magic. It's
-possible to change this CF from multiple values to single value.
+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.
-End user documentation is in L<Tutorial/'IP'>.
+See L<Tutorial/'IP'> for more information.
See also L</SetIPFromContent> below.
=item Netmask
-Network mask for a Block
+Network mask for a Block.
=item Port
-Port for a Block
+Port for a Block.
-=item WhereBlocked
+=item Where Blocked
-Where the block is placed
+Where the block is placed.
=item Customer
-Customer for an IR or Investigation
+Customer for an IR or Investigation.
=back
-=head2 Managing "RT at Glance" and "RTIR home" pages
+=head2 Managing "RT at a glance" and "RTIR at a glance" pages
-In the config you can set @RTIR_HomepageComponents option to control
+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. Read more about different portlets in L<Tutorial>.
+RTIR. See L<Tutorial> for more information.
=head2 Notifications
-Almost all email notifications in RT/RTIR are constrolled via scrips.
+Almost all email notifications in RT/RTIR are controlled via scrips.
There are three default base actions you can use to notify users:
@@ -106,130 +124,142 @@ There are three default base actions you can use to notify users:
=item Notify
-Sends a notification to users, reply-to field will be set
-according to correspond address. As well, NotifyActor option
-influence set of recipients.
+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 reply-to field is set according to
-comment address.
+Similar to 'Notify', but the reply-to field is set based on
+the comment address.
=item Autoreply
-Is a variation of 'Notify' action which sends email even if NotifyActor
-option is disabled.
+A variation of the 'Notify' action which sends email even if the
+NotifyActor option is disabled.
=back
-Above actions have multiple variants with different list of recipients,
-for example 'Notify Owner' or 'Notify Requestors'. List of recipients
+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 ticket's
+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 combination of values like 'Owner, Ccs, AdminCcs'.
+The list can be a combination of values like 'Owner, Ccs, AdminCcs'.
-Here is several examples:
+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 queue's template
-can override global one. For example you can create template 'Correspondence'
-in a queue and all notifications (global or queue specific) will be using
-this template instead of global.
+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, set the HowReported Custom Field to a default
-value of Email if it wasn't otherwise specified.
+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 status of blocks according to a few rules
+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'.
-As well, take a look at C<$RTIR_BlockAproveActionRegexp> option
+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,
+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 IR is not linked. When an IR is
+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 what RT's AutoOpen checks and scrip behaves in
+checks everything that RT's AutoOpen checks and the scrip behaves in
the same way.
=item Set Due Date On Incident
-Keeps Due date of incidents in sync with the most due child.
+Keeps the Due date of incidents in sync with the most due child.
See L</Service Level Agreements> below for details on automating
-Due dates and L<RT::Action::RTIR_SetDueIncident> for details
+Due dates, and L<RT::Action::RTIR_SetDueIncident> for details
about action of the scrip.
=item ResolveAllChildren
-Applies to the IncidentsQueue.
-If the Status of an Incident is changes to an Inactive Status,
-looks for linked Tickets in the Incident Report, Investigation or Blocks
-Queues and Resolves them. If any of these linked Tickets are linked
-to other ongoing Incidents, a comment is left and they are left unresolved.
+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
+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
+
+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 is marked as Open.
+
+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 Incident 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 removed. If it is changed from an Active Status to an Inactive Status
-and the Resolution Custom Field wasn't set manually, it is set
-to the value according %RTIR_CustomFieldsDefaults in your
+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
+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 IP and IP Ranges
+
+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
@@ -240,21 +270,23 @@ 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 checking the parent Ticket, the
+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
+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.
+
+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
@@ -292,9 +324,11 @@ 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
+RT. This extension can remove data such as users or tickets
from the RT/RTIR system. You can find documentation for this
-extension in in L<RT::Shredder> by running `perldoc lib/RT/Shredder.pm`
+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.
@@ -302,14 +336,14 @@ 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 RT_SiteConfig.pm.
+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 still be processed, but there will be "This message is
+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.
@@ -334,21 +368,21 @@ 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
-was mis-set in RTIR_SiteConfig.pm. Note that you can use either GPG Agent or
+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)
-RTIR used to have simple Service Level Agreements (SLA) implementation.
-L<RT::Extension::SLA> was prototyped on it, but heavily improved. In RTIR 3.0
-we got rid of SLA implementation in the core of RTIR that was in conflict
+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.
+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
-----------------------------------------------------------------------
More information about the Rt-commit
mailing list