11. Configuring Notifications

Notifications, Events, and Targets

Polarion can send email notifications to users when changes occur to Work Items. Certain kinds of changes trigger notification events. Examples of changes that trigger notification events include:

  • A new Work Item is created or an existing Work Item is updated: its status, assignee, or approval state changes, for example.

  • A new user is created.

  • A new Document is created in a project.

  • A build finishes or fails.

Notification events have targets which represent some user or aggregation of users. For example, a status-changed event normally has a target representing the author of the Work Item. Therefore, when a change in the Work Item's status triggers the event, a notification is sent to the Work Item's author (i.e. the user who created the item). Some targets represent an aggregation of users. The all-watchers target encapsulates all users who have a Watch set on a Work Item.

Event's can have multiple targets. For example the status-changed event might also have targets "all-watchers" and "all-voters" in addition to the current-author target. If the same user happens to be in multiple targets for the same event, only one notification is sent to that user.

Users that are both Included and Excluded

The general rule is as follows:

When a user is in a group that is both included and excluded, then by default they will not receive notifications.

The default notification scheme is designed to be sufficient for many organizations, but may not be exactly what yours needs. For example, you may want to reduce the overall number of notifications going across your network, or add targets, or change default targets of some events. Therefore, the notification scheme is configurable. This chapter explains how to access and perform configuration of notifications.

Enabling E-mail Notifications

Before Polarion can send email notification to users, it is necessary to enable the notifications feature, specifying the SMTP server and other parameters. This setup is typically done during the installation and initial configuration process, so details are provided in the PDF installation guide document bundled with Polarion distributions. On Windows systems, the full installer presents a screen for enabling notifications and specifying basic configuration settings.

Once you have email notifications enabled, you can proceed to customize the configuration for the notifications feature as described in the remainder of this chapter.

Accessing the Configuration

Basic notification properties are configured in the global scope for each Polarion repository. Targets can be configured both globally, and in individual projects to override the global configuration.

To access the configuration:

  1. Make sure you are logged in with administrator permissions for the scope you want to configure.

  2. Enter the Administration interface (click the Administration link in the tool view of Navigation).

  3. In the Navigation pane, expand Notifications. If you are working in the global (Repository) scope, the following Navigation links appear under Notifications:  

    • Settings - global configuration for some basic settings related to properties of emails sent by the system.

    • Events and Targets - global configuration of targets for notification events.

    • Layouts - global configuration for the layout of email notification messages for notifications related to Work Items.

    If you are working in the project scope, only the Events and Targets and Layouts topics are present, providing access to the project-scope configuration for these items. Settings in the project scope override the same settings in the global configuration.

Configuring Settings

The Settings page provides fields enabling you to specify properties of notification email messages such as a prefix for the subject line and an email address to be used as the sender address in outgoing emails. You can refer to the Quick Help text embedded in the Settings page for information and examples.

Configuring Event Targets

The Events and Targets administration page provides table of all available notification events for the scope in which you are working. For each event, you can specify add targets or remove existing targets, define if targets are included or excluded from notifications, and set values for several Advanced properties for each event.

The objective here is to decide which events you want to have trigger notifications (and just as importantly, which events you do not) want triggering notifications, and which users should receive notifications as a result of the events you decide to include. You should make sure you include all the desired events in the configuration, and remove any events for which you don't want any notifications triggered. For each event you include, you need to be sure that the target(s) include all the users who need to get notification about the event.

Reference information explaining the events and targets is available in the Events and Targets page where you configure the settings (scroll the page to see it). In particular, you will need to understand which actual users are represented by each target in order ensure that no one is left out who needs to get a notification.

Understanding the Events Table

Each row in the Events table represents a notification event. The name of the event appears in bold type in the Event column.

The targets currently configured for each event are listed in a tabular format in the  Targets column. Each target occupies a row in this sub-table. The last sub-table row enables you to add another target to the event using a drop-down list of targets. You can remove existing targets listed in this sub-table by clicking the icon on the desired row. You can add multiple targets using the icon to create a new row in the sub-table for an additional target.

You can add events or remove events by adding or removing rows in the Events table. Remove an event row using the icon in the row's Actions column. The last row in the table enables you to add an event, using a drop-down list of events to specify which event. (You will probably need to scroll down to see this row.) You can add multiple events using the icon.

The following tips are useful to keep in mind:

  • The in the Actions column is disabled in the project scope when there is no project-scope configuration and the project is using the global configuration. You need to create a project-scope configuration using the Create button that appears above the Events table when you are working in the project scope.

  • Advanced settings are hidden by default. Click the Show Advanced Settings button in the page toolbar to show or hide these settings. Advanced settings have to do with setting priority values between multiple configuration elements for the same event. For details, see the embedded Help on the Notification Events and Targets administration page.

Customizing Layout of Notification Emails

Notification Layouts provide a way to customize the layout of email notification messages pertaining to new and updated Work Items. A Notification Layout defines what fields are displayed in notification email messages, and how those fields are arranged. Layouts can be configured in both repository and project scopes.

There are two default layouts, which you can customize, or you can create your own custom layouts by changing these files. To actually use a customized layout, you need to configure an optional attribute named layout for particular Work Item related events.

The Notification Layout Editor provides an embedded XML editor which enables you to configure the layout without leaving your browser. In-line Help contains extensive comments on the various elements and how to structure them to achieve the desired layout.

To create a new Notification Layout configuration:

  1. Log in with administrator permissions for the scope you want to configure.

  2. Open the repository or project you want to configure and enter the Administration interface if you are not already there when you log in.

  3. In Navigation, expand Notifications and select Layouts. The Notification Layouts page appears, and displays a table of the existing notification layouts, if any.

  4. Click the Create New Notification Layout button. The Create New Notification Layout dialog appears.

  5. Select the Work Item type to which the new configuration is applicable, or if applicable to all types, select -- unspecific --.

  6. Enter a name for this Layout (do not use spaces or special characters) and click Next. The Notification Layout Configuration page loads in your browser.

You can now use the embedded XML editor in conjunction with the in-page Help text (scroll down if necessary) to define the layout configuration.

Finding Users with Disabled Notifications

Users can individually opt out of receiving email notifications by checking the Disable Notifications option on their user account page. You as an administrator may need to find users who have disabled their accounts.

To find users with disabled email notification in their user accounts:

  1. If you want to search users of a specific project, log in with administrator permissions for the desired project. Otherwise, log in the administrator permissions for the repository.

  2. Open the scope you want to search (repository, or the desired project), and in Navigation select User Management > Users.

  3. You can optionally sort the table of users on the "Disabled Notifications column by clicking on that column header. Or...

  4. In the Search field of the User page, enter this search string disabledNotifications:true and click Search.

    The table of users is filtered to show only those users who have checked the Disable Notifications option in their user accounts.