Manage notification emails

This section provides information about the email notification system in Dimensions CM.

Notification system overview

The Dimensions CM email notification system is designed to provide more control over email notification and content.

The notification system has a mechanism that enables administrators to configure which users/groups receive email notifications. The new notification system is designed to work together with the existing email notification mechanism. If switched on using subscriptions, it replaces the standard default Dimensions CM email notifications.

There are a number of standard, or system, notifications to which a user or group can be subscribed. For details, see Notification types.

Administrators with the appropriate privilege can subscribe users to notifications. For details, see Use the email notification system.

After one or more users have been subscribed to a notification, the default emails, which are usually sent to everyone with the appropriate role, are switched off in favor of the new subscriptions. This way, an administrator can configure users to receive only those notifications that are relevant to them.

The dmemail utility

When using the default email notification system, emails are sent immediately whenever a command runs. For systems with a slow connection to the email server, a time lag may occur before the command completes.

The new email subscription system writes every email event to the database to allow it to be processed later "on-batch" using a utility called dmemail. Commands are no longer tied to the response time of the email server, and a system administrator has more flexibility as to scheduling when emails are processed.

The dmemail utility provides more fine-grained control over email processing and can be configured to run as a scheduled task or on demand. The utility scans the pending email events, applies email templates, and sends the resulting email to the subscribed users. For details, see Use the dmemail utility.

Email templates

The email subscription model supports the use of email templates, enabling the administrator to customize the email content.

The templating syntax for the template files is the same as for writing remote jobs and build templates. It can support complex IF/ELSE constructs and other control conditions. For details about the email templating syntax, see the API reference.

The DM_EMAIL_TEMPLATE_DIR variable in the dm.cfg server configuration file defines the template location. By default, the templates are located under the $<installdir> folder in the email_templates subfolder.

One template file exists for each subscribable notification, and can be found using the Administration Console. By default, the templates support HTML syntax.

Back to top

Use the email notification system

The email notification system enables you to:

  • Subscribe users or groups to the mail events for which you want to generate notifications using the command line or the Administration Console.

  • Create/edit the required email templates to customize the notification content as desired.

  • Edit the dmemail configuration file (email_config.dat) and lastly, run the dmemail utility as required.

For details on how to subscribe users to email notifications in the Administration Console, see Subscribe users to mail events.

Or use the following commands:

Command Description
SUB Subscribe user/group to notification.
USUB Unsubscribe user/group to notification.
LMNR List mail notification rules.

For a full description of these commands, see the Command-Line Reference.

For a description of supplied templates and available variables, see Notification templates and variables.

For the options in the configuration file, see Dmemail configuration parameters.

Note: Users who are subscribed to this notification receive an email for every request that is closed within the system, regardless of the role held for that request or the request originator. When a request is closed by the subscribed user, the user does not receive a notification.

Back to top

Notification types

The following table describes the predefined email notification types to which users and groups can subscribe.

Note: Notifications are not processed for external requests.

