- Multiple Constituency Functionality
- Implementation Details
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 government institutions. You may have different contact mechanisms for members of these groups including different email addresses for reporting incidents. For a variety of reasons, it makes sense to identify and separately track interactions with these individual constituencies, particularly when handling incidents.
However, it also makes sense to use the same tools when working on these separate sources of data. Depending on the constituency, different users may wish to work on incidents within different queues or have access to incident data held within different queues. Members on the education response team may not have privileges to see information on government incidents, so you need to be able to assign user privileges depending on the constituency.
With some additional configuration, RTIR provides a flexible system that supports setting up multiple constituencies with different incident handling and access rules. These configurations all run in a single RTIR instance with shared workflows and global configuration that applies to all constituencies. This guide will help you configure RTIR to manage multiple constituencies.
The implementation of the constituencies feature was updated in RTIR 4.0 and is described here. If you were using this functionality in previous versions, you can read about specific changes in UPGRADING-4.0.
A constituency is defined by:
Its name, as defined in the RTIR Constituency custom field on the queue configuration page.
Its correspondence email address.
Its queues--typically a set with one each of Incident Reports, Incidents, Investigations, and Countermeasures--each with the same RTIR Constituency value defined.
Associated ACLs (rights and permissions for queues, tickets, etc.)
A ticket is assigned a constituency in a few different ways:
On a new incoming incident report, the constituency set automatically based on the incoming email address (the correspond address) and the associated queue in which it creates tickets.
Any new incidents created from incident reports, or countermeasures and investigations created from incidents, inherit the constituency from the launching ticket.
You can manually select the constituency to any new tickets created in the RTIR web interface by selecting the RTIR queue associated with a given constituency.
You can manually change the constituency of an incident and all its related tickets by moving it to a new queue.
Of course the last two points require that the user has the right to do so, according to the ACLs.
RTIR Constituency is a queue-level custom field, so the queue a ticket is in determines the constituency. Constituencies is an optional feature of RTIR so you can choose to leave it unset.
Constituency is a custom field that applies to all RTIR queues. The RTIR administrator can manage the field and its values via the RT web interface at Tools -> Configuration -> Custom Fields -> click on the "RTIR Constituency" custom field. At the bottom of the page in the Values section, you can add, delete, and rename values, and change the sort order.
However, to get advanced control over constituencies you have to create additional objects in the system. The steps below describe how to do this manually. A script (bin/add_constituency) is also provided which helps add new constituency values, along with their associated groups and queues. In previous versions of RTIR, these queues were a hidden implementation detail. In RTIR 4.0, each constituency has its own queues, which work like regular RT queues.
In some simple configurations, administrators may use the web interface to add, delete, or rename values for the 'RTIR Constituency' field, however if you need the advanced access control RTIR's Constituencies system provides, you need to create several queues and groups for each value.
For example the following objects affect the rights users can have to the constituency 'EDUNET':
Queue 'Incident Reports - EDUNET'
Queue 'Incidents - EDUNET'
Queue 'Inestigations - EDUNET'
Queue 'Countermeasures - EDUNET'
Group 'DutyTeam EDUNET'
Group 'ReadOnly EDUNET'
See "Access Control (ACLs)" below for more about granting rights using special queues and groups.
To make it easier to create all of the objects in RT needed for a constituency, we have provided a tool to help. The tool can create everything needed for a new constituency configuration, including groups with some default permissions. It can also rename existing queues. You can read the docmentation for the tool online at add_constituency or on your system. To run the tool, navigate to your base RT directory and run it as follows:
cd /opt/rt4 # Default location, yours may be different local/plugins/RT-IR/bin/add_constituency --help # View docs local/plugins/RT-IR/bin/add_constituency --name EDUNET --correspond 'firstname.lastname@example.org'
After you run the tool, you can look at the permissions granted for the groups created and modify them as needed.
Starting in RTIR 4.0, the
$RTIR_StrictConstituencyLinking option replaces the old
$_RTIR_Constituency_Propagation configuration option.
$RTIR_StrictConstituencyLinking is a simple boolean which implements the most common behaviors of
$RTIR_StrictConstituencyLinking is set to 1, any attempt to link RTIR tickets across constituencies will result in an error.
$RTIR_StrictConstituencyLinking is set to 0, RTIR will allow users to link tickets across multiple constituencies.
Before discussing constituency propagation in depth let's look at the primary ways of setting and changing the Constituency field.
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, the user will be able to create the ticket in any Incident Report queue for which they have the 'SeeQueue' and 'CreateTicket' permissions.
RTIR allows users to create new tickets and link them with another as a single step. For example a user can create a new IR from an Incident or launch an Investigation from it. When a ticket is created based on an existing ticket, we can use the core information from the existing ticket, including the constituency value.
RTIR_StrictConstituencyLinkingis set to 1, the list of available queues for the new ticket will be limited to the Constituency of the source ticket.
- Creating a new ticket with Incident Id
This case is similar to the first case, but the user provides an Incident Id in the Incident field. Since the new ticket references and existing ticket, constituency logic can come into play as noted in the second case.
- Updating an existing ticket
Users can edit an existing ticket and change its constituency by moving it to a new queue on the 'Advanced' tab.
If RTIR_StrictConstituencyLinking is set to 1, and the ticket's new queue is in a different constituency, all linked tickets will be moved to the new queue's constituency.
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 constituencies, it allows you to link tickets with different constituencies even if
RTIR_StrictConstituencyLinking is set to 1.
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
$StrictLinkACL option in RT's configuration.
Each constituency has its own queues in RTIR. As such,
CommentAddress work just like they do for any RT queue.
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 fallback address is the
$CorrespondAddress in the RT's configuration file.
It is important to note that these additional configurations do not also add new mail routing rules. It is your responsibility to configure
rt-mailgate and other parts of your email infrastructure to handle mail coming to the constituency correspond addresses.
RTIR allows you to grant additional rights to tickets based on their constituency by means of "pseudo" queues ("Incidents - EDUNET" for the EDUNET constituency on the Incidents queue, for example).
For example, assume you have two constituencies "EDUNET" and "GOVNET". Your RTIR instance consists of four queues for each constituency: Incident Reports - EDUNET, Incidents - EDUNET, Investigations - EDUNET and Countermeasures - EDUNET. To grant the user Edward the right to work with EDUNET Incident Reports, make Edward an AdminCc of the new queue, either directly or as a member of a group like "DutyTeam EDUNET".← Back to index