[Rt-commit] rtir branch, 2.9/doc-updates, updated. 3.0.0rc1-19-gec2877e

Jim Brandt jbrandt at bestpractical.com
Thu Oct 4 12:39:37 EDT 2012


The branch, 2.9/doc-updates has been updated
       via  ec2877e8521678f8d210cfe646d4c2f433a68776 (commit)
       via  f0968372e6fac4f4c7f20e0c05fe69ce22aa2bb6 (commit)
      from  8c70aaa9caa321fdcc1fb01310b3ede611aa2efc (commit)

Summary of changes:
 lib/RT/IR/Constituencies.pod | 389 ++++++++++++++++++++++++-------------------
 lib/RT/IR/Tutorial.pod       | 297 +++++++++++++++++----------------
 2 files changed, 372 insertions(+), 314 deletions(-)

- Log -----------------------------------------------------------------
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 ec2877e8521678f8d210cfe646d4c2f433a68776
Author: Jim Brandt <jbrandt at bestpractical.com>
Date:   Thu Oct 4 11:48:32 2012 -0400

    Documentation updates for constituencies

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