[Rt-commit] rtir branch, 2.9/doc-updates, created. 3.0.0rc1-19-gf3d3855
Jim Brandt
jbrandt at bestpractical.com
Thu Oct 4 13:10:43 EDT 2012
The branch, 2.9/doc-updates has been created
at f3d38552ce60a6b3a9e8f64ed62cf6a678572f61 (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
commit f0968372e6fac4f4c7f20e0c05fe69ce22aa2bb6
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Wed Oct 3 16:17:11 2012 -0400
Documentation updates for tutorial
diff --git a/lib/RT/IR/Tutorial.pod b/lib/RT/IR/Tutorial.pod
index 0b89194..6bf3891 100644
--- a/lib/RT/IR/Tutorial.pod
+++ b/lib/RT/IR/Tutorial.pod
@@ -23,34 +23,34 @@ 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 the problem. Once again, relevant
+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 the blocks placed on the borders of the network. You
+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
+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
+=head2 Operations with Tickets
-=head3 Creating tickets
+=head3 Creating Tickets
-=head4 Suppress sending emails
+=head4 Suppress Sending Emails
-During creating of a ticket in RTIR, user may check box next to
-"Don't send any emails to correspondents" phrase, this will
+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 later user will recieve other
-emails according to configuration of notifications.
+this works only during creation, and users added later will receive
+emails as normal based on the system configuration.
-=head3 Merging tickets
+=head3 Merging Tickets
If it turns out that two Incidents are actually the same
-(which can occur when, e.g., dynamic IP addresses are
+(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
@@ -59,25 +59,22 @@ 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.
-When a user opens a ticket's display page there is a 'Merge'
-option in the page's tabs. The Merge page is split into two
-blocks. The first one is a list of other children of the parent
+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 a user
-merges an IR into an Investigation then Investigation is always
-used as the target ticket.
+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.
-You have to select one ticket from the list and submit the form.
If the merge completes successfully, you'll be redirected to the
-target ticket's main page. The action may fail because of lack of
-permissions or a system error, in this case you'll see an error
-message, consult to your system administrator.
+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
@@ -85,15 +82,13 @@ 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 an ID of
+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
-
-There are some technical details users may be interested in.
+=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.
@@ -104,89 +99,89 @@ 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, also if there
+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 have no way
-to merge a ticket into one that's been resolved or rejected,
-but you should note that merging into a resolved ticket (you can
-change search conditions via refine tab) is not the same as
-resolving ticket and RTIR will not send notifications in this case.
+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, also, can access RT's generic merge from an RTIR ticket's
-'Advanced' tab. This option allows user to merge any ticket into
-any avoiding 'the same queue' and other restrictions RTIR has.
-For example you can merge an Investigation into an IR, or an IR
-into a ticket in non RTIR's queues. ACL checks still apply.
-In the normal course of work, this operation should be avoided.
+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
+=head3 Splitting Tickets
-The Split operation allows user to create a new ticket from an existing one.
-When a user selects the 'Split' tab he will see a new ticket creation form
+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. The user can change any and all
+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 tickets can only be created in the same queue as the ticket they're
split from.
-Note that the split action is implemented over "create" function and if
-your RTIR is configured to notify requestors (correspondents) then mail(s)
-would be send after split. However you can use "Don't send any emails to
+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 the ticket". There are several
+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 or something else. Rejected tickets are still available for
+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 open a ticket's display page there is a 'Reject' tab. You click
-it and see 'reject Incident Report' page with a box for message and other
+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 status of the ticket, records the message
-and unlink the IR from any Incidents.
+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
-during reject action then you can submit the reject form immediately or
-use 'Quick Reject' tab and reject the current IR without even opening
+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)
+=head4 Rejecting Many IRs at Once (Bulk Reject)
On the RTIR home page at the top right corner of 'New unlinked Incident Reports'
-box you can see 'Reject' link. Following that link you can open interface
-for rejecting many tickets at once. The interface has a buttons to
-check/uncheck all tickets on the page or you can select particular IRs
-with checkboxes. To reject tickets you submit the form with 'reject' or
-'reject and return' buttons, by clicking the former one you stay on the
-'bulk reject' page, while the latter one returns you to the RTIR home page
-where you could continue your work.
-
-As well, link to 'Bulk Reject' operation exist in the page menu of searches
-for 'Incident Reports', so you can go to RTIR's 'Incident Reports' menu,
-refine search conditions if you like to, and from the page with results go to
-'Bulk Reject' operation.
-
-Using this interface you can reject IRs that have links to Incident(s) what
-may be undesired, so search results on 'Bulk Reject' page have column
-'Has Incident?' which indicates wether a IR linked to Incident or not.
-However this column is only informative and you still can reject IRs
+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.
-Note that you can't reject IRs that are owned by somebody else (you can,
-however, reject unowned IRs) with the bulk reject interface. IRs owned by
-others will be skipped with a warning even if you selected them.
+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
@@ -195,41 +190,40 @@ 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, only
+children grouped by queue. You can select children with checkboxes and only
children you've selected will be rejected, resolved or removed.
-Resolution of the Incident is set according to C<%RTIR_CustomFieldsDefaults>
-config option and by default its value is "no resolution reached", however,
+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 that will be added to the selected children as
-a comment or response according to value of 'Update Type' field.
+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.
-Once user submit the form RTIR updates selected tickets and then checks
-state of children of the Incident to decide whether it's OK to abandon it
+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 another open Incident, RTIR marks the Incident
-as abandoned if all children are closed(resolved, rejected or removed)
+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". The latter case may happen when the user's
-selected not all children.
+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 IR, but adds
-a comment to the IR telling that the Incident has been abandoned while
-this ticket is still linked to open Incident and left unchanged. In such
-situation the Incident is abandoned.
+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)
+=head4 Abandoning Many Incidents at Once (Bulk Abandon)
-Use a bulk abandon subtab under the Incidents tab to abandon multiple
-Incidents at once.
+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 L<RT::Extension::TicketLocking>
-extension is installed.
+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).
@@ -287,7 +281,7 @@ When creating a new IR, you may enter the ID number of an Incident in the
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 linking them to this IR by clicking the "[New]" button next to the
+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.
@@ -299,38 +293,38 @@ 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 tickets and link it to the Incident automatically.
+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 common update form. You can select children
-with checkboxes. Only children you've selected will be resolved.
+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 according to value of 'Update Type' field.
+a comment or response based on the value of the 'Update Type' field.
-Once a user tries to resolve an Incident, RTIR checks the state of that
+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
-another open Incident, RTIR marks the Incident as resolved if all children are
-closed(resolved, rejected or removed) otherwise you see a notice "State of the
-Incident left unchanged; not all children were updated". The latter case may
-happen when the user's selected not all children.
+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. Clicking Quick Resolve will
-change a ticket's status to 'resolved' immediately. You won't be asked to
-fill in a message or time worked, attach files, and so on.
+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 Investigatin, create a new ticket in the Investigation queue.
+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
@@ -340,32 +334,33 @@ You will be required to provide one or more correspondents.
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 home' pages
+=head2 Managing 'RT at glance' and 'RTIR at a glance' Pages
-You can add/delete or reorder portlets on those pages using preferences.
-Either you can click 'Edit' link or Preferences and then goto subtab
-you're interested in.
+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.
-Page is splitted into two columns, however you can leave one column empty
-if you need wider one-column layout.
+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
+=head3 Available Portlets
=over 4
=item QuickSearch
-Lists queues with summary on numbers of active tickets in those.
+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 particular status.
+with a particular status.
=item Other
-There are more portlets you use which names are quite self-descriptive.
+There are more portlets you can use with self-descriptive names.
=back
-=head2 Custom fields
+=head2 Custom Fields
=head3 IP
@@ -375,27 +370,27 @@ 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 range;
+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 IP-IP form.
+to the IP range form.
-You can set value of the custom field on create or later through edit page of a
-ticket. You can enter several values at once, one per line or comma-separated,
-as well you could mix different formats. Create or update action fail if you
-enter incorrect values with an error message, you should fix the problem and
-resubmit the form. On creation, IPs and CIDR blocks are also parsed from the
-body of the message and added to the ticket.
+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 see input box for IP condition, enter an IP, range or CIDR
-and add the condition to the current query, return back to search results.
+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 and you may enter incorrect value, be careful.
+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
@@ -403,13 +398,29 @@ builder and you may enter incorrect value, be careful.
=item active ticket
-Within RTIR a ticket is C<active> if its state is C<new>, C<open>, C<pending
-activation>, C<active> or C<pending removal>. See also C<inactive 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
-Within RTIR a ticket is C<inactive> if its state is C<resolved>, C<rejected>,
-C<abandoned> or C<removed>. See also C<active 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
commit f3d38552ce60a6b3a9e8f64ed62cf6a678572f61
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Thu Oct 4 11:48:32 2012 -0400
Documentation updates for constituencies
diff --git a/etc/RTIR_Config.pm b/etc/RTIR_Config.pm
index 8501bb4..e68f700 100644
--- a/etc/RTIR_Config.pm
+++ b/etc/RTIR_Config.pm
@@ -531,8 +531,9 @@ Set(
Set constituency propagation algorithm. Valid values are 'no',
'inherit' and 'reject', by default 'no' propagation happens.
-Read more about constituencies in F<lib/RT/IR/Constituency.pod>.
-Algorithms are described in 'Changing the value' chapter.
+Read more about constituencies in F<lib/RT/IR/Constituencies.pod>.
+Algorithms are described in
+L<Constituencies/"Constituency Propagation Options">.
=cut
diff --git a/lib/RT/IR/Constituencies.pod b/lib/RT/IR/Constituencies.pod
index c82acb9..9600d8a 100644
--- a/lib/RT/IR/Constituencies.pod
+++ b/lib/RT/IR/Constituencies.pod
@@ -1,221 +1,267 @@
-=head1 REQUIREMENTS for Multiple Constituency functionality
-
-Demand exists to provide services for more than one constituency.
-For a variety of reasons, it makes sense to separate these
-constituencies, particularly when handling incidents. However,
-it also makes sense to use the same tools when
+=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
+constituency, different users may wish to work on incidents within
different queues or have access to incident data held within different
-queues. Therefore, access is required, which allows user privileges
-depending on the constituency. RTIR does not support this out of
-the box. Of course it would be possible to install one separate
-instance of RTIR per constituency. But this is somewhat cumbersome,
-as a lot of the configuration is identical on all instances, hence
-error-prone. A better solution would be to integrate the facility
-of handling several constituencies within the same instances of
-RTIR.
+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:
- * It's name.
- * Its correspondence email address.
- * Associated ACLs.
- * Assigning a constituency to a ticket:
- ** On new incoming incident report, the constituency is preset
- automatically according the email address the email is sent to.
- ** Any new incidents created from incident reports, or blocks and
- investigations, created from incidents inherit the constituency
- from the launching ticket.
- ** Manually assign the constituency to any new tickets created from
- within RTIR, not yet related to any other ticket.
- ** Manually change the constituency of a ticket and all its related
- tickets.
+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
+=head1 Implementation Details
=head2 Mandatory
-The constituency field is a mandatory field, so users must select value for
-the field during creation of tickets in RTIR's queues.
+The constituency field is a mandatory field, so users must select a value
+when creating RTIR tickets.
-=head2 Constituency values
+=head2 Constituency Values
-Constituency is a custom field that applies to all RTIR's queues. Administrator
-can manage the field and its values via the web interface: RT -> Configuration ->
-Custom Fields -> click on 'Constituency' record in the list. At the bottom
-of the page there is control elements to add, delete and rename values of
-the constituency field.
+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. We'll describe steps below, but as well admins may use the
-F<add_constituency> script in the etc directory which helps add and new constituency
-values, along with their associated groups and queues.
+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
+=head2 Managing Constituency Values
-In some simple configurations,administrators may use the web interface
-to add/delete or rename values to the 'Constituency' field, however
+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. To simplify this task you can used the F<add_constituency>
-script. You can find it in the etc directory of RTIR's distribution.
-This script adds new values to the field and creates several objects
-in the system if those don't exist. It also grants basic constituency
-rights.
+value.
-For example the following objects affect the rights users can have to the constituency 'EDUNET':
+For example the following objects affect the rights users can have to
+the constituency 'EDUNET':
-=over 4
+=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 as sources of LIMITED information for
-per-constituency information for tickets in the master queue. You
-can set constituency base correspond and comment addresses. You'll
-find more details about that later.
+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.
-Read more about granting rights using special queues and groups below in
-the ACL section.
+See L</"Access Control (ACLs)"> below for more about granting rights using
+special queues and groups.
-=head2 Value propagation algorithms
+=head2 Constituency Propagation
-An administrator can use the C<$_RTIR_Constituency_Propagation> config option to
-choose RTIR's behaviour on constituency inheritance between linked tickets.
-There are three algorithms at the moment: 'no', 'inherit' and 'reject'.
-These algorithms are defined in L</Changing the value>
+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 we start discussing algorithms in depth let's look at the primary ways of
-setting and changing value of the 'Constituency' field:
+Before discussing constituency propagation in depth let's look at
+the primary ways of setting and changing the Constituency field.
-=over 4
+=over
-=item Creating a new ticket without links.
+=item Creating a new ticket without links
-The simplest case. User creates a new ticket and there is no reference to
-another ticket which already exists in the system. For example user creates
-an IR using the Web UI by clicking RTIR -> Incident Reports -> New Report,
-fills in values, leaves the Incident input blank. In this case default value
-from the config is used, however user can change constituency.
+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.
-A similar situation happens when ticket is created using the email interface.
-Find out more about that in the 'Presetting constituency according to mail
-traffic' section below.
-
-=item Creating a new ticket with a link.
+=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 user is looking at a creation
-page we already know all information about the ticket he's creating a new
-one from, so we select default constituency value based on the ticket the user
-is going to link to. This is one of situations where the option plays
-its role. Depending on the configuration, we can allow user to change
-constituency of the new ticket or not.
+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
-There is another scenario you should be aware of: when user is creating
-a ticket he can enter the ID of an Incident into an input field. In this case
-we don't know anything about the incident beforehand and operation may
-be interrupted later on - at the form submit.
+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 Changing the value
+=item Updating an existing ticket
-Changing constituency of a ticket can affect linked tickets as well.
+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
-The three propagation algorithms:
+=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 of a ticket doesn't
-affect linked tickets. However, reasonable defaults are suggested. For example
+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
-latter ticket by default instead of using the default value from the config.
+existing ticket by default instead of using the default value from the config.
=head3 reject
-This algorithm doesn't allow user to link tickets with different values of
-the 'constituency' field.
+This algorithm doesn't allow a user to link tickets with different Constituency
+values.
-Users can not change the 'constituency' field's value when create a new ticket from another one.
+Users cannot change the Constituency value when creating a new ticket from
+another one.
-During linking tickets together, the list of possible candidates is restricted by
-constituency of the former ticket, so user may not choose targets with different
+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.
-Changing constituency value through the 'Edit' page is possible ONLY if
+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 of the above two. Operations are not
-rejected, instead we prefer the value of a new incident when user links tickets
+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 new linked ticket then
-the creation page contains a predefined value for constituency and can't be
+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.
-Changing constituency value is possible through the 'Edit' page. RTIR
-updates all related tickets during this action, so all continue to have
+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.
+Constituency value is always preferred.
-=head3 Linking tickets using the 'Advanced' tab
+=head3 Advanced Linking
-The Advanced tab RTIR has allows people to do things that generic RTIR
-interfaces don't, so you can merge random tickets, move tickets between
-queues and what is B<most important> in regards to constitiencies it
-allows users to link tickets with different constituencies even if
-propagation algorithm is 'reject'.
+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'.
-ALCs are still applied to such operations, but administrators should
-remember that by default links don't require bi-directional ACL checking.
-This behavior can be changed using $StrictLinkACL option in the RT's
-config.
+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"
+=head2 Outgoing Mail: "CorrespondAddress" and "CommentAddress"
-If you create queues as described in the L</Managing constituency values>
-section, their correspondence and comment addresses will override
+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 an user replies to an IR with constituency EDUNET and RTIR
-sends notifications then correspond address of 'Incident Reports - EDUNET'
-queue is used in notifications, but only if it's not empty. If the field
-is empty then correspond address of 'Incident Reports' queue is used
-unless it's empty too. The last resort is $CorrespondAddress in the RT's
-config file.
+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
+It is important to note that these additional rights do not also
add new mailing rules.
-=head2 Presetting constituency according to mail traffic
+=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
+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)
+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
@@ -226,87 +272,88 @@ address as follows in /etc/aliases:
gov: abuse+govnet
abuse: "|/path/to/rt-mailgate ...mailgate options..."
-The rt-mailgate script expect that MTA sets the EXTENSION environment variable
-with value of "flag". The script adds this value to the incoming message in
-the 'X-RT-Mail-Extension' header's field. If an incoming mail has
-'X-RT-Mail-Extension: <valid constituency value>' header field then new
-ticket is created and constituency set according to field value.
+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
+The Constituency field is mandatory so if the mail gate is not configured
then the default value from the config is used.
-=head2 ACLs
+=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.)
+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"
+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
+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 NOT grant the user or group "queue-wide" rights such as
+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 NOT to the "Incident Reports" queue.
+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
+=head3 Constituency Specific Groups
-For each constituency value admin can create a group
-'DutyTeam constituency_value' using either the web UI or the script.
+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 a little bit automation for such groups. Those groups
-are added as AdminCc to a ticket according to value of the field.
-And you can grant additional rights using this fact. For example
-if you grant 'TakeTicket' right to AdminCc role of IR queue
-then users that are members of 'DutyTeam EDUNET' group will have
+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
-has enough privileges still can add other users and groups as
+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 constituency specific group get via AdminCc role.
-As you use AdminCc role only then you can not use it to grant one
-set of rights to group X and another set to group Y.
+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.
-As well, by default AdminCcs are notified on many actions that happens
-with tickets, so this feature can be a little bit noisy. You either
+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 ticket's
+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 reach the same and much more.
+can use the pseudo-queues to add this control.
-=head3 DutyTeam group vs. constituency specific group
+=head3 DutyTeam Group vs. Constituency Specific Group
-By default DutyTeam has almost all rights on all RTIR's queues, rights
-this group has applies to tickets with all constituencies, so if you
-want to give access to group 'DutyTeam EDUNET' on EDUNET tickets only
-then it's not good idea make this group member of DutyTeam.
+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 can not deny right for a subgroup of a group if the latter
-has it, so you should avoid adding groups into groups with higher
-privileges. We suggest leave DutyTeam and constituency specific group
+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 applies to user members of groups. Rights of all groups
-a user is member of are summed up and if he is member of DutyTeam with
+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
-constituency specific group (who is not member of other groups).
-Considering above suggestion a good way to deal with users is to place
-each user into constituency specific groups user should have access to
-and place her into DutyTeam only if he should work with all constituencies.
+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.
-----------------------------------------------------------------------
More information about the Rt-commit
mailing list