Generating an RSS Feed from ClearQuest Change Requests


The preceding chapter discussed how you can subscribe to a CruiseControl RSS feed to monitor a project's build results. This is just one example of how RSS feeds can be used to facilitate reporting on your build and release process. Since RSS feeds are relatively simple to construct, you could additionally use this capability in a number of other ways. For example, you could create an RSS feed of the latest files checked in to ClearCase or the latest change requests submitted to ClearQuest. This section describes how to programmatically create an RSS feed on the latest submitted ClearQuest change requests. It builds on the capabilities discussed so far for Perl and the ClearQuest API.

A Sample RSS Feed

To generate any RSS feed, first you must decide what information you want to convey. In our example, the requirements for the RSS submitted change requests feed are as follows:

  • The list of the 20 most recently submitted change requests will be maintained.

  • The change request name, its submitter, submit date, and headline will all be included in the feed.

  • Each change request will also include a link to allow it to be navigated to in the ClearQuest Java web.

  • The feed will be generated hourly and the last generation date stored.

Here's a sample RSS feed that would be generated:

[View full width]

<?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:blogChannel="http://backend.userland.com/blogChannel Module"> <channel> <title>ClearQuest Submissions Feed</title> <link>http://localhost:8080/CQWeb/login.jsp</link> <description>Feed of 20 most recently newly submitted ClearQuest change requests</description><language>en-us</language> <lastBuildDate>28/01/06 14:36:41</lastBuildDate> <item> <title>RBPRO00000023 [EnhancementRequest]</title> <link>http://localhost/cqweb/main?command=GenerateMainFrame&service=CQ&schema=7.0. 0&contextid=RBPRO&entityID=RBPRO00000056&entityDefName=Defect</link> <description>Changed Bank initialization parameter </description><author>alex</author> <pubDate>2006-01-22 09:23:01</pubDate> </item> ...


The majority of the content for this RSS feed can be retrieved from ClearQuest using its API, similar to how the release report was constructed in the preceding section. In fact, the majority of Listing 8.5 can be used; the only difference is that in this example the change requests are not associated with any particular release. The remainder of the content and the formatting of this example can be implemented using a Perl RSS library. One such example is XML::RSS:: SimpleGen, which is available at http://search.cpan.org/~sburke/XML-RSS-SimpleGen-11.11. It is used in this section.

Installing and Using Third-Party Perl Modules with ClearQuest

The ClearQuest Perl distribution comes with a large number of existing modules. However, if the one you require is unavailable (as in this case), download it to a standard directory, such as X:\PerlLibs. Then reference this directory in your script with the use lib directive, such as use lib X:\PerlLibs. An example is given in Listing 8.6, shown in a moment.


Creating the Perl Script

To create an RSS feed, two arguments to the Perl script are required:

  • The date the feed was last generated

  • The name of a file to write the feed to

The date the feed was last generated is required so that all the ClearQuest change requests submitted since that date can be retrieved using a ClearQuest API query:

my @submitted = ("$submit_date"); my $where = $queryDefObj->BuildFilterOperator($CQPerlExt::CQ_BOOL_OP_AND); $where->BuildFilter("Submit_Date", $CQPerlExt::CQ_COMP_OP_GT,\@submitted);


This requires that you have a Submit_Date field in each of your change request entity types in your ClearQuest schema. If some of your entity types do not have this field, create a new DATE_TIME field called Submit_Date and create an initial value hook script that sets this field to the current date:

$entity->SetFieldValue($fieldname, &GetCurrentDate);


With this information, all the newly submitted change requests can be found and added to the RSS feed as items.

To generate an RSS feed, you must first generate a channel. This is a description of what the feed contains; it also has a link to its Web site if required. To make matters confusing, RSS comes in several different versions0.9x, 1.0, and 2.0most of which are incompatible. To make matters simple, I will generate the same version of RSS as that of CruiseControl in the previous chapter2.0. To create an RSS channel with the XML::RSS::SimpleGen library, you simply call the channel method with the attributes you want to define for the channel:

