Creating custom reports with BIRT and Rational Team Concert: Part 1. Basic reports

IBM® Rational Team Concert™ can help software development teams store and organize an enormous amount of information, including work plans and tasks, builds and tests, and source code and other files. This article demonstrates how to visualize that information with custom reports by using Rational Team Concert with Eclipse Business Information and Reporting Tools (BIRT).

Tim McMackin (tmcmack@us.ibm.com), Software Engineer, IBM

Photo of Tim McMackinTim McMackin is a technical writer for IBM Rational software in Raleigh, North Carolina. He has a background in writing for advertising technical products and has been with IBM since 2004.



25 May 2010

Also available in Chinese Russian Vietnamese

About this article

This is the first article in a three-part series. Part 2 will cover complex reports and nested data sets.

IBM® Rational Team Concert™ can help software development teams store and organize an enormous amount of information, including work plans and tasks, builds and tests, and source code and other files. With any repository of that size, visualization becomes an issue. How do you get a high-level view of the state of the projects that Rational Team Concert is tracking? Dashboards and work item queries provide ways to see this information, but for a more customizable view, Rational Team Concert supports custom Eclipse Business Information and Reporting Tools (BIRT) reports loaded directly into the Web client.

Figure 1. Sample report with a line graph
Defect Discover Rate graph

Rational Team Concert includes more than 50 predefined reports that show information about work items, builds, and the source control system, which you can access from the Reports tab of the Web client. If these reports don't show exactly what you want to see, you can create custom reports.

You can use custom reports to specify and format the information that you want with great precision. This article shows some of the basics of how to present specific information from your Rational Team Concert repository in the form of custom reports.

The people in my organization use custom Rational Team Concert reports in several different ways:

  • I often create a simple report rather than a work item query when I need to include information from many different sources. Dashboards can show multiple queries in this way, but the report offers greater flexibility.
  • Some areas use reports as part of meeting agendas. In this case, the report shows the work items that need to be discussed (such as blocking issues or recent updates), and this list guides the meeting.
  • We also use reports to track the long-term progress of our software products. In this case, the report retrieves information from all of the different areas that are associated with a product and shows how that product is progressing toward its long-term goal.

Objectives

This article is Part 1 of a three-part series. The articles that follow in this series discuss more advanced uses of Rational Team Concert and BIRT reports.

This article covers these topics:

  • Installing and configuring the Rational Team Concert server and client and the BIRT report editing tools
  • Retrieving information from the Rational Team Concert repository into a simple BIRT report
  • Uploading report templates to the Rational Team Concert server and creating reports from those templates

Prerequisites

This article series assumes basic familiarity with the Rational Team Concert Web client or Eclipse client, particularly creating and querying work items. It focuses on work items because those are usually the area of information that illustrates the state of a project. However, the techniques covered in this article apply to many other types of information in the repository, such as test results, build results, and source control data.

To follow this article, you need a free account on Jazz.net and the full or trial versions of Rational Team Concert server and Rational Team Concert client. If you do not have a server and client, the instructions describe how to get a trial version of the server and a free version of the client.


How reports work and when to use them

Reports in Rational Team Concert are similar to work item queries, in that they both show you information about the repository according to the parameters that you specify. For example, if you click the Work Items tab in the Rational Team Concert Web client, you can see a list of predefined queries that show information about work items. You can click the Create Query button to create a new query for work items with certain values in certain fields; you also specify which of the work items' fields to show in the output. Fundamentally, reports work the same way: you specify the input parameters for the report and how the output is formatted. Creating a report is more time-consuming than creating a work item query, but reports offer much more flexibility than work item queries:

  • Rational Team Concert uses reports that you create in the WYSIWYG BIRT report editor, which gives you much greater control over the format of the output. Unlike work item queries, reports can show custom-structured tables, charts, styles, labels, and images. You can also use reports to code interactive elements, such as drop-down menus, expandable and collapsible sections, and other JavaScript-driven events.
  • Reports can show information about many different areas of the Rational Team Concert repository that work item queries cannot, including builds, source control, users, and team and project areas. You can also cross-reference the information from one area with the information from another.
  • You can specify parameters in reports to change values at run time. In this way, you can create multiple instances of one report and set different parameters for each instance, thereby creating different reports for different circumstances from the same report design file.
  • Queries can show information only about the current state of the repository, such as how many new or unassigned work items are in a certain team area right now. Reports have access to historical information in the repository as well as the current information, so they can show information about how many new work items were created on a certain date, for example.