Email notification name Type Object class Description
CREATE_USER_NOTIFICATION Create User (Administration notification) A new user has been created in the base database.
DELEGATED_ITEM_NOTIFICATION Delegate Item An item has been delegated.
DELEGATED_REQUEST_NOTIFICATION Delegate Request A request has been delegated.
DELETE_USER_NOTIFICATION Delete User (Administration notification) An existing user has been deleted from the base database.
DELIVERY_NOTIFICATION Deliver Project A delivery has been made to a stream.
DEMOTE_BASELINE_NOTIFICATION Demote Baseline A baseline has been demoted.
DEMOTE_ITEM_NOTIFICATION Demote Item An item has been demoted.
DEMOTE_REQUEST_NOTIFICATION Demote Request A request has been demoted.
DEPLOY_BASELINE_NOTIFICATION Deploy Baseline A baseline has been deployed.
DEPLOY_ITEM_NOTIFICATION Deploy Item An item has been deployed.
DEPLOY_NOTIFICATION Deploy   An item, request, or baseline has been deployed.
DEPLOY_REQUEST_NOTIFICATION Deploy Request A request has been deployed.
ITEM_LOCK_NOTIFICATION Lock Item An item has been locked in a stream.
ITEM_UNLOCK_NOTIFICATION Unlock Item An item deployment has been unlocked in a stream.
MERGE_ITEM_CONFLICT_NOTIFICATION Merge Item An item conflict needs to be merged.
PENDING_BASELINE_NOTIFICATION Action Baseline A baseline has been created or actioned.
PENDING_ITEM_NOTIFICATION Action Item An item has been created or actioned.
PENDING_PROJECT_NOTIFICATION Action Project A project has been created or actioned.
PENDING_REQUEST_NOTIFICATION Action Request A request has been created or actioned.
PROJECT_CONTENT_CHANGED_NOTIFICATION Action Project

An operation has changed the content of a project or stream, for example:

  • Create, modify, move, delete, export or remove an item.

  • Create, move or delete a folder.

PROJECT_LOCK_NOTIFICATION Lock Project A project or stream has been locked.
PROJECT_UNLOCK_NOTIFICATION Unlock Project A project or stream has been unlocked.
PROMOTE_BASELINE_NOTIFICATION Promote Baseline A baseline has been promoted.
PROMOTE_ITEM_NOTIFICATION Promote Item An item has been promoted.
PROMOTE_REQUEST_NOTIFICATION Promote Request A request has been promoted.
REQUEST_CLOSURE_NOTIFICATION Update Request

A request has reached its end of lifecycle state.

  • If you use this notification, the new email system is always used (even if you are not subscribed).

  • For request types that have the Notify Originator on Closure option set, an email is sent to the originator on closure, even if they are not subscribed.

  • Subscribers receive an email for every request that is closed, regardless of what role they hold for that request or who is the request originator.

ROLLBACK_BASELINE_NOTIFICATION Rollback Baseline A baseline has been rolled back from an area.
ROLLBACK_ITEM_NOTIFICATION Rollback Item An item has been rolled back from an area.
ROLLBACK_NOTIFICATION Rollback   An item, request, or baseline has been rolled back from an area.
ROLLBACK_REQUEST_NOTIFICATION Rollback Request A request has been rolled back from an area.
UPDATED_ACTION_DESCRIPTION_NOTIFICATION Update Request The action description of a request in a user’s inbox has been added or updated.
UPDATED_BASELINE_ATTRIBUTE_NOTIFICATION Update Baseline The attribute of a baseline in a user’s inbox has been updated.
UPDATED_DETAILED_DESCRIPTION_NOTIFICATION Update Request The detailed description of a request in a user’s inbox has been updated.
UPDATED_FILENAME_NOTIFICATION Update Item The project file name of an item in a user’s inbox has been updated.
UPDATED_ITEM_ATTRIBUTE_NOTIFICATION Update Item An attribute of an item in a user’s inbox has been updated.
UPDATED_PROJECT_ATTRIBUTE_NOTIFICATION Update Project An attribute of a project or stream in a user’s inbox has been updated.
UPDATED_REQUEST_ATTRIBUTE_NOTIFICATION Update Request An attribute of a request in a user’s inbox has been updated.
UPDATED_REQUEST_RELATIONSHIPS_NOTIFICATION Update Request An object has been related, or unrelated, to a request in a user’s inbox.
UPDATED_REQUIREMENT_NOTIFICATION Update Requirement A requirement that is related to a request in a user’s inbox has been updated.

Back to top

Email digesting

When a user or a group is subscribed to a notification, there is the option to make the subscription a digest type, which means that all emails for that user or group are batched together and sent as a single digest email.

This option enables users or groups to receive a summary of all the undertaken activity that matches their subscriptions.

Back to top

See also: