Timed Notification

Timed Notification

What does Timed Notification mean?

Sometimes we would like to implement notifications that are not triggered by particular action. You might need a reminder that defect approached a resolution deadline, or that a trouble ticket passed due date, was not implemented in time frame required by the Service Level Agreement, was not assigned for implementation in a reasonable time frame. I call such kind of requests Timed Notifications or Reminders.

How Timed Notifications / Reminders are implemented?

There are two parts of the complicated task

1. find records that could be eligible for notification
2. trigger notifications based on information in selected records

How to find records?

To make it flexible and to avoid waste of resources, the selection process is implemented in two phases:

1. Initial records selection selects records that might be eligible, define notification scope.

   It would be too expensive to check evaluate every ClearQuest record to determine whether or not notification condition met. In order to improve performance and reduce load on the database, we need to reduce number or records for evaluation. For example, when implementing due date reminder, we could safely exclude closed or resolved defects. It could be different in other cases, but the main goal would always be defining potential notification scope, then

2. Final selection evaluates notification rules on selected at step (1) records and triggers notification if condition is met (for example, the record passed due date).

Initial records selection

It is limiting scope based on simple criteria that can be used in a SQL Query to retrieve records. For example, you can limit records based on record type, current state, severity, assignment, etc. Timed Notification script offers you two possibilities:

1. create a ClearQuest query, and save it in the public workspace
2. specify criteria to create the query dynamically during the execution

Final selection

In addition, records can be filtered based on Email Notification Rule Condition field. It is performed during evaluation of notification rules on the record set selected on the previous step. Rules evaluation is expensive process that is why it very is important to have good initial record selection.

Triggering notifications

Since we are using extremely customizable email notification rules for other actions, it makes sense to use the same functionality, and keep timed notification rules at the same place. Regular notifications are triggered by actions, timed notifications - by pseudo-actions. It means that in reality no action is executed, but the script evaluates email notification rules on selected records in the same way as it would be done if the real action would be invoked.

If you noticed, selection of actions on Email Notification Rule record is not limited to actions defined for the record type, and it is done on purpose: you can specify there non-existent, pseudo-action name.

To make all thins working, you just need to

• create a notification rule, using pseudo-action
• run the script using the pseudo-action as a parameter
• let script know the record types that it will be running on and the way to limit record set for notification rules evaluation.

ClearQuest does not have any server based process like cron that can trigger actions. It can be changed in the future (the new ClearQuest Web Server includes request manager that does not have any public interface so far), but as of today, the only way to trigger timed email notification is to run timed notification script from UNIX cron or Windows scheduler on your ClearQuest server.

You can download timed notification script here.

Configuration

For example, we would like to notify assignees about defects that will pass due date in the next 24 hours. I will name pseudo action used in this example DailyNotification

The following tasks need to be accomplished

Configure Scheduler on a ClearQuest server

CQ Web server could be a good candidate to run the script. The following script need to be configured to run daily, let's say at 4 AM

  cqperl TimedNotification.pl <cq_login> <password> <database> <dbset> "DailyNotification"

Enable Notification for the record type

In this example, we need to inform the script that it is running on Defect record type. In order to do it, TN_RecordTypes property need to be set to Defect (udb_property record type has to be submitted with "Defect" value)

Note: TN_RecordTypes property value can contain more then one record type. A list of enabled record types has to be specified as one-record-type-per-line.

Create email notification rule

Email Notification Rule for Defect record type (major fields)

Field	Value
Name	Defect_Reminder
Record Type	Defect
Actions	DailyNotification
Condition	$Due_Date ne '' && DateTimeDiff( $Due_Date, GetDateTime('+1d') ) < 0
To:	${owner.email}
Subject:	Defect $ID will pass due date $Due_Date soon
Body:	You need to do something with defect $ID

Limit record set for notification rules evaluation

It would be too expensive to evaluate the notification rule on each record. It is a good idea to limit an evaluation scope. As it was discussed above, there are 2 ways to do it.

Create query in ClearQuest client

For example, we can create query that will filter open defect, save as "Public Queries\Admin\DailyNotificationQuery" and set TN_Query-Defect-DailyNotification property to that value.

When script is executed, it checks TN_Query-{record type}-{pseudo action name} or TN_Query-{record type} properties if the first one is not defined.

Note: You could have both TN_Query-{record type} and TN_Query-{record type}-{pseudo action name} properties in your database. The first one would work as a default value for all action names, while TN_Query-{record type}-{pseudo action name} would overwrite default value if specified.

OR provide filter criteria for dynamic query

This way you can specify state names that have to be excluded from the notification. Based on information provided, script will create a query at run time. The states can be specified using TN_QueryExcludeStates-{record type}-{pseudo action name} or TN_QueryExcludeStates-{record type} property in one-state-per-line style. In our case, we can submit TN_QueryExcludeStates-Defect-DailyNotification property with the following values:

 Submit
 Closed

If 'TN_Query-{record type}-{pseudo action name}' and 'TN_Query-{record type}' properties do not exist, the script checks for excluded state properties and uses them as a filter in run-time created query.

Note: You could have both TN_QueryExcludeStates-{record type} and TN_QueryExcludeStates-{record type}-{pseudo action name} properties in your database. The first one would work as a default value for all action names, while TN_QueryExcludeStates-{record type}-{pseudo action name} would overwrite default value if specified.

Properties used in Timed Notification script

Property name	Description
TN_RecordTypes	list of record types enabled for the timed notification script
TN_Query-{record type}-{action name}	Workspace path to a ClearQuest query that will be used to extract record for email notification rules evaluation for pseudo action {action name} (from the script command line) Overwrites TN_Query-{record type} property when exists.
TN_Query-{record type}	Workspace path to a ClearQuest query that will be used to extract record for email notification rules evaluation for any pseudo action name
TN_QueryExcludeStates-{record type}-{action name}	a set of record states, one per line, that will be filtered out in run-time query for pseudo action {action name}, when TN_Query-{record type}-{action name} or TN_Query-{record type} properties do not exist. Overwrites TN_QueryExcludeStates-{record type} property when exists.
TN_QueryExcludeStates-{record type}	a set of record states, one per line, that will be filtered out in run-time query for any pseudo action, when TN_Query-{record type}-{action name} or TN_Query-{record type} properties do not exist.