Notifications

This topic describes server and email notifications.

In this topic:

 

Server message notifications

Back to top

Email notifications

When you enable email for a server configuration, users can email the properties of an item to another user from within the application. The email recipients do not need to be running the application to receive the email.

The application sends automatic email to users when their exclusive locks on items are broken. Users can only break locks if they have the correct access rights and privileges to do so. You can also configure the application to perform automatic email notification when certain other events occur. Depending on the server configuration and system policy options you select:

• Members of the System Managers group can receive email whenever an error is added to the server log.
• Members of the Security Administrators group can receive email whenever a logon failure occurs.
• All users can receive automatic notifications about items for which they are responsible or for which they are recipients.

If you enable email notification, a user automatically receives email if:

• The Responsibility field value changes in a change request
• Any field for a requirement or task for which the user is responsible has changed.
• Any field for a topic for which a user is listed as a recipient has changed. (If no recipients are listed for a topic, no one receives notification)

Because email notification is client-independent, your team members do not have to run a client to receive notification messages.

Default messages sent to recipients of automatic email notification are localized, based on the locale of the server. When no translation is available for a locale, the message is in English.

Users may confuse email messages sent by individuals (using the Send to command in the client) with email notification messages, because unless you choose to customize the email message templates, they are somewhat similar. Therefore, it is a good idea to let users know when you enable automatic email notification and to explain the differences between the two types of email messages and the two types of notification.

Back to top

Custom email notifications

You can configure customized, automatic email notifications on a per-server configuration, per-project, or per-component basis. You can design your own text or HTML-based message templates or use the default templates provided in the Notifications folder, a subfolder of the server installation folder. All email notification messages (both plain text and HTML) are sent in UTF-8 encoding.

You can define custom email templates to use with email notifications for the following components:

• Change Request
• Task
• Topic
• Requirement

When a server configuration starts for the first time, the contents of the Notification folder in the installation directory are copied to the repository for the server configuration in a corresponding Notification folder. You can make customizations to the default templates in the Notification folder found in the server configuration repository. The predefined email notification files consist of a set of component-level XML configuration files – one for each desired component and an arbitrary number of email message body templates that can have any name that you choose. However, the configuration files must be named as follows:

• ChangeRequest.xml
• Requirement.xml
• Task.xml
• Topic.xml

The predefined email message body templates are named:

• itemTypeAbbr-new.txt
• itemTypeAbbr-modified.txt
• itemTypeAbbr-new.html
• itemTypeAbbr-modified.html

Where itemTypeAbbr corresponds to cr, req, task, or topic.

Each time that you start the server configuration, it scans the contents of the Notification folder. If the configuration (.xml) files are invalid and you have email notification enabled for your server configuration, the server issues an error message in the server log and fails to start.

You can also make dynamic updates to the message templates in the repository Notification folder without restarting the server configuration. The server checks for changes in the configuration and message template files every two minutes and immediately applies valid changes found in the files.

If the server finds a corrupted configuration and/or template file while the server configuration is running, a predefined email message is sent to the Admin group. Email notification becomes unavailable until you restore a valid configuration in the Notification folder. While any of the files in the Notification folder are in an invalid state, the server sends users the standard email notifications.

Fields used in email notification message templates

Within each of the sample templates provided in the Notification folder in your repository, you will find fields that you can use in your own customized templates. Three types of fields are used:

• Fields stored in the database
• Client-calculated fields
• Server-calculated fields

Embedded images in email notification message templates

You cannot embed images in the HTML email message templates. However, you can use a URL to an image on a web site that users can access.

Back to top

Configuring email support and notifications

This topic assumes that you have the Server Administration Tool open that you have selected and logged onto the server configuration that you want to change. If you are using the client (available with custom installations only), you can administer remote server configurations only.

1. Click Tools > Administration > Configure Server.
   The Configure Server page opens.
2. Select the Email tab.
3. Check the option to Enable e-mail support.
4. Type the host name for your SMTP (Simple Mail Transfer Protocol) server in the SMTP server field.

   You can use an IP address if your site uses only static IP addresses. The application uses SMTP, which traditionally operates over TCP using port 25. It is widely used and is the Internet’s standard host-to-host mail transport protocol.

   Note: For Microsoft Windows environments, the Exchange server is usually the SMTP server.

5. Optionally, type a value in the TCP/IP endpoint field if your SMTP server uses a port other than the default value, 25.
6. For secure ports, select either SSL or TLS.
7. If you want to use e-mail notification, check the option to Enable e-mail notification.
8. If you selected SSL or TLS, you have additional Security Settings:
   1. SMTP Certificate Name
      Name of certificate file to be used for the secure connection. This setting is required on Windows only .
      StarTeam Server will look for certificates in subfolder: install path\CACertificates. You should place the certificates in this folder. On Microsoft Windows, two certificates are pre-installed:

      Equifax	EquifaxCA.pem - This certificate is useful to connect to GMail SMTP server.
      Verisign	VeriSignClass3PublicPrimaryCA.pem - This certificate is used to connect to Yahoo SMTP server.

   2. SMTP HostName
      SMTP Hostname as it appears in the SMTP server’s certificate. If the hostname in the certificate does not match with the entered one, we will write a warning to the server log similar to: 62 00000002 2016-02-19 10:30:18 SMTP TLS Unrecognized certificate: error code=13 and error message: Certificate name does not match. Hostname not matching is a potential security issue: if the hostname in the certificate is not the expected one, there could be a "man-in the middle" security attack - this means another site is impersonating the SMTP server.
   3. SMTP Logon Name, SMTP Password
      These are the credentials to be used to login to the SMTP server. These are optional, they should be entered if the SMTP server requires them.
9. Click OK.
   

Back to top

Configuring notifications per project/component

This section describes how to configure email notifications on a project-specific and component-specific basis using the change request component as an example. You should have already enabled email support and email notification messages.

1. Navigate to the Notifications folder installed with StarTeam Server. The Notifications folder installs as a subfolder of your StarTeam Server installation. By default, StarTeam Server is installed in the C:\Program Files\Micro Focus\StarTeam Server <version> folder.

   Tip: Make a copy of the Notifications folder before making any modifications. You can revert to this copy if you make any undesirable changes.

2. You can edit the component-specific *.xml file for the component (change request, task, topic, requirement) that you want to use for project-specific notifications. Open ChangeRequest.xml and type the following rules for a specific project:

   <rule-list> <rule project=”MyProject” event=”new” template=”MyProject-cr-new-txt”/> <rule project=”MyProject” event=”modified” template=”MyProject-cr-modified-txt”/>

   In the above example, “MyProject” corresponds to your specific project name. These entries must go before the following default <rule project="*" event="new" template="cr-new-html"/> and <rule project="*" event="modified" template="cr-modified-html"/> entries.

3. Enter the template information used for your project under the <template-list> tag. For example,

   <template-list>  <template-id=”MyProject-cr-new-txt”>    <subject>New Change Request #~~ChangeNumber~~</subject>    <body content-type>”text/plain” template-file=”.\MyProject-cr-new.txt”/>  </template>  <template-id=”MyProject-cr-modified-txt”>    <subject>Modified Change Request #~~ChangeNumber~~</subject>    <body content-type>”text/plain” template-file=”.\MyProject-cr-modified.txt”/>  </template>

4. Save the changes and close the template files.
5. Copy your new template files and updated ChangeRequest.xml file to the Notifications folder in your repository.

Back to top