Configure Notifications

Polarion can send email notifications to users when changes occur to objects in the system. Notification events are triggered when such changes take place. Examples of changes 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, updated, or commented in a project.

  • A build finishes or fails.

Notification events have targets, which represent some user or an aggregation of users who are to receive emails when the even occurs. For example, by default a status-changed event has a target current-author 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 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 at the time the event occurs.

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

Note:

If a user is part of the aggregation of a target that is included for an event, and also in the aggregation of another target that is excluded in the same event, the user will not receive notifications triggered by that event.

For example, if the workitem-linked event is configured to include the all-watchers target, and exclude the all-commenters target, and User A is included in the aggregation of users for both those targets, User A will not receive a notification when the workitem-linked event occurs.

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.

Enable notifications

Before Polarion can send email notification to users, it is necessary to enable the Notifications feature, specifying the SMTP server and other parameters. Because this is typically done during the platform installation and initial configuration process, details are provided in the PDF installation guide. It can be found in the Polarion section of Siemens' Doc Center. On Windows systems, the installer presents a screen for enabling notifications, specifying the email server, and other configuration settings.

Once you have email notifications enabled for your installation, you can proceed to customize the configuration for the notifications feature as described in later in this topic.

Access the configuration

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

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

  2. Enter Administration via the tool view of Navigation.

  3. In Navigation, expand Notifications. If you are working in the Global Administration scope, the following navigation nodes appear:

    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 messages for notifications related to Work Items.

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

Configure notification settings

The Settings page of the Notifications topic provides fields where you can specify a prefix for the subject line, and an email address to be used as the sender address in outgoing notification emails. Refer to the Quick Help text embedded in the page for information and examples.

Configure events and event targets

The Notification Events and Targets page provides table of the notification events currently configured for the scope in which you are working. You can add more events to, or remove events from the configuration. For each event, you can add targets or remove existing targets, specify whether targets are included or excluded from notifications, and set values for several advanced properties.

The objective here is to decide which events occurring in the scope should trigger notifications, and — just as importantly — which events you do not want triggering notifications. You must also decide which users and aggregations of users, represented by targets, should receive notifications as a result of the events you decide to include in the configuration. You should make sure to 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 or targets include all the users who should receive notifications when the event occurs.

Reference information explaining the events and targets is embedded on the Notification Events and Targets page where you configure the settings. (You may need to scroll the page to see it). In particular, you will need to understand how actual users are represented by each target in order ensure that no one is left out who needs to receive a notification. Target names are descriptive and should help you with this.

The Events and Targets table is important to understand in order to successfully customize the notifications configuration. Each row in the table represents a notification event. The name of the event appears in bold-face type in the Event column.

Tip:

Events, targets, and their names are predefined and cannot be changed.

The targets currently configured for each event are listed in a tabular format in the Targets column. Each target occupies a row in a sub-table embedded in each event row. The last sub-table row enables you to add another target to the event using a select 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 and Targets 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 icon 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 and Targets table when you are working in 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 provide event-specific data fields, and event-specific fields for properties of email messages generated in response to the event . For details, see the embedded Help on the Notification Events and Targets page.

  • The set of events and the set of targets are predefined in the system. You cannot add items to, or delete items from these sets, or modify their names.

Customize email message layouts

Notification Layouts provide a way to customize the layout of email notification messages about new and updated Work Items. A Notification Layout specifies what fields are displayed in notification email messages, and how those fields are arranged. Notification Layouts can be configured in both global and project scopes.You can create unspecific layouts that apply to all Work Item types, and type-specific layouts that apply to one specified Work Item type.

In the default global configuration there are some predefined layouts ,which you can optionally customize. You can create your own custom layouts in global or project scope using the default XML code of these layouts as a starting point. To actually use a customized Notification Layout, you must specify its name in the Layout field of relevant Work Item events on the Notification Events and Targets page. (Click Show Advanced Settings on that page to expose the field.)

The Notification Layout Configuration page that appears when you create a new layout, or edit an existing layout, provides an embedded XML editor that you can use to configure the layout without leaving your browser. Embedded Help on the page provides extensive comments on the various elements and how to structure them to achieve the desired layout.

To create a new Notification Layout, follow these steps:

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

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

  3. In Navigation, expand Notifications and select Layouts.

    The Notification Layouts page appears, and displays a table of the existing notification layouts. The table is empty of no layouts are defined yet.

  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 opens in your browser. You can now use the embedded XML editor in conjunction with the embedded Quick Help text to define the layout configuration.

Find users who have disabled Notifications

Users can individually opt out of receiving email notifications by selecting the Disable Notifications option on their user account page. As an administrator, you may need to find users who have done this. You can run this check in Global Administration or in individual projects.

  1. Log on with administrator permissions for the scope you want to check.

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

    A table of all users in the current scope appears on the page.

  3. In the Search field of the Users 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 account page.

Tip:

Instead of searching, you can optionally sort the table of users on the Disabled Notifications column by clicking on that column header.