ClearQuest EmailPlus - An Enhanced Email Notification Mechanism Alan Murphy

1. ClearQuest EmailPlus- An Enhanced Email Notification Mechanism Alan Murphy IT Specialist, IBM Rational Brand Services alan.murphy@uk.ibm.com Updated For Support Enablement Dec 2009

2. Limitations of Today's ClearQuests Email Sending Solution What Is EmailPlus? EmailPlus Features Configuration Operating Modes Agenda

3. Emails Can Only Contain: Data from one record New or Old Field Values Only Nothing from the Environment Nothing from Other records No Explanatory Text No Sending Context Why am I Getting this Email?

4. No Emphasis In Content Can't Use Text Effects Like Bold Can't Use Colour Can't Insert Graphics Can't Add Attachments Can't create a Web link to the record No Rich Content I expect Rich Content in my e-mails to highlight important information and improve readability

5. RATLC00705527, RATLC00705550, RATLC00705602, RATLC00705612, RATLC00705616, RATLC00705722, RATLC00705741, RATLC00705838, RATLC00705859, RATLC00706044, RATLC00706062, RATLC00706078, RATLC00706153, RATLC00706158, RATLC00706202, RATLC00706327, RATLC00706342, RATLC00706465, RATLC00706536, RATLC00706537, RATLC00706632, RATLC00706641, RATLC00706657, RATLC00706866, RATLC00706941, RATLC00707097, RATLC00707145, RATLC00707150, RATLC00707208, RATLC00707276, RATLC00707304, RATLC00707399, RATLC00707497, RATLC00707525, RATLC00707536, RATLC00707718, RATLC00712100, RATLC00457344, RATLC00988890, RATLC01006188, RATLC01011894, RATLC01053690, RATLC01194610, RATLC01194753, RATLC00496322, RATLC00507635, RATLC00705807, RATLC00707362, RATLC00707757, RATLC00770756, RATLC00983579, RATLC01021510, RATLC01024741, RATLC01027454, RATLC01027661, RATLC01028537, RATLC01029513, RATLC01029524, RATLC01035933, RATLC01043038, RATLC01044647, RATLC01047575, RATLC01048523, RATLC01054804, RATLC01064234, RATLC01068124, RATLC01209501, RATLC01225471, RATLC01231200, RATLC01261794, RATLC01263899, RATLC01271689, RATLC01293440, RATLC01371654, RATLC01067529, RATLC00705612, RATLC00706202, RATLC00507635, RATLC00770756, RATLC00983579, RATLC01021510, RATLC01024741, RATLC01027454, RATLC01027661, RATLC01028537, RATLC01029513, RATLC01029524, RATLC01035933, RATLC01043038, RATLC01044647, RATLC01047575, RATLC01048523, RATLC01054804, RATLC01068124, RATLC01209501, RATLC01231200, RATLC01261794, RATLC01263899, RATLC01271689, RATLC01293440, RATLC01371654 Note: Some of these are provided directly by package functionality, others can be achieved by using the customisation capabilities of the package. EmailPlus Closes off 80+ Outstanding Email RFE's

6. CQ Clients Talk Direct to SMTP Server SMTP Server What's all this email traffic?

7. SMTP Server Lockdown SMTP Server I'll Fix that !No more SPAM threat ! Hey CQ Emails not working !!

8. Limited Rule Conditions Based On: State Transitions Actions Query on Data in Triggering Record Only Performance Can be a Problem with lots of Rules(Especially those using Queries) Limited Addressing Capabilities Not End-User Customisable / Extensible MAPI now effectively useless due to security patches Individual users can disable email notifications Other Limitations

9. A New ClearQuest Email Package Replacement For Out-of-the-Box Email Rules Package Written in PERL Any Custom Extensions are done in PERL Also Works in VBScript Schemas Certain Transport Modes Require a VB Application running on Windows (Relay Component) Emails based on a template that can: Provide Boiler Plate Text Take Data from many sources – Not just the record NEW! What is EmailPlus ?

10. Rich Content including: Embedded Graphics including ClearQuest Charts Hyperlinks / URLs to Records, Queries, Charts & Reports Use text effects such as font, size, bold and colour Add File Attachments from the triggering record Vastly Extended Rules Capabilities Doesn't Use Queries No longer limited to just data in the triggering record Can use: PERL built-in Functions PERL Functions in your Schema ClearQuest API functions Users can Self Subscribe to rules and Record changes at admin discretion What Does EmailPlus Give Me?

11. How Does it Work?

12. EmailPlus Configuration Record

13. EmailPlus Site Configuration Record - 1

14. EmailPlus Site Configuration Record - 2

15. EmailPlus Templates - 1

16. EmailPlus Templates - 2 Template is boilerplate text with embedded substitution tags Tags are:Old Field ValueNew Field ValueMeta Tags Meta Tags:Built in orCustom

17. Template Substitution Tags • Replace tag with Current Field Value e.g. #?state?# • Replace tag with Old Field Value e.g. #%state%# • Replace Meta Tag with tag value e.g. #@NameOfRule@# • Create Your Own Custom Meta tags • Use Arbitrary PERL Expressions • Embed field tags in Expressions • Operate on Field Value • #@expression::formatdatetime(#?submit_date?#,1)@#

