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:
Here's a sample RSS feed that would be generated:
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.
Creating the Perl Script
To create an RSS feed, two arguments to the Perl script are required:
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:
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:
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
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:
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:
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.
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.