• Multiple Constituency Functionality
  • Definitions
• Implementation Details
  • Mandatory
  • Constituency Values
  • Manually Managing Constituency Values
  • Constituency Propagation
    • Introduction
    • Constituency Propagation Options
    • no
    • reject
    • inherit
    • Advanced Linking
  • Outgoing Mail: "CorrespondAddress" and "CommentAddress"
  • Presetting Constituency from Email
  • Access Control (ACLs)
    • Constituency Specific Groups
    • DutyTeam Group vs. Constituency Specific Group
  • Constituency issues

Multiple Constituency Functionality

In some cases, your incident response team may provide services to multiple different "customers" or constituent groups. For example, you my provide incident support for both educational and governemental institutions. You may have different contact mechanisms for members of these groups including different email addresses for reporting incidents. For a variety of reasons, it makes sense to identify and separately track interactions with these individual constituencies, particularly when handling incidents.

However, it also makes sense to use the same tools when working on these separate sources of data. Depending on the constituency, different users may wish to work on incidents within different queues or have access to incident data held within different queues. Members on the education response team may not have privileges to see information on government incidents, so you need to be able to assign user privileges depending on the constituency.

With some additional configuration, RTIR provides a flexible system that supports setting up multiple constituencies with different incident handling and access rules. These configurations all run in a single RTIR instance with shared workflows and global configuration that applies to all constituencies. This guide will help you configure RTIR to manage multiple constituencies.

Definitions

A constituency is defined by:

• Its name.

• Its correspondence email address.

• Associated ACLs (rights and permissions for queues, tickets, etc.)

A ticket is assigned a constituency in a few different ways:

• On new incoming incident report, the constituency is preset automatically based on the email address the email is sent to (the correspond address).

• Any new incidents created from incident reports, or blocks and investigations created from incidents, inherit the constituency from the launching ticket.

• You can manually assign the constituency to any new tickets created in the RTIR web interface.

• You can manually change the constituency of a ticket and all its related tickets.

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.

Implementation Details

Mandatory

The constituency field is a mandatory field, so users must select a value when creating RTIR tickets.

Constituency Values

Constituency is a custom field that applies to all RTIR queues. The RTIR administrator can manage the field and its values via the web interface at Tools -> Configuration -> Custom Fields -> click on Constituency custom field. At the bottom of the page in the Values section, you can add, delete, and rename values, and change the sort order.

However, to get advanced control over constituencies you have to create additional objects in the system. The steps below describe how to do this manually. A script (bin/add_constituency) is also provided which helps add new constituency values, along with their associated groups and queues. These queues are there only for technical reasons and are only visible for administrators of RTIR. The script is located in the etc directory in your RTIR distribution.

Then assign users to their corresponding DutyTeam to give them control over objects from their constituency. As the permissions are based on the constituency field of the ticket there is no need to move tickets from one queue to the newly created constituency queue.

Manually Managing Constituency Values

In some simple configurations, administrators may use the web interface to add, delete, or rename values for the 'Constituency' field, however if you need the advanced access control RTIR's Constituencies system provides, you need to create several queues and groups for each value.

For example the following objects affect the rights users can have to the constituency 'EDUNET':

• Queue 'Incident Reports - EDUNET'

• Queue 'Incidents - EDUNET'

• Queue 'Inestigations - EDUNET'

• Queue 'Blocks - EDUNET'

• Group 'DutyTeam EDUNET'

• Group 'ReadOnly EDUNET'

These queues are used to store limited per-constituency information for tickets in the master queue. For example, you can set the constituency base correspond and comment addresses.

See "Access Control (ACLs)" below for more about granting rights using special queues and groups.

Constituency Propagation

The $_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 "Constituency Propagation Options".

Introduction

Before discussing constituency propagation in depth let's look at the primary ways of setting and changing the Constituency field.

Creating a new ticket without links

This is the simplest case. A user creates a new ticket and there is no reference to an existing ticket. For example, the user creates an IR using the web UI by clicking RTIR -> Incident Reports -> Create, fills in values, and leaves the Incident input blank. In this case Constituency will be set to the default, set in %RTIR_CustomFieldsDefaults in the RTIR configuration, or to the value the user selects.

Creating a new ticket with a link

RTIR allows users to create new tickets and link them with another as a single step. For example a user can create a new IR from an Incident or launch an Investigation from it. When a ticket is created based on an existing ticket, we can use the core information from the existing ticket, including the constituency value. In this case, the configuration option defines whether the user is allowed to manually change the constituency value.

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 the Constituency value, and this can affect linked tickets as well. This case in particular is controlled by the propagation option you set.

Constituency Propagation Options

The three propagation algorithms are available:

no

This is the default algorithm. Any combinations are allowed. Users can link tickets with different constituencies. Changing the value on a ticket doesn't affect linked tickets. However, reasonable defaults are still used. For example when a user creates a new ticket from another one we select constituency of the existing ticket by default instead of using the default value from the config.

reject

This algorithm doesn't allow a user to link tickets with different Constituency values.

Users cannot change the Constituency value when creating a new ticket from another one.

When linking tickets together, the list of possible constituencies is restricted by the constituency of the former ticket, so the user may not choose targets with different constituencies.

The Constituency value on an existing ticket can be changed only if the ticket is not linked to any other tickets.

inherit

This algorithm is something in between no and reject. Operations are not rejected; instead we prefer the value of a new incident when a user links tickets together.

If the user uses New or Launch links on the main view of an incident, investigation, incident report or block to create a new linked ticket then the creation page contains a predefined value for Constituency and can't be changed at this point.

The Constituency value can be changed on existing tickets, even if the ticket has other tickets linked to it. In this case, RTIR updates all related tickets during the update, so all continue to have the same value.

