ClearQuest Email Notification Package Delivery Mode

Delivery Mode

The package was designed to use Simple Mail Transfer Protocol (SMTP) for delivery of generated notification messages. SMTP allows to unify configuration for all possible ClearQuest clients (Windows, Eclipse, UNIX, CCWeb), but requires a mail server, also called SMTP relay, to accept incoming messages either anonymously, or using some credentials for authentication. Usually, it is not a problem. Many tools employ SMTP, and your would not be first who approached system administrators asking for mail server configuration information in your organization. They should be able to assist you.

It does not mean that SMTP is the only mechanism that can be employed. SMTP is "out of the box" solution, but other protocols can be plugged in.

There are three main delivery modes supported by the package: Deferred (default), Light, and Queue. Delivery mode is controlled by EN_DeliveryMode database property.

Deferred Delivery (default)

When no EN_Delivery mode property is set, or the property value is set to "Deferred," the package perform delivery in the following way.

When user is executing some action in ClearQuest, email rules are evaluated. All email messages created in result are stored in the ClearQuest database (1). A special stateless record type, en_email_message, a part of the package, is used to keep these messages. When rules evaluation is completed, the same ClearQuest client queries the database for all email messages that are eligible for delivery (2), and deliver them to the SMTP server (3). When message transfer is successful, these messages are accepted for further delivery to the recipients by the server.

It might be possible that SMTP server was not able to accept emails for delivery. For example, it could be down for maintenance, overloaded; connection could be blocked by firewall or internet security software installed on the user's machine.

In this case, these messages would be queried when action is performed by other ClearQuest client, at the end of its own rules evaluation cycle (4) to be delivered (5).

Maximum number of delivery attempts is 5, and can be changed by setting EN_DeliveryAttempt property. When maximum number of delivery attempts is reached, further delivery can be performed by ClearQuest administrator by executing Send Message action on the en_email_message records, or by resetting number of delivery attempts on them.

Light Delivery

When notification audit trail is not so important, and you would like to minimize interactions with database without sacrificing reliability, you can consider using Light delivery mode.

In this case, generated email messages delivered immediately to the SMTP server (1), and only when the server is unavailable or delivery is blocked, the message will be dumped to the database (2) to be queried (3) and delivered (4) by the same or other client later.

Queue Delivery

Another common way to process notifications is Queue delivery mode.

In this case ClearQuest client would not perform delivery attempt. All created emails are dumped in the database (1). These messages needs to be queried by delivery script (2) running on the ClearQuest server(s). The only requirement for the server is to have ClearQuest installed and database connection configured. ClearQuest Web (CM) servers could be good candidates for scheduled execution of the script, and it might make sense to configure more than one for redundancy.

Queue delivery might be extremely useful when sending emails from users' desktops is restricted by organization policy, blocked by security software, firewall, or fails due to application bugs (for example, in some versions ClearQuest 7.0 Eclipse client). It also improve end-user performance, in comparison with Deferred mode, as actions are not delayed while sending emails.

Other Considerations

Running delivery script on the server is required for Queue delivery mode, but might be useful with Deferred and Light modes as well. It would ensure timely message delivery even with no user activity.

Message queue, en_email_message table, has tendency to grow over the time. It is a good practice to periodically purge the table. A simple script can be found on Downloads page.

Custom Delivery Mechanisms

SMTP along with offered delivery modes should be able to satisfy most of the requirements. Nevertheless, it might be required to employ custom delivery mechanism. Fortunately, Queue delivery mode opens this possibility. When Queue mode is used, Email Notification package would ensure that all generated messages are stored in the database, and you can implement desirable delivery protocol by taking simple delivery script as an example.