Install the server, client, and BIRT editor

If you already have a Rational Team Concert server running, you can use that instance safely when you are experimenting with reports, because reports never change the data on the server. You must get permission from the server administrator to upload reports to the server, as described later in this article. If you want to use an existing instance of Rational Team Concert server, skip to Install the Rational Team Concert client.

Install the trial version of Rational Team Concert server

If you don't have an instance of Rational Team Concert server, you can download a free 60-day trial version from jazz.net:

  1. Download and decompress the Enterprise edition of Rational Team Concert server from jazz.net (see the Resources section).

In version 2.0 and later, Standard and Enterprise are the only editions that include full BIRT reporting support. There are many different files available for each release of Rational Team Concert, so be sure to get the correct one for your needs:

Edition: Enterprise
Platform: Microsoft® Windows® or Linux®, as appropriate
Architecture: x86 for most computers; x86-64 only for 64-bit operating systems
Installation style: .zip file

If you are using Windows, the file to download will have a name like "RTC-Enterprise-Server-2.0.0.2-Trial-Win32.zip."

Figure 2. Versions of the Rational Team Concert server that are available for download (Enterprise edition, Windows version discussed in this article is highlighted).
List of server versions
  1. In the server folder, on Windows, run the server.startup.bat file. On Linux, run server.startup with root privileges.
  2. In a Web browser, open the location of the Rational Team Concert server setup wizard:
    https://serverlocation:9443/jazz/setup

Note:
Use the location of your server as serverlocation. If the server is running on the same computer as the Web browser, you can use this URL:https://localhost:9443/jazz/setup

  1. Sign in as ADMIN with the password ADMIN.
  2. Click Fast Path Setup.
  3. Click Tomcat User Database.
Figure 3. Select the user database.
Tomcat user database selected as Type
  1. Fill in your user information as the administrator. You can add other users later.
  2. Select the check boxes to give your administrator account Contributor and Developer licenses.
  3. Select the check box to disable the default ADMIN account. From this point forward, you will use your own account rather than the ADMIN account that you used to log into the server.
  4. Click Next.

The next step in configuring the server is to create a project area in which to store your work.

  1. Click Create a Project.
  2. Under Active Project Areas, click Create Project Area.
  3. Give the new project a name and summary.
  4. Click Deploy predefined process templates and wait until you see a list of templates under Available Process Templates.
  5. Select Simple Team Process.
  6. Under Members and Administrators, add yourself as a member and as an administrator of the project.
  7. At the top-right of the page, click Save.


Now you have a project area and a few sample work items. You can create more work items and team areas to create some sample data to work with in your reports. For more information on working with Rational Team Concert in this way, see the Rational Team Concert help.

Install the Rational Team Concert client

As with the server, you can use an existing Rational Team Concert client on your computer or download one for free from jazz.net. However, you must use a version of the Rational Team Concert client that matches the version of the Rational Team Concert server. So if you are using Version 2 or later of the Rational Team Concert server, make sure that you use Version 2 or later of the Rational Team Concert client. If you are using Version 1 of the server, use Version 1 of the client.

Also as with the server, there are several different files available for download. The easiest way to get the Rational Team Concert client is to download the .zip file version that is labeled "Client for Eclipse IDE," because it requires no configuration beyond decompressing the file and running the eclipse.exe file. Alternatively, if you want to add the Rational Team Concert client to an existing instance of Eclipse on your computer, you can use the Installation Manager version.

Figure 4. Versions of the Rational Team Concert client that are available for download
'Windows x86' outlined for emphasis

Install BIRT into the Rational Team Concert client

The BIRT tools provide a WYSIWYG editor for you to work with reports in the Rational Team Concert client and upload them to the Rational Team Concert server. (BIRT is included in the Standard and Enterprise versions of Rational Team Concert server. Therefore, in most cases, you do not need to do anything to enable reports on the server.)

  1. Open the Rational Team Concert client. The first time that you run Rational Team Concert, it prompts you to select a workspace, which is the folder on your computer where Rational Team Concert stores the files you create.
  2. Click Help > Software Updates.
  3. Under the Available Software tab, expand Ganymede Update Site and select Charting and Reporting.