Note that while linking tickets together, the list of possible candidates is not restricted by the constituency of the initial ticket, so a user may choose targets with different constituencies. In the latter case the incident's Constituency value is always preferred.

Advanced Linking

The Advanced tab allows you to do things that generic RTIR interfaces don't, so you can merge arbitrary tickets, move tickets between queues and, most important for constituencies, it allows you to link tickets with different constituencies even if the propagation algorithm is set to 'reject'.

Permissions (ACLs) are still applied to such operations, but administrators should note that by default links don't require bi-directional ACL checking. This means a user does not need the ModifyTicket right on the ticket they are linking to in order to set up a link. This behavior can be changed using the $StrictLinkACL option in RT's configuration.

Outgoing Mail: "CorrespondAddress" and "CommentAddress"

If you create queues as described in "Managing Constituency Values", the queue correspondence and comment addresses will override the original queue's where possible.

For example, if a user replies to an IR with constituency EDUNET and RTIR sends notifications, the correspond address of the 'Incident Reports - EDUNET' queue is used in notifications, if one is set. If the field is empty, the correspond address of the 'Incident Reports' queue is used unless it's also empty. The last fallback address is the $CorrespondAddress in the RT's configuration file.

It is important to note that these additional configuration do not also add new mail routing rules. It is your responsibility to configure rt-mailgate to handle mail coming to the constituency correspond addresses.

Presetting Constituency from Email

Many mail transfer agents (MTAs) allow you to specify a flag on any incoming email message by appending "+flag" after an email address. This option is supported by postfix, sendmail, qmail, exim and others, though the "+" delimiter has different defaults on some systems and can be customized by a site's systems administrator.

RTIR's multiple constituency support uses this extension mechanism to allow a single queue to receive mail for multiple constituencies. If you have two constituencies, EDUNET and GOVNET, you might set up RTIR's "incident report" address as follows in /etc/aliases:

    edu: abuse+edunet
    gov: abuse+govnet
    abuse: "|/path/to/rt-mailgate ...mailgate options..."

The rt-mailgate script expects the MTA to set the EXTENSION environment variable with a value of "flag." The script adds this value to the incoming message in the 'X-RT-Mail-Extension' header field. If an incoming mail has 'X-RT-Mail-Extension: <valid constituency value>' header field then a new ticket is created with Constituency set accordingly.

The Constituency field is mandatory so if the mail gate is not configured then the default value from the config is used.

Access Control (ACLs)

RTIR allows you to grant additional rights to tickets based on their constituency by means of "pseudo" queues ("Incidents - EDUNET" for the EDUNET constituency on the Incidents queue, for example).

For example, assume you have two constituencies "EDUNET" and "GOVNET". Your RTIR instance consists of four queues: Incident Reports, Incidents, Investigations and Blocks. To grant the user Edward the right to work with EDUNET Incident Reports, you'll need to create a new queue, "Incident Reports - EDUNET". Make Edward an AdminCc of the new queue, either directly or as a member of a group like "DutyTeam EDUNET".

You should grant that user or group the rights you want them to have to tickets in the "Incident Reports" queue. It is important that you 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.

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.

Constituency Specific Groups

For each Constituency value, the RTIR admin can create a group 'DutyTeam [constituency_value]' using either the web UI or the script.

We've added some automation for such groups. Those groups are added as an AdminCc to a ticket according to value of the field and you can grant additional rights using this assignment. For example if you grant the 'TakeTicket' right to the AdminCc role on the IR queue then users that are members of the 'DutyTeam EDUNET' group will have this rights on all EDUNET tickets.

Note that this method has some limitations and caveats. Users who have enough privileges still can add other users and groups as AdminCcs of a ticket and these principals will get the same set of additional rights that constituency-specific groups get via the AdminCc role. Since this uses the AdminCc role to grant constituency rights, you cannot use the role to grant one set of rights to group X and another set to group Y.

Also, by default AdminCcs are notified on many ticket actions, so this feature can be a little bit noisy for members. You either can disable notifications of AdminCcs or disable this functionality.

If you want to disable this functionality you just have to disable "SetConstituencyGroup" scrips in RTIR's queues. These scrips add or replace group in the AdminCc list when people set or change the ticket's constituency. If you still need more control over ACLs then you can use the pseudo-queues to add this control.

DutyTeam Group vs. Constituency Specific Group

By default DutyTeam has almost all rights on all RTIR's queues. This group's rights apply to tickets with all constituencies, so if you want to give access to group 'DutyTeam EDUNET' on EDUNET tickets only, then you don't want to make this group a member of DutyTeam.

In RT/RTIR you cannot deny a right for a subgroup of a group if the parent group has it, so you should avoid adding groups into groups with higher privileges. We suggest leaving DutyTeam and constituency specific groups on the same level, however, you can join them using a new top level group.

The same rules apply to user members of groups. Rights of all groups a user is a member of are summed up and if he is a member of DutyTeam with default of rights then he has more rights than any member of a constituency specific group (who is not member of other groups). Considering the above suggestion, a good way to manage users is to place each user in a constituency specific groups based on their access needs. Place users into DutyTeam only if they should work with all constituencies.

Constituency issues

Constituencies are very heavyweight, they add extra code to many permission checks in the system and also greatly complicate the number of groups and group members in the system. If you are not going to use this functionality, you would be well served to disable the Constituency Custom Field, which will cause RTIR to remove a number of added complexities.

Additionaly, while RT 4.2 has shipped with the config option $UseSQLForACLChecks defaulted on, it is not compatible with Constituencies. If RTIR detects that it is being started with Constituencies enabled it will disabled $UseSQLForACLChecks. Overriding this means that any part of the UI trying to show a list of tickets (such as the RTIR homepage or any search results) will be empty for users in restricted Constituency DutyTeams.

← Back to index