Reports in Automatically Generated Dashboards

It’s easy to add reports to your personal dashboards in Rational Team Concert using the web interface. Report widgets give you a quick view of project history without having to pull up individual reports. You can get a side-by-side view of historic activity in small widgets that show you the same information you’ll see in the full-sized report.

On your dashboard, just click on the widget control, the screen opens to show you a bunch of cool reports and views, and you select the one you want. Enter in a couple of parameters if necessary, and you’re good to go.

Not so fast. What if you want to make those dashboards available to everyone on your team when they join your project? You might want to place useful reports on everyone’s personal dashboard so everyone on the team can see the same progress information.

That means you’ll need to add the dashboard reports to a dashboard defined in the RTC project description (or process template). You do this in the Project Configuration section of the project description.

In the RTC Dashboard editor, You need to identify each dashboard, page, and widget separately. Oh, you’ll need to identify each report parameter separately too. And another thing: each parameter has a name/value pair that you need to enter separately.

This only sounds difficult. In fact, it’s tedious.

You get to do all this in a little window with no copy/paste or drag/drop capability. The result is that you repeatedly create identical key value pairs over and over. It’s good for an entertaining game of Let’s Get Carpal Tunnel Syndrome.

Sound fun? Let’s get started!

Truthfully, I’m being a little hard on the dashboard template UI. To be fair, it’s not too difficult once you understand the basics.

In this article we’ll edit a Scrum project, but you can use the process described below to edit any type of project or process template.

First, create a Scrum project from the Scrum template. I’m using RTC 4.0.1 RC1, but any 4.x version should work.

After the project is created, open your project area and select the Process Configuration tab. Drill down into Project Configuration > Configuration Data > Dashboards > Dashboard Templates.

Let’s look at an example of what you’ll want to do. Open ${scope} (project) > General (page), then open the second column. Then open Release Burndown (viewlet) > (memento) > parameters (property) > (memento). You’ll see two more properties called “name” and “value”.

Release Burndown is the name of the report widget. A memento is a generic envelope that holds properties and other mementos. The first thing we see in this first memento is the parameters property, followed by all the parameters used by the report, packaged inside of mementos. Each parameter memento has two properties, otherwise known as a name/value pair. Hence the labels “name” and “value”.

Quick quiz: which property holds the name of the parameter? If you said “name”, you’re correct!

Select the name property. You’ll see that it’s name is “name”, it’s of type String (because the name of a parameter is always a string), and the value is ProjectAreaName. In other words, this property tells RTC that we’re referring to the ProjectAreaName parameter of the report.

Select the value property. The name is “value”, the type is String, and the value is ‘{Current Project Area}’ (including the single quotes).

All this is just another way of saying that the parameter ProjectAreaName in the report is getting the value ‘{Current Project Area}’. As you’ve already guessed, this particular paramater is telling the dashboard that the project area used in the report will be the project area that the dashboard belongs to.

Now you’ll create your own report in a dashboard template. We’ll focus on a contributor’s dashboard, so open ${scope}’s Dashboard (contributor) > General. Each new contributor who joins the team gets this dashboard created for them as their initial personal dashboard.

Now you’ll add a new report to the 3rd column of the General page in the personal dashboard template. Select the third column under ${scope}’s Dashboard, then select the Add viewlet link. Next to the Identifier field, select Browse.

Select the Report viewlet. The identifier of the viewlet is added, but you can define your own title, trim color, background, etc. Enter New Work Items in the Title field.

You’ve got the identifier of the viewlet, but you still need to enter the identifier of the report so the viewlet knows what report to display. You can find a list of reports in the Change and Configuration Management Reports page of the Infocenter. Your best bet is to select a report that starts with the word “Micro…”. These reports are designed for dashboard viewlets. For this example you’ll want Micro New Work Items By Severity.

Now that you know the report, we need to get the ID of the report. Here’s where you might need to start using your intuition.

The report you chose is based on workitems (see the Resources column in the Infocenter page you linked to above). RTC has standard internal names for these reports. So the Micro New Work Items By Severity report is called workitems.MicroNewWorkItemsBySeverity. Add that name to the Report field on the Perferences tab of the viewlet.

Currently the Query field also shows as being a required field but this is a bug. No query is required.

How did we intuit the ID of the report? Magic! Not really. This is the standard format for the report IDs. So if a report is called “Battlestar Galactica”, and it displays work items, then the report ID will probably be workitems.BattlestarGalactica. And in more recent versions of RTC you can get the ID directly from the viewlet on a dashboard (see Method 1 below).