Figure 5. Installing BIRT
Software Updates and Add-ons window
  1. Click Install and follow the wizard through accepting the license agreement and installing BIRT.
  2. When BIRT is installed, you will be prompted to restart the Rational Team Concert client.

When the Rational Team Concert client restarts, you are ready to connect the client to the server:

  1. In the Rational Team Concert client, open the Work Items perspective.
  2. In the Team Artifacts view, click Connect to Project Area.
  3. Click Create a new repository connection, and then click Next.
  4. In the URI field, enter the location of the Rational Team Concert server. If the server is running on the same computer as the client, use this URI:
    https://localhost:9443/jazz
  5. Enter the user ID and password of the user that you created when you set up the server, not the admin user credentials that you used when you first logged in.
  6. Optionally, type a name for the server connection.
Figure 6. Connect the Rational Team Concert client to the server
Jazz Repository Connection dialog window
  1. Click Next.
  2. Select the check box next to the project area, and then click Finish.

Give yourself permission to upload reports

Even if you added yourself as an administrator to your own Rational Team Concert server, by default you do not have the necessary permissions to upload reports. To upload reports to the server, you need to give reporting permissions to one of the process roles that are assigned to you or have an administrator assign those permissions to you.

  1. Open the Jazz Administration perspective.
  2. In the Team Artifacts view, right-click the project area and then click Open.
  3. Under the Overview tab, in the Members section, select your user ID and ensure that you have at least one process role assigned to you, such as Team Member. To assign a role to a user, select that user, click Process Roles, and use the Edit Process Roles window to assign one or more roles.
  4. Save the process configuration.
  5. Under the Process Configuration tab, expand Team Configuration and click Permissions.
Figure 7. Setting the permissions
=Configuration options for the Project Area
  1. In the table of roles and permitted actions, select a role that is assigned to you, such as Team Member, or select Everyone to give the permission to everyone.
  2. Under Permitted Actions, select Reports.
Figure 8. Set permissions for reports
Permitted actions section
  1. Save the project area configuration.
  2. On the Overview page, right-click your user name, either in the Members section or the Administrators section, and then click Open.
  3. In the user editor, under Repository Groups, select the check boxes next to JazzAdmins and JazzDWAdmins.
  4. Save the user profile.

(Optional) Deploy the predefined report templates

The predefined report templates are not installed by default on the Rational Team Concert server. Follow these optional steps to deploy the predefined report templates to the server.

  1. In the Team Artifacts view, right-click the project area and then click Open.
  2. Under the Links tab, expand Reports, right-click Report Templates, and then click Deploy New Templates.
  3. In the pop-up window, select your project area and click OK.
  4. In the list of reports, click either Select All to deploy all of the report templates, or select individual report templates, and then click OK.

Now these report templates are available on the Reports tab of the Web client. You can click Create Report and then choose a template from which to create the report. In this way, you can use these templates as a starting point for your own reports or to see examples of what is possible with reports.


Create a simple report

The report that you create in this section isn't very complicated or interesting, but it illustrates the process of creating reports and uploading them to the server. When you add more information to the report later in this example, you will see more of the value of reports in Rational Team Concert.

This simple report mimics a work item query in Rational Team Concert; it lists the work items in the repository.

Create a data source

As the name suggests, the data source is a connection to the source from which the report retrieves data, such as a server, database, or file. In this case, you create a data source that retrieves data from the work items in the repository.

  1. Open the Report Design perspective. If you do not have the Report Design perspective, BIRT tools are not installed in your instance of the Rational Team Concert client (see "Install BIRT into the Rational Team Concert client").
  2. Create a project by clicking File > New > Project, expanding General, double-clicking Project, and filling in a name for the project, such as MyReports. You can put BIRT reports into any type of project.
  3. In the Navigator view, right-click the project and then click New > Report.
  4. Give the report a name with the extension .rptdesign, such as workitems.rptdesign, and click Finish.
  5. In the Data Explorer view, right-click Data Sources and then click New Data Source. The New Data Source window shows a list of the types of sources from which BIRT can retrieve information.
  6. Click Jazz Data Source and give the new data source a name, such as Work Items.
  7. Click Next.
  8. Select your Rational Team Concert server and project area.
  9. In the Enter snapshot list, select WORKITEMS_SNAPSHOT.


