Paul at 14:44, 1 February 2013

2013-02-01T14:44:47Z

Paul at 18:54, 22 August 2011

2011-08-22T18:54:22Z

Paul: 1 revision

2010-11-05T00:28:08Z

1 revision

Paul: /* OR provide filter criteria for dynamic query */

2008-12-11T11:56:18Z

‎OR provide filter criteria for dynamic query

New page

=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. A call such kind of requests Timed Notifications or Reminders.

== How Timed Notifications / Reminders are implemented? ==
There are two parts of the complicated task
# find records that are eligible for notification
# trigger notifications based on information in selected records

=== How to find records? ===
To make it flexible, the selection process is implemented in two phases

==== Initial records selection ====
It is limiting scope based on simple criteria the 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:
# create a ClearQuest query, and save it in the public workspace
# 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 [[Download | 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
<source lang="bash">
cqperl TimedNotification.pl <cq_login> <password> <database> <dbset> "DailyNotification"
</source>

=== 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)
{| width="100%" border="1" cellspacing="2" cellpadding="5" valign="top"
! Field
! Value
|-
| Name
| Defect_Reminder
|-
| Record Type
| Defect
|-
| Actions
| '''DailyNotification'''
|-
| Condition
| <source lang="perl"> $Due_Date ne '' && DateTimeDiff( $Due_Date, GetDateTime('+1d') ) < 0 </source>
|-
| To:
| <source lang="perl"> ${owner.email} </source>
|-
| Subject:
| <source lang="text">Defect $ID will pass due date $Due_Date soon</source>
|-
| Body:
| <source lang="text">You need to do something with defect $ID</source>
|}

=== 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 ==
{| width="100%" border="1" cellspacing="2" cellpadding="5" valign="top"
! Property name
! Description
|-
| valign="top" | '''''TN_RecordTypes'''''
| list of record types enabled for the timed notification script 
|-
| valign="top" | '''''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.
|-
| valign="top" | '''''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
|-
| valign="top" | '''''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. 
|-
| valign="top" | '''''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.
|}
 

[[Category:Email_Notification_Package]]

← Older revision		Revision as of 14:44, 1 February 2013
Line 148:		Line 148:
	<br /> <br />		<br /> <br />

−	[[Category:Email_Notification_Package]]	+
		+	[[Category:Rational]] [[Category:Email_Notification_Package]]

@@ Line 3: / Line 3: @@
 == 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. A call such kind of requests Timed Notifications or Reminders.
+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
-# find records that are eligible for notification
+# find records that could be eligible for notification
 # trigger notifications based on information in selected records
 === How to find records? ===
-To make it flexible, the selection process is implemented in two phases
+To make it flexible and to avoid waste of resources, the selection process is implemented in two phases:
 ==== Initial records selection ====
-It is limiting scope based on simple criteria the 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.
+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:
 # create a ClearQuest query, and save it in the public workspace

← Older revision	Revision as of 00:28, 5 November 2010
(No difference)

Timed Notification - Revision history

Paul at 14:44, 1 February 2013

Paul at 18:54, 22 August 2011

Paul: 1 revision

Paul: /* OR provide filter criteria for dynamic query */