You’re almost there! Now all you have to do is the hard part.

You’re probably wondering how you’re going to find out all the arcane information about your report like the ID (if you can’t intuit it), the parameters, the parameter types, etc.

The first time I tried this was with RTC 4.0. At that time there was no easy way to find out what the parameters are called for a viewlet report. But I recently installed version 4.0.1 RC1, and now there’s an easier way to do this. Let’s look at a few different methods of doing this.

Method 1

If you’re like me and you’d rather exercise your talent for loafing instead of introspecting dashboard viewlets, then use this method. I know it works under RTC 4.0.1 RC1, but this method may not be available in earlier releases.

Go to a dashboard in the web interface that you’re allowed to edit (or create a new one). Open the Add Widget palette, and add the Custom Report widget to the dashboard. Or, go to a report widget on an existing dashboard that displays a report you want to add to your dashboard in the project description.

If necessary, configure the report widget to show the report whose parameters and ID you want to see. In this case, it’s Micro New Work Items by Severity.

Now click on the menu in the upper right corner of the widget and select Export. You’ll be asked for the size of the widget – just select Next.

And now you can see a code snippet that contains the ID and parameters you need (along with a lot of other information). I highlighted the parameters and the report ID here:

Method 2

This method involves using the Firefox Firebug extension to reverse engineer the parameters from the dashboard viewlet. This wiki page describes how to do it.

Use this method if you don’t have the Export option from Method 1 available. Or if you’re a masochist.

Secret Method 3

Before the Export option was available, I developed a scientific methodology for uncovering the mysterious parameters. I call it “guessing”.

If you look at the dashboard template called ${scope} (project), and open the second column under the General page, you’ll see two reports: Release Burndown and Team Velocity. For each of these reports, open the <memento> parameters section. You’ll see a number of mementos underneath with the name/value pairs that represent the report parameters. Both reports have at least the following parameters in common:

    • ProjectAreaName: ‘{Current Project Area}’
    • TeamAreaName: ‘’
    • ProjectAreaName1: ‘{Current Project Area}’
    • Interval: ‘’
    • Zoom: false

Decades of experience leads me to believe that these parameters are good candidates for every report viewlet. Most people wouldn’t need decades of experience to figure this out.

So if you add these parameters to your dashboard viewlet you’ll probably be OK. You can also look at other report viewlets in the dashboard templates for more clues. Yeah, it’s tedious. But at least it’s not rocket science.

So we have a few methods of deriving the report ID and parameters. Now all we have to do is add parameters to the viewlet in the dashboard template. You have to do all this manually – there is not cut/paste or drag/drop within this view. It’s all about creating mementos and properties.

Create a memento by right-clicking the New Work Items viewlet and selecting Add Memento. Then right-click on the memento and select Add Property. Give the property the name “parameters”, and a type “String” (without the quotes)

Now right-click on your parameters property and create one memento for each parameter you will need. Under each of these mementos, create two properties: one called “name” and the other called “value” (without the quotes). It should look like the name/value pair properties from the image earlier in this blog post.

Make the type of every “name” parameter a String. The value of each “name” parameter should the the name of the parameter that you discovered using the methods above.

So far, the type of every “value” parameter I’ve created for a dashboard report is String, so you’re pretty safe sticking with that. And the value of the “value” parameter is derived from one of the methods described above. Of course, your mileage may vary depending on the type of report you’re using.

And that’s it! Easy peasy.

I’d expect this to get easier in the future. But even if it doesn’t, you probably won’t create dashboards with lots of reports. Dashboards with a lot of widgets lose their value by making it difficult to understand what questions you’re trying to answer. It’s best to keep a dashboard page focused on a specific questions you need to answer like:

    • “Is my project on-track for delivering what we promised this iteration?”
    • “What are the significant problems I’m dealing with this iteration (what needs my attention?”
    • “How does this iteration compare with our progress and promises in other iterations?”
    • etc.

Good luck!

This entry was posted in Uncategorized and tagged , , . Bookmark the permalink.

1 Response to Reports in Automatically Generated Dashboards

  1. dtoczala says:

    Nice post on an area of RTC that is not well understood. Setting up simple and information loaded default dashboards helps users adopt the tools more quickly. Since most of those users are not “software types”, this can be more important than most people realize.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s