Rational Team Concert stores data in several separate categories called snapshots. Each snapshot stores a different type of data. The most commonly used snapshots for reports are the WORKITEMS_SNAPSHOT, which stores information about work items, and the COMMON_SNAPSHOT, which stores information about users and team areas. In this way, you might need to work with multiple data sources in the report, one for each snapshot that you want to access, but all of the data is coming from the same Rational Team Concert repository.

As you will see later, each snapshot contains several tables, each with different information about that type of data. For example, the work items snapshot contains a table of the work items themselves, but it also contains tables of information about the valid states and types of work items, as well as tables that record historical information about the changes to work items.

Figure 9. Select the snapshot for the data source
Snapshot Information window
  1. Click Finish.

Create a data set from the data source

Data sets are result sets of data that BIRT retrieves from the data source. In the case of Rational Team Concert reports, BIRT is retrieving data either directly from the Rational Team Concert repository or from an intermediate repository called the data mart. This distinction will be explained later in the series. In this context, data sets are just like the results from the work item queries that you create in Rational Team Concert. (If you are familiar with SQL, you can also think of a data set as the result set from a SELECT statement.)

When you create a query in Rational Team Concert, you specify three pieces of information:

  • The table from which to retrieve the information.

    When you create a query in the Rational Team Concert Web client, Rational Team Concert assumes that you are searching for work items, dashboards, or build results, depending on the page from which you start the search. However, when you create a data set in BIRT, you must specify whether the data set contains work items, project areas, build results, or other information from the repository.

  • The input parameters or criteria for the query.

    For example, you can search for work items that belong to a certain person. You could also retrieve only work items in certain iteration, of a certain type, or with a certain status.

  • The output information for the query.

    If you are searching for work items, you don't want every piece of information about each work item. Therefore, you filter the information to a few fields that you are interested in, such as the ID number, summary text, team area, and owner.

Figure 10. Create a work item query for comparison
Work Item Query view

In this way, a data set in BIRT is just like the information that Rational Team Concert returns from a query: a table of data that is a subset of the information in the repository.

Figure 11. The results of a work item query
Table display of results

The difference between queries in Rational Team Concert and data sets in a BIRT report is that data sets allow much more flexibility. In the Rational Team Concert Eclipse client and Web client, you can run only one query at a time. But in a BIRT report, you can create as many data sets as you want. Data sets also offer much more control than Rational Team Concert queries.

The following steps show you how to create a simple data set of work items. This data set is no more complicated or useful than a Rational Team Concert query, but later, you will see how data sets offer more control than Rational Team Concert queries.

  1. In the Data Explorer view, right-click the Data Sets folder and then click New Data Set.
  2. Under Data Source Selection, select your data source.
  3. Under Data Set Type, select Jazz Data Set.
  4. In the Data Set Name field, type a name for the data set, such as Work Items.
Figure 12. Create a data set
New Data Set window
  1. Click Next.
  2. Under Enter Table Name, select the LIVE_WORKITEM_CNT table.

This table contains the live list of work items from the repository, so it is the table that you will use most of the time when you want information about work items. Some of the other tables in this list contain historical information about the work items; for example, the NEW_WI_COUNT table contains counts of new work items per day. Some of the tables in the list contain information about the various types, states, categories, severities, and priorities to which work items can be assigned. There are also several tables in this list with names beginning with WS_ or WC_. These tables contain very specific data about attributes on the work items and are generally not needed in reports.

  1. Under Select columns, select the columns to show in the output of the data set. In this case, select the most important characteristics of the work item: WI_ID (the ID number of the work item), SUMMARY, CONTRIBUTOR_NAME (in this context, "contributor" means "owner"), and WI_TYPE (the type of work item, such as task or defect).
  2. Under Select parameters, select the input parameters for the query. You will specify values for these parameters later. In this case, select the CONTRIBUTOR_USERID field so that you can retrieve only the work items that are associated with a certain owner. You can add more input or output columns to this data set later.
Figure 13. Select the information to show in the data set.
Lists of options: table name, column, parameters
  1. Click Finish.

