ClearQuest Email Notification Package Delivery Mode

Delivery Mode

The package was designed to use Simple Mail Transfer Protocol (SMTP) to deliver generated notification messages. SMTP allows to unify configuration for all 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 the 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 as well.

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 performs delivery in the following way.

When user is executing some action in ClearQuest, email rules are evaluated. All notifications 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 other action is performed later by the same or other ClearQuest client, at the end of rules evaluation cycle (4) and 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 the 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 messages 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 security policy, blocked by firewall, or fails due to application bugs (for example, socket library in some versions ClearQuest 7.0 Eclipse client). It also improves end-user performance, in comparison with Deferred mode, as actions are not delayed for 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 delivery of email even with no user activity on the database.

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

Custom Delivery Mechanisms

SMTP along with offered delivery modes should satisfy most of the users' requirements, but sometimes, it might be required to employ custom delivery mechanisms. 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 and enhancing it.