18. <img src="cockroach.jpg" HEIGHT=120 WIDTH=180 ALIGN=middle> <H1>New Defect Submission # #?ID?#</H1> <B>Severity: </B>#@EXPRESSION::if ( #?Severity?# =~ /^1/ ) { "<font color=\"red\">"; } else { "<fontcolor=\"green\">"; } @#Severity#?Severity?# </FONT><br> <B>Submission Date :</B>#@expression::formatdatetime(#?submit_date?#,1)@#<BR> <B>This Defect was submitted by: </B>#?submitter.fullname?#(#?submitter?#)<br> <B>EMail: </B>#?Submitter.email?#<BR> <H2><font color=\"green\">Headline:#?Headline?#</font></H2><BR> <B><font color=\"green\">Description :</B>#?Description?#</font><BR> <H2>Current Workload Assignment</H2><BR> #@embedchart::Public Queries/Distribution Charts/Active Defects by Owner::::@#<BR> <B>ClearQuest</B><BR>--//---<BR> <B>Generating Email Rule Name: </B>#@NameOfRule@# <BR> <B>Actioner User Name:</B>#@ActionerUserName@#<BR> <H3>#@URLofEntity::ClearQuest Web Link to New record @#</H3> <B>Generated on:#@expression::GetCurrentDate() ;@#</B><BR> Example HTML Based Template

19. Template is an HTML Body part Mail Transport used – SMTP Direct Example Generated Email

20. EmailPlus Rules - 1 Simple Rule of up to 5 Clauses No Database Query Involved All rule evaluation done in Memory – All Rules cached

21. EmailPlus Rules - 2 Retains State and Action Capabilities of old package Can be Combined in More Flexible ways

22. EmailPlus Rules - 3 Arbitrarily Complex Expressions Can Use PERL,CQ APIs Can call PERL routines in your CQ Schema

23. EmailPlus Rules - 4 Retains Addressing Capabilities of old package Allows indirect user references to other records

24. EmailPlus Rules - 5 Users can 'Self-Subscribe' to rules at administrators discretion. Subscription controlled by group membership.

25. Features By Mail Transport Types Some Modes Require a VB App running on windows

26. Post Office Server allowed access to SMTP Server Post Office Mode SMTP Server PostOffice Server ClearQuest Database

27. SMTP Direct Mode Clients allowed direct access to SMTP Server SMTP Server • Can use Either: • ClearQuest Email Component • PERL Email Client Component

28. Relay Mode Client talks directly to a Relay Server that is allowed access to SMTP Server SMTP Server Relay Server

29. Custom Mode Clients Sends Email However YOU Choose ? SMTP Server • Can be customised to use whatever mechanism YOU want to use. • Provides a Template routine which you provide the implementation of • Must be in PERL even in a VBSCRIPT schema. • Cannot call VBSCRIPT routines in your schema

30. EmailPlus Post Office & Relay Component

31. Extensive / Detailed Administrators Guide is provided Install Apply package Enable Record types Create EmailPlusAdmins group Subscribe admins to group and both to databases Configure Create an EmailPlusConfig Record Create EmailPlusSiteConfig record for each site (min1) Choose Transport Mode Provide SMTP Server or relay credentials Create at least one template Create at least one rule NOTE: Initial Release is part of CQALM1.1 Only (but it's still a package) NOTE2: Some Customers may have the earlier VBScript Version 1.7 and earlier as a standalone package. These customers need special handling Setup Steps

32. Debug Trace • Standard CQ Diagnostic Trace Available • Additional EmailPlus Debug output can be enabled by setting environment variable EMP_DEBUGOUT_LEVEL before starting client • Set 0 = Off • Set 1 = Routine Entry Trace • Set 2 = Routine Entry & Exit Trace • Set 3 = Detailed Trace

33. Debugging Steps - 1 • Verify Installation & Configuration Completed • Can't See / Create EmailPlusConfig record • Check EmailPlusAdmins group membership / DB Subscription • Doesn't Send Emails • Do they have at least one rule and a template • Are they Using SMTP DIRECT or CQMAIL transport modes • Is the SMTP server reachable from the client (ping) • Can You Telnet to the SMTP server • telnet <<server name>> 25 • 25 is the default SMTP port • Try a very simple rule e.g record submitted or record modified • Or something equally simple the customer is happy with • Use a very simple template

34. Debugging Steps - 2 • Are they using SMTP Relay Mode • Is the VB Relay Component running? – is it reachable? • Is it configured to be listening on the same port as the EmailPlusSiteConfig record says • Do you see any logging information in the VB App log window • No – Then the problem is at the sending end • Yes – Then the problem is the SMTP server access from where the VB Relay component is running

35. Are they Using Post Office Mode? Are there any EmailPlusPostOffice records? No - then rules aren't firing Yes – then the VB Relay Component isn't running or isn't configured correctly Hasn't reached a poll interval timeout – check timeout value Can't send to SMTP server Debugging Steps - 3