The new data set appears in the Data Explorer view, and the data set editor opens so that you can make other changes to the data set. You will learn more about the options in this editor later. For now, enter the value for the input parameters:

  1. On the Parameters tab, select the CONTRIBUTOR_USERID parameter and then click Edit.
  2. In the Default Value field, enter a user ID in the repository, such as "jdoe" (including the quotation marks).
Figure 14. Set the parameter for the data set.
Edit Parameter window
  1. Leave the rest of the fields set to the default values, and click OK.
  2. Click the Preview Results tab.

If you are connected to the Rational Team Concert server, this tab shows the resulting data set. This preview tab is useful to make sure that you are getting the data that you expect before you load it into the report. The preview tab can also be useful to inspect the data in the repository. For example, if you are not sure what information is contained in a certain table, you can create a simple data set, such as the example in Figure 15, and quickly see the contents of the table under the Preview Results tab.

Figure 15. Preview the data set.
Edit Data Set view shows Preview Results view
  1. Click OK. A warning message reminds you that you did not fill in a value for the RESULT_SET_SIZE parameter. (BIRT adds this parameter to every data set automatically so that you can specify a maximum number of results in the data set. You can delete the parameter if you want to suppress this warning message.) You do not have to fill in a value for every parameter and, in some cases, you need to leave parameters blank so that you can pass values to the data set at run time.
  2. Click OK to dismiss the warning.
  3. Drag the data set from the Data Explorer view to the report editor. Figure 16 shows how the data set appears as a table on the report.
Figure 16. The table of data on the report
The data set as a table in the report
  1. Click the Preview tab at the bottom of the editor (see Figure 17). Like the preview tab in the data set editor, the preview tab in the report editor shows what the report will look like with the data from the repository. When you are finished previewing the report, click the Layout tab to resume editing the report.
Figure 17. Preview the report
The preview tab of the BIRT edito

Note:
When you preview a report this way, the report editor saves the report automatically.


Upload the report to the Rational Team Concert server

To use the report with Rational Team Concert beyond this preview mode, you must upload a copy to the server.

  1. Open the Jazz Administration perspective.
  2. In the Team Artifacts view, expand your project area and then expand the Reports folder.
  3. Right-click the Report Templates folder and then click New > Report Template.
  4. Give the new report a name and an identifier. The name is the label that will appear in Rational Team Concert; the identifier is a unique ID for the report that you will need later if you want to link to the report. For example, you might name the work items report that you created in the previous section My work items and give it the identifier report.myworkitems.
  5. In the Sharing section, select a project or team area for the report. This option helps you categorize reports according to team areas, but for now you can assign the report to the project area.
  6. If you want other people to be able to use the report, select the Sharing check box.
  7. Under Contents, click Browse and select the report file.
  8. Clear the Supports Data Caching check box. (This check box, and how Rational Team Concert handles data caching, will be explained in a later article.)
Figure 18. Upload the report to the Rational Team Concert server
Report Template Properties view
  1. Click OK.
    Note: If you have entered all of the information into this window and the OK button is disabled, click the Browse button in the Sharing section and select your project or team area again and the button will be enabled.
  2. In the Report Templates folder in the Team Artifacts view, right-click the report template that you just added and then click Create Report.

Rational Team Concert uses your report design file as a template for one or more reports. Later, you will see how you can create multiple reports from a single report template by specifying different parameters in each report.

  1. In the Select a Folder window, specify where to store the report and click OK. In general, put reports that you intend to share in the Shared Reports folder and reports that are not shared in the My Reports folder. You can create folders and organize the reports in the Team Artifacts view.
  2. Open the Rational Team Concert Web client to the Reports tab. Your new report appears on the left side of the page.
  3. Click the report to load it.
Figure 19. The finished report on the Web client
The report is listed on the Reports tab

These steps might seem like a lot of work for a simple table with rudimentary formatting, but in the next article in this series, you will see how the reports provide much more flexibility. Reports allow you to use much more sophisticated logic on the data from Rational Team Concert, such as cross-referencing data from different areas of the repository and changing the report with parameters that users specify at run time.


Acknowledgements

The author is grateful to Rational Team Concert developers James Moody and Rafik Jaouani for their advice on this article and for the very helpful information that they provide on jazz.net and the jazz.net forums.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=490737
ArticleTitle=Creating custom reports with BIRT and Rational Team Concert: Part 1. Basic reports
publish-date=05252010