ClearQuest Email Notification Package

ClearQuest Email Notification Package

Created by ClearQuest admin for ClearQuest admins.

Email Notification Package

It is NOT a solution that is provided and supported by IBM-Rational. It is a replacement of existing package that allows you to overcome drawbacks of standard solution and satisfy all notification requirements that you might possibly have, creating custom emails using text or HTML. The package offers ultimately flexible way of customizing notifications with no need of modifying ClearQuest schema. Usually, you need to update schema once, when you installing the package and applying it to desirable record types. It offers you rich functionality from the beginning and allows your to enhance it.

The package was initially released in 2004, and presented on RUC 2006 and IBM VoiCE 2011.

Here is a quick overview of some of the features.

Centralized configuration and maintenance

Email settings are stored in the ClearQuest user database. You do not need to configure every client. You configured notification on the database, turned them on – and it is working for all users, regardless of the client type: Windows, CCWeb, UNIX. It also easy to turn off notifications when they are not necessary. For example, you copied your production database to a test environment, turned the plug off, and you do not bother your users with annoying emails while testing.

Reliable delivery/Message Queue

If message cannot be delivered due to SMTP relay outage, delivery error or connectivity issue, it is saved in the message queue and will be re-delivered. You can optimize delivery mode based on your own requirements and needs. There are tree delivery modes offered by the package Light, Deferred (default), and Queue.

In case of Light delivery mode each client tries to deliver message to SMTP relay immediately, and store generated messages in the database for further re-delivery if attempt was unsuccessful only.

Deferred delivery means that client stores all triggered messages in database message queue first, and then tries to deliver them, as well as other eligible messages that might be left from previous unsuccessful delivery attempts. All messages are sent in batch mode when rules evaluation is completed.

In case of Queue delivery mode, client stores all messages in database and does not attempt to deliver. In this case, SMTP delivery is performed by separate CQPerl script running from ClearQuest server.

You can find out more about delivery modes here.

Email Message Log/Audit trail

In Deferred and Queue delivery mode all generated messages are stored in the message queue, which is a ClearQuest table. You are able to validate what was sent and when, check for delivery errors, error messages. In addition to that you can update and re-deliver messages if necessary within the ClearQuest.

Message queue is also useful to develop and debug email notification rules. For example, you can turn on email notifications on your test database, and set Queue delivery mode without delivery script running. Email Rules will be evaluated, emails triggered and saved in the database, but users would not be disturbed. You can review generated emails and sent them manually, if necessary.

Customizable message envelope and body

You can create almost any message you want. Most of the field in the notification rule that defines email message are free-text fields, where you can embed parameters, such as record fields, database properties, results of SQL statements execution, Package or Perl build-in, and user-defined function. At runtime, during the rules evaluation, these parameters will be expanded, substituted with actual field values and function's return results.

For example, you configured subject in your email notification rule as:

 Defect $ID has been $State

and subject in the generated email message might look like

 Subject: Defect RATL0000001 has been closed 

You can also use html emails with rich formatting, colors, embedded images, links, etc.

Configurable email message priority

Users receive tons of emails, and sometimes you need to attract their attention to some of them. Priority field can be used to flag some messages. It can be a static priority specified for email notification rule, or dynamically evaluated priority. For example, you can flag messages that are generated by incident with Severity 1 only. Since your email body is also customizable, you can add there details instructions for the recipient on what needs to be done when they received such email.

Additional header information

It might be required to include some information not just to message body, but also to the message envelope. For example, to inform the mail agent about character set used in the message, or specify particular message type, such as html, etc. It could be used for specifying reply-to address, references, or other special information.

Notification conditions

Notification condition filed provide you additional mechanism to customize message behavior. Along with fields, parameters and function, you can use logical comparison, arithmetic and other operators, as well as regular expressions patterns.

Message sender and reply-to address

You can send email using the current user email address in the “From:” field, select a dedicated email address that will be used for all emails generated in the database, or create from email address dynamically when email is triggered. It is flexible and can be used in many ways. For example, it can help you satisfying mail relaying policies in very restrictive environments. If necessary, you can configure different Reply-To address, that will be used when users try to reply to generated emails.

Site-specific settings in Multisited environment

If you use ClearQuest multisite, you might change some database settings based on the site where you are located. For example, to point your users to a site-specific SMTP relay. It is not a problem: the package allows you to create global, as well as site specific settings, to modify or unset global database properties on particular site.

Password authentication with SMTP relay

Optionally, you can configure password authentication with SMTP relay. Credentials used for notification can be saved as encrypted values in the database

Reminders

Another nice feature of the package that it allows you to configure reminders, such as notifications about approaching due date, or other important events. I called it Timed Notification. You can create a template using the same flexible email notification rules, and Timed Notification script will trigger them using dummy action.

Email Notification Subscription

You can allow users to manage there email notification rules subscription preferences. This functionality is delivered with optional EmailSubscription package. It can be used as-is, enhanced, or taken as an example to implement your own, more sophisticated end-user subscription solution. Please check Email Subscription page for details.

Getting Started

Would you like to try it? Then, create a backup of your schema and user database, or (even better) create test environment with master and user databases. Many customers have been using the package for years, but it is always makes sense to test the package in your specific environment and check for conflicts with existing hooks, issues with particular database vendor and version, etc, and update production when you are sure that it would be safe to do it only.

1. Download the package.
2. Install it.
3. Create your first notification rule

Additional Information

1. It could be useful to read package configuration guide and
2. Frequently Asked Questions
3. Please check Examples and
4. Extending IBM(R) Rational(R) ClearQuest(R) Email Notifications presentation
5. Reminders / Timed Notifications
6. End users self-subscription to email notifications
7. If you have questions or problems, welcome to the support forum

License

The ClearQuest Email Notification Package is licensed under the GNU Lesser General Public License (AKA, the "LGPL"), Version 2.1, February, 1999.