Manage notification emails

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

In this topic:

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.

Back to top

Notification types

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

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:

• Administration and error handling