[View full width]

my $url = qw<http://localhost/cqweb/login>; rss_new($url, "ClearQuest Submissions Feed", "Feed of $max_items most recently submitted ClearQuest Change Requests"); rss_item_limit($max_items);


You can use a number of other attributes (they are defined in the RSS 2.0 specification; see http://blogs.law.harvard.edu/tech/rss). However, these attributes will suffice for our purposes. Once you have created the channel, you can add new items to it as and when required:

rss_item(   "http://localhost/cqweb/main?command=GenerateMainFrame& .   "&service=CQ&schema=7.0.0&contextid=RBPRO&entity&entityDefName=" . $type,   $id . " [" . $type . "]",   $headline );


In this example, the values of the attributes are hard-coded; however, the same information can be retrieved from ClearQuest using its API. Listing 8.6 shows a complete example of a Perl script to generate an RSS feed of submitted change requests.

Listing 8.6. Perl cq_rss_report.pl File

[View full width]

use lib "C:\\Views\\JavaTools_int\\JavaTools\\libs\\perl"; require CQPerlExt; use XML::RSS::SimpleGen; my ($submit_date, $rss_file) = @ARGV; if ((@ARGV != 2) or ($submit_date eq "") or ($rss_file eq "")) {     die("Error: invalid date or rss file specification.\n"); } my $history_file = "rss-history.dat"; my $max_items    = 20; my $debug        = 0; my $url = qw<http://localhost/cqweb/login>; rss_new($url, "ClearQuest Submissions Feed", "Feed of $max_items most recently submitted  ClearQuest Change Requests"); rss_item_limit($max_items); # does the history file exist? if (-e $history_file) {     # YES, load it     rss_history_file($history_file); } # execute the ClearQuest query my $sessionObj = CQSession::Build(); $sessionObj->UserLogon("admin", "password", "RBPRO",""); my $queryDefObj = $sessionObj->BuildQuery("all_change_requests"); $queryDefObj->BuildField("dbid"); $queryDefObj->BuildField("id"); $queryDefObj->BuildField("headline"); $queryDefObj->BuildField("Submit_Date"); $queryDefObj->BuildField("record_type"); $queryDefObj->BuildField("Submitter"); my @submitted = ("$submit_date"); my $where = $queryDefObj->BuildFilterOperator($CQPerlExt::CQ_BOOL_OP_AND); $where->BuildFilter("Submit_Date", $CQPerlExt::CQ_COMP_OP_GT, \@submitted); my $resultSetObj = $sessionObj->BuildResultSet($queryDefObj); $resultSetObj->Execute(); while (($resultSetObj->MoveNext()) == $CQPerlExt::CQ_SUCCESS) {     $dbid = $resultSetObj->GetColumnValue(1);     $id = $resultSetObj->GetColumnValue(2);     $headline = $resultSetObj->GetColumnValue(3);     $date = $resultSetObj->GetColumnValue(4);     $type = $resultSetObj->GetColumnValue(5);     $user = $resultSetObj->GetColumnValue(6);     print("found record $id - $headline");     rss_item(         "http://localhost/cqweb/main?command=GenerateMainFrame&" .         "&service=CQ&schema=7.0.0&contextid=RBPRO&entity&entityDefName=" . $type,         $id . " [" . $type . "]",         $headline     ); } rss_save($rss_file); CQSession::Unbuild($sessionObj);

Based on the information already given in this chapter, this example should be relatively self-explanatory. However, a couple points to note are how the feed is kept to the last 20 items using the $max_items variable, and also how a link into the ClearQuest Java web is programmatically constructed using the following line:

"http://localhost/cqweb/main?command=GenerateMainFrame&" . "&service=CQ&schema=7.0.0&contextid=RBPRO&entity&entityDefName=" . $type,


This allows the user to read the summary of the feed and then navigate from the feed to the ClearQuest record (the user is prompted to log in if necessary). With this script in place, the next step is to create a mechanism for executing it; for this you could create a target in Apache Ant.

Automating Report Creation Using Ant

Any reports you frequently produce should be automated so that they are a natural side effect of the build process. If the report is a script that is executed from the command line, you can use Ant's exec task to invoke the script. In our example, a target to execute the Perl script from Listing 8.6 could be created as follows:

[View full width]

<property name="dir.webhome" value="C:\Program Files\Apache Software Foundation\Tomcat 5.0 \webapps\ROOT\ratlbankmodel"/> <target name="update-rss"> <property file="rss.properties" prefix="rss"/> <echo>RSS feed last updated at ${rss.date}</echo> <exec executable="ratlperl.exe" error="error.txt"> <arg value="etc/clearquest-rss_report.pl"/> <arg value='"${rss.date}"'/> <arg value='"${dir.webhome}/clearquest-changes.rss"'/> </exec> <propertyfile file="rss.properties" comment="ClearQuest RSS feed properties"> <entry key="date" type="date" value="now" pattern="dd/MM/yy HH:mm:ss"/> </propertyfile> </target>


In this example, a target called update-rss is created; it maintains a property file called rss.properties that contains the date the last feed was executed. When this target is executed, it reads the date property from this file and executes ratlperl.exe, passing the script from Listing 8.6 and the date property. It then updates the property file with the current time. The output of the script is sent to the file clearquest-changes.rss. This file should be available somewhere on your intranet so that a user can navigate to it and subscribe to it. In this example I have placed it in a directory of the Tomcat server.

Subscribing to the Feed

Once the feed has been generated, you can subscribe to it using an RSS aggregator tool. To achieve this using RSSReader, you select File, Add Feed, which brings up a screen similar to that shown in Figure 8.2.

Figure 8.2. Adding a new feed using RSSReader


In the URL for the feed, you enter the full URL path to the feed that has been generated. In this example, it's as follows:

http://localhost:8080/ratlbankmodel/clearquest-changes.rss


After you add the feed, you see information on each of the items from the feed, as shown in Figure 8.3.

Figure 8.3. Displaying the latest headlines in a feed using RSSReader


If you click the Open in browser option for an RSS item, a browser opens, and you see the individual record in the ClearQuest web, as shown in Figure 8.4.

Figure 8.4. Displaying the record in the ClearQuest web


The aggregator tool monitors the RSS file, checking for any changes. If there are changes, it notifies you directly. In RSSReader's case, it displays a pop-up window in your system tray.

Automating Report Generation Using CruiseControl

If you wanted to schedule the execution of this report on a regular basissay, every houryou could also create a new project in CruiseControl to achieve this. Chapter 7, "CruiseControl Best Practices," described how to create a time-based schedule. I do not necessarily recommend creating a CruiseControl project for every report-generation activity, because this can quickly make your CruiseControl config.xml difficult to read. Instead, I recommend creating a single project for report generation that executes all the reports you need at the same time.

Further Customizations

This section has described a relatively straightforward generation of an RSS feed. This is really just the start; there are lots more possibilities. For example, you might want to create separate change request feeds for each project or release. Similarly, you might not want to generate feeds on change requests at all. Instead, you might want to generate a feed on the latest ClearCase elements or activities committed to the integration area, or the latest recommended UCM integration baseline or label that developers should use. Hopefully, the information in this chapter on interfacing with ClearCase, ClearQuest, and RSS will enable you to achieve customizations such as these.




IBM Rational ClearCase, Ant, and CruiseControl. The Java Developer's Guide to Accelerating and Automating the Build Process
IBM Rational ClearCase, Ant, and CruiseControl: The Java Developers Guide to Accelerating and Automating the Build Process
ISBN: 0321356993
EAN: 2147483647
Year: 2004
Pages: 115
Authors: Kevin A. Lee

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net