Creating customized reports through multiple project areas in Rational Team Concert

This article explains how to create customized reports, step by step through multiple project areas in Rational Team Concert for two roles, manager and developer so that they can act to insure good health of projects. This article uses mainly BIRT scripting and computed columns to show them necessary information for your own views. Files of sample reports are also provided.

Ken Kumagai (theken@jp.ibm.com), Software Engineer, IBM

author photoKen Kumagai is a software engineer at the Yamato Software Development Laboratory at IBM Japan. He works as a developer in the IBM Rational ClearCase MultiSite team. One of his current interests is how existing systems can work seamlessly with the Rational Team Concert and Jazz technology platform, based on Open Services for Lifecycle Collaboration (OSLC). In his spare time, he enjoys reading books at the nearest Starbucks coffee shop.



28 February 2012

Also available in Chinese Spanish

How reports help you check the health of projects

Seeing the information about projects from various angles is important for ensuring the good health of projects throughout software development. The information about a project in IBM® Rational Team Concert™ is collected and stored in the data warehouse as snapshots. A snapshot resembles a table in a relational database management system, and there are snapshots for such things as work items, builds, software configuration management (SCM). You can create reports to display this information from your favorite angles by using BIRT (see the "Data Warehouse Concepts" and "Data Warehouse Snapshot Schemas" links in the Resources section).

This article can help you keep your projects healthy by guiding you in getting useful reports, especially customized reports on work items, from your own perspectives. For this purpose, you'll consider the roles of developer and manager and customized reports for each role. Each role has its own responsibilities and needs support for certain actions.

  • Each developer belongs to teams and projects. A developer works on assigned work items to meet deadlines and requests approvals of work items by other developers to maintain the quality of the deliverables.
  • Each manager supervises projects and teams. The manager assigns work items to be finished by the end of specified iterations and balances the workload among the developers to avoid overloading any of them.

Techniques for reports are explained in a three-part series of articles titled "Creating custom reports with BIRT and Rational Team Concert" (see the Resources section for a link). This article focuses on how to create reports to show necessary information so that the person in each role can determine the health of projects by checking the reports.


Set up the environment to create reports

See "Creating and Deploying a New Report" on the development team's wiki on Jazz.net (see the link in Resources) for steps to set up the environment. To work through the steps in this article, you will need these versions of the following software:

  • Rational Team Concert 3.0.1
  • Eclipse framework and tools:
    • Eclipse Modeling Framework 2.5.0
    • Web Tools Platform 3.1.2
    • Data Tools Platform 1.7.2
    • Business Intelligence and Reporting Tools (BIRT) 2.5.2

Follow these steps to open the sample report files:

  1. Open the Report Design perspective. In the Data Explorer view, click the sample reports file, .rptdesign.
  2. Under the Data Sources folder, click each data source to open a dialog.
  3. In the Enter Repository and Enter Project Area panes, respectively, select your repository and project area.
    Note:
    If no repository and project area appear, check to be sure that repository connections are created and that you are logged in to project areas.
  4. Open the Work Items perspective.
  5. In the Team Artifact view, expand the Reports folder under your project area, and then right-click Report Templates to select New > Report Template.
  6. Click Browse in the contents pane, and select one of sample report files (rptdesign).
  7. Click OK.

Types of customized reports

This article explains how to report information by using three types of reports: tables, pie charts, and bar charts (the focus is primarily on information bound to the Live_Workitem_Cnt table).

Table reports
Tables show information about the work items listed by setting parameters. The first table report sets CONTRIBUTOR_ITEMID. The second table report sets APPROVAL_APPROVER_ITEMID. In addition, BIRT scripting makes it possible to define your own output columns.
 
Pie chart reports
Pie charts show information about the work items grouped by the values of the output columns. Rates for each group are shown by setting output columns to category definition and setting WI_COUNT to slice size definition. The first pie chart sets WI_SEVERITY, and the second pie chart sets WI_PRIORITY to category definition.
 
Bar chart reports
Bar charts show the numbers of work items by setting output columns to Category (X) series and setting WI_COUNT to Value (Y) series. The first bar chart sets CONTRIBUTOR_NAME, and the second bar chart sets APPROVAL_APPROVER_NAME to the Category (X) series.

Work item assignments and approval requests

The first table report shows unfinished work items assigned to each developer in order of deadline or priority (Figure 1). Developers can see it any time during the iteration to decide what work items to work on first.

deadline (data type: Date)
Defined at computed columns in Joint data set from Live_Workitem_Cnt and Iteration tables. deadline is DUE_DATE in Live_Workitem_Cnt table if it exists, and is ENDDATE in Iteration table if it does not exist. It's important to sort work items by deadline, especially, if DUE_DATE is earlier than ENDDATE because developers often plan to finish work items by the end of iteration, and then overlook the due date.
 
priority_label (data type: String)
Defined at computed columns in data set from Live_Workitem_Cnt table. priority_label stores human readable string such as high, medium, low converted from WI_PRIORITY with prefixes of numeric values that show smaller values as higher priority.

Five kinds of tables (listed in Table 1) are needed to create the report that Figure 1 shows. Report parameters at Project_Area, Live_Contributor tables are cascading parameters in this order.

Table 1. Tables used to report assigned work items
TableExplanation
IterationENDDATE is used for the computed column deadline (deadline is shown in report).
Live_ContributorSelected CONTRIBUTOR_ITEMID at report parameter is set to CONTRIBUTOR_ITEMID at Live_Workitem_Cnt.
Live_Workitem_CntWI_ID, SUMMARY, and PROJECT_AREA_NAME are shown in the table report.

DUE_DATE is used for computed column deadline.

Unfinished state is set to STATE_NAME.

priority_label at computed column is shown in report.
PriorityPRIORITY_ID and WI_PRIORITY are stored into variable priority_map (Default Value: new Object ()) as key and value respectively at script onFetch.

priority_map is used for priority_label at Live_Workitem_Cnt.
Project_AreaSelected PROJECT_AREA_ITEMID at report parameter is set to PROJECT_AREA_ITEMID at both Live_Workitem_Cnt and Live_Contributor.
Figure 1. Assigned work items in deadline order
six work items listed according to deadlines

The second table report shows work items where approvals are requested to each developer (Figure 2). Overlooking approvals might lead to blocking other developers if conditions of completing work items require approvals. Developers see this any time in the iteration to avoid overlooking work items where approvals are requested.

You need five kinds of tables to create the report shown in Figure 2 by replacing Live_Workitem_Cnt, Live_Contributor (Table 1) with Live_Workitem_Cnt, Live_Contributor (Table 2)

Table 2. Different tables to report approvals requested at work items
TableExplanation
Live_Workitem_CntSame as Table 1 except setting STATE_NAME.

Pending state is set to APPROVAL_STATE rather than setting STATE_NAME.
Live_ContributorSelected CONTRIBUTOR_ITEMID at report parameter is set to APPROVAL_APPROVER_ITEMID at Live_Workitem_Cnt.
Figure 2. Work items approval requests in order of priority
three work items list according to priorities

Unfinished work items in iterations

The first pie chart report shows unfinished defects in order of severity (Figure 3). Managers see it when planning iterations, so they can assign immediate work items to developers and check whether the project will be on schedule or not.

severity_label (data type: String)
Defined at computed columns in data set from Live_Workitem_Cnt table. severity_label stores human-readable string, such as Blocker, Critical, Major, Normal, or Minor that is converted from WI_SEVERITY with prefixes of numeric values that show smaller values as higher in severity (0 = most severe).

Again, you need five kinds of tables (see Table 3) to create the report shown in Figure 3. Report parameters at Project_Area, Live_devline, Live_iteration tables are cascading parameters in this order.

Table 3. Tables to report defects in order of severity
TableExplanation
com.ibm.team.process.DevelopmentLine (Live_devline)Table belongs to Live snapshot. Selected itemId at report parameter is used to set internalDevelopmentLine.itemId at Live_iteration.
com.ibm.team.process.Iteration (Live_iteration)Table belongs to Live snapshot. Selected itemId at report parameter is set to variable iteration_param (default value: ""). If not selected, all itemId filtered by using Live_devline are concatenated into iteration_param at script onFetch. iteration_param is set to ITERATION_ITEMID at Live_Workitem_Cnt.
Live_Workitem_CntA pie chart is put on group header row in a table where rows are grouped by PROJECT_AREA_NAME.

Work items are grouped by values of severity_label. Each rate of groups calculated from WI_COUNT is shown in the pie chart report in order of severity.

Work item type, defect, is set to WI_TYPE.

Unfinished state is set to STATE_NAME.
Project_AreaSelected PROJECT_AREA_ITEMID at report parameter is used to set to both PROJECT_AREA_ITEMID at Live_Workitem_Cnt, and internalProjectArea.itemId at Live_devline.
SeveritySEVERITY_ID and WI_SEVERITY are stored as severity_map variable (default value: new Object () ) as key and value, respectively, at script onFetch.

severity_map is used for severity_label at Live_Workitem_Cnt.

To show information of one project area by one pie chart, the pie chart is put on a group header row in a table where rows are grouped by PROJECT_AREA_NAME. Figure 3 shows the number of unfinished defects per project area in two project areas, according to severity.

Figure 3. Unfinished defect reports in order of severity
two pie charts showing the number of defects

The second pie chart report shows unfinished work items other than defects, also in order of priority (Figure 4). priority_label is defined at computed columns in a data set from Live_Workitem_Cnt table.

Again, you need five kinds of tables to create the report shown in Figure 4, so replace Live_Workitem_Cnt, Severity (see Table 3) with Live_Workitem_Cnt, Priority (Table 4).

Table 4. Different tables to report work items in order of priority
TableExplanation
Live_Workitem_CntA pie chart is put on the group header row in a table where rows are grouped by PROJECT_AREA_NAME.

Work items are grouped by priority_label values. Each rate of groups calculated from WI_COUNT is shown in the pie chart, in order of priority.

Work item type, other than defect, is set to WI_TYPE.

Unfinished state is set to STATE_NAME
PriorityPRIORITY_ID and WI_PRIORITY are stored as priority_map variable (default value: new Object() ) as key and value, respectively, at the onFetch script.

priority_map is used for priority_label at Live_Workitem_Cnt. priority_map and priority_label are calculated the same way in a report of assigned work items.

To show information of one project area by one pie chart, you follow the same steps as for the first pie chart report. Figure 4 shows the number of unfinished work items other than defects by project area in two project areas, in order of priority.

Figure 4. Unfinished work items in order of priority
two pie charts showing the number of work items

Productivity and contributions

The first bar chart report shows how many work items each developer finished (Figure 5). Managers check it at the end of iterations to see who has been the most productive.

Six kinds of tables (Table 5) are needed to create the report in Figure 5. Report parameters at Project_Area, Live_teamarea, Live_devline, Live_iteration tables are cascading parameters in this order.

Table 5. Tables to report productivity
TableExplanation
Live_ContributorAll CONTRIBUTOR_ITEMID filtered by Live_teamarea are concatenated into the contributor_param variable (default value: "") at script onFetch.

contributor_param is set to CONTRIBUTOR_ITEMID at Live_Workitem_Cnt.
com.ibm.team.process.DevelopmentLine (Live_devline)This table belongs to Live snapshot.

The selected itemId at report parameter is used to set internalDevelopmentLine.itemId at Live_iteration.
com.ibm.team.process.Iteration (Live_iteration)This table belongs to Live snapshot.

The selected itemId at report parameter is set to the iteration_param variable (default value: "").

If not selected, all itemId filtered by using Live_devline are concatenated into iteration_param at script onFetch.

iteration_param is set to ITERATION_ITEMID at Live_Workitem_Cnt (ways of calculation and setting of iteration_param are the same in a report of unfinished defects and work items).
com.ibm.team.process.TeamArea (Live_teamarea)Selected itemId at report parameter is set to TEAM_AREA_ITEMID at Live_Contributor.
Live_Workitem_CntFinished work items are counted per CONTRIBUTOR_NAME by using WI_COUNT, and each number is shown in descending order.

Finished state is set to STATE_NAME.
Project_Area,Selected PROJECT_AREA_ITEMID at report parameter is used to set to three parameters, projectArea.itemId at Live_teamarea, internalProjectArea.itemId at Live_devline, and PROJECT_AREA_ITEMID at Live_Workitem_Cnt.

To show a summary of information from multiple project areas in one bar chart, a stacked bar chart is used and the PROJECT_AREA_NAME column is set to the optional Y series grouping. Figure 5 shows the number of finished work items per contributor in two project areas.

Figure 5. Work items finished by each developer
Number of finished work items, by name

The second bar chart shows how many work items were approved by developers (Figure 6). Managers check it at the end of iterations to see who has contributed the most.

You need six kinds of tables by replacing Live_Contributor, Live_Workitem_Cnt (Table 5) with Live_Contributor, Live_Workitem_Cnt (Table 6) to create Figure 6 report.

Table 6. Different tables to report contributions
TableExplanation
Live_ContributorAll CONTRIBUTOR_ITEMID filtered by Live_teamarea are concatenated into variable contributor_param at script onFetch. contributor_param is set to APPROVAL_APPROVER_ITEMID at Live_Workitem_Cnt.
Live_Workitem_CntApproved work items are counted per APPROVAL_APPROVER_NAME by using WI_COUNT and each number is shown in descending order.

Finished state of approvals is set to APPROVAL_STATE.

To show a summary of information of multiple project areas in one bar chart, follow the same steps for the first bar chart report. Figure 6 shows the number of approved work items per contributor in two project areas.

Figure 6. Approved work items sorted by developer
Number of items by project and by name

Creating reports

This section explains how to create reports when the process applied to project areas in Rational Team Concert is scrum. It explains all steps of creating a report of assigned work items. Highlights of the other reports are also explained.

Assigned work items

Creating the Assigned Work Items report involves these seven steps:

  1. Create data sources
  2. Create data sets
  3. Create report parameters
  4. Set report parameters on data sets
  5. Create computed columns with variables
  6. Create a report parameter to select the sort type
  7. Create the layout

Create data sources

Create COMMON and WORKITEMS data sources.

  1. Select File > New > Report, and for File name, enter assigned_workitems.rptdesign.
  2. Click Next, select Blank Report, and click Finish.
  3. Open the Data Explorer view.
  4. Select New Data source by right-clicking Data Sources, and do these steps
    1. Select Create from a data source type in the following list.
    2. Select Jazz Data Source from the list.
    3. Enter COMMON at Data Source Name.
    4. Click Next.
  5. Select these values from lists in each pane, and click Finish.
    • Enter Repository:your repository
    • Enter snapshot:COMMON_SNAPSHOT
    • Enter project area:your project
  6. Repeat Steps 4 and 5 by selecting WORKITEMS_SNAPSHOT at Enter snapshot pane to create another WORKITEMS data source.

Create data sets

Create Iteration, Live_Contributor, Project_Area, Live_Workitem_Cnt, and Priority data sets.

  1. Right-click Data Sets, and select New Data Set, and then complete these steps:
    1. Click COMMON at Data Source Selection.
    2. Select Jazz Simple Data Set at Data Set Type.
    3. Enter Iteration at Data Set Name.
    4. Click Next.
  2. Select these values at each pane, and click Finish.
    • Enter table name: ITERATION
    • Select columns: ENDDATE, ITERAITON_ITEMID, and ITERATION_NAME
    • Select parameters: PROJECT_AREA_ITEMID
  3. Select the COMMON data source, and repeat steps 1 and 2 to create these data sets.
    • Data Set Name: Live_Contributor
      • Enter table name: LIVE_CONTRIBUTOR
      • Select columns: CONTRIBUTOR_ITEMID and CONTRIBUTOR_NAME
      • Select parameters: CONTRIBUTOR_ARCHIVED and PROJECT_AREA_ITEMID
    • Data Set Name: Project_Area
      • Enter table name: PROJECT_AREA
      • Select columns: PROJECT_AREA_ITEMID and PROJECT_AREA_NAME
      • Select parameters: PROJECT_AREA_ARCHIVED
  4. Select the WORKITEMS data source, and repeat steps 1 and 2 to create these data sets.
    • Data Set Name: Live_Workitem_Cnt
      • Enter table name: LIVE_WORKITEM_CNT
      • Select columns: WI_ID, SUMMARY, PROJECT_AREA_NAME, ITERATION_ITEMID, WI_PRIORITY, and DUE_DATE
      • Select parameters: PROJECT_AREA_ITEMID, CONTRIBUTOR_ITEMID, and STATE_NAME
    • Data Set Name: Priority
      • Enter table name: PRIORITY
      • Select columns: PRIORITY_ID and WI_PRIORITY

Create report parameters

Create the cascading parameter group, ProjectArea, and ContributorName.

  1. Right-click Report Parameters to select New Cascading Parameter Group.
  2. Enter these values at General
    • Cascading Parameter Group Name: ProjectAreaAndContributorName
    • Prompt text: Select ProjectArea and ContributorName
  3. Select Multiple Data Sets.
  4. Click Add, and enter and select these values, and then click OK.
    • Enter ProjectArea at Name.
    • Select Project_Area at Data Set.
    • Select PROJECT_AREA_ITEMID at Value.
    • Select PROJECT_AREA_NAME at Display Text.
  5. Select these values:
    • Sort by: PROJECT_AREA_NAME
    • Sort direction: Ascending
  6. Repeat steps 4 and 5 by doing these steps.
    • Enter ContributorName at Name
    • Select Live_Contributor at Data Set.
    • Select CONTRIBUTOR_ITEMID at Value.
    • Select CONTRIBUTOR_NAME at Display Text.
    • Click OK.
    • Select CONTRIBUTOR_NAME at Sort by.
    • Select Ascending at Sort direction.
  7. Click OK.

Set report parameters on data sets

Set the parameters on these data sets: Iteration, Live_Contributor, Live_Workitem_Cnt, and Project_Area data sets.

To fetch unfinished work items, set the unfinished state to STATE_NAME at parameters dialog. The unfinished state might vary according to processes of project areas or user customization of the process. By opening the project area and the Process Configuration Tab, refer to values of id attributes in state tags. Listing 1 shows values with group attributes that are open or in progress.

Tip:
Keep in mind that Resolved state of defect has the same value, 3, as the Done state of task, and both of them are in a closed group. This means that defects that are Resolved state are not shown in the report by using the code in Listing 1. A workaround is to create two Live_Workitem_Cnt data sets to show defects and tasks separately, and set STATE_NAME, respectively).

Listing 1. Unfinished states of work items at scrum process
'\'1\',\'2\',\'6\',\'com.ibm.team.workitem.buildTrackingWorkflow.state.s2\',\'com.ibm.te
am.apt.epic.workflow.state.s1\',\'com.ibm.team.apt.epic.workflow.state.s2\',\'com.ibm.te
am.apt.story.idea\',\'com.ibm.team.apt.story.tested\',\'com.ibm.team.apt.story.defined\'
,\'com.ibm.team.workitem.retrospectiveWorkflow.state.new\',\'com.ibm.team.workitem.retro
spectiveWorkflow.state.inprogress\',\'com.ibm.team.workitem.impedimentWorkflow.state.s1\
',\'com.ibm.team.rtc.workflow.adoption.state.s1\',\'com.ibm.team.rtc.workflow.adoption.s
tate.s2\''
  1. Click Iteration to select Parameters and then click Edit to select these values:
    • Parameter name: PROJECT_AREA_ITEMID
      • Data Type: String
      • Linked to Report Parameter: ProjectArea
  2. Repeat step 1 on these other data sets by selecting and entering these values to parameters:
    • Data set: Live_Contributor
      • Parameter name: CONTRIBUTOR_ARCHIVED
        • Data Type: Boolean
        • Default value: false
      • Parameter name: PROJECT_AREA_ITEMID
        • Data Type: String
        • Linked to Report Parameter: ProjectArea
    • Data set: Live_Workitem_Cnt
      • Parameter name: PROJECT_AREA_ITEMID
        • Data Type: String
        • Linked to Report Parameter: ProjectArea
      • Parameter name: CONTRIBUTOR_ITEMID
        • Data Type: String
        • Linked to Report Parameter: ContributorName
      • Parameter name: STATE_NAME
        • Data Type: String
        • Default value: Enter unfinished states of work items (Listing 1)
    • Data set: Project_Area
      • Parameter name: PROJECT_AREA_ARCHIVED:
        • Data Type: Boolean
        • Default value: false

Create computed columns with variables

Create computed columns, priority_label and deadline with project_area_array and priority_map variables.

WI_PRIORITY at Live_Workitem_Cnt might not be in a readable format. It can be converted to WI_PRIORITY at Priority by using a relation between PRIORITY_ID at Priority and WI_PRIORITY at Live_Workitem_Cnt (see Listing 2). Then, WI_PRIORITY at Priority is stored in priority_label with prefixes of numeric values that show smaller values as higher priority (0 = highest).

Listing 2. A relation between PRIORITY_ID and WI_PRIORITY
PRIORITY_ID (at Priority) = PROJECT_AREA_ITEMID (at Project_Area) + "p" + 
    WI_PRIORITY (at Live_Workitem_Cnt)

When report files are deployed on the Rational Team Concert server, the ProjectArea report parameter holds selected project areas in a format with each project area surrounded by single quotation marks and separated by a comma from others (Note: ProjectArea holds one project area without single quotation marks and a comma when running report files in the local environment.) Code Listing 3 shows how to parse ProjectArea and store each ID in the project_area_array variable. Information of project areas is used to calculate the priority_map variable in Listing 4.

Listing 3. Store selected project areas into project_area_array
var project_area_str = params["ProjectArea"].value; 
var project_area_ids = project_area_str.split(","); 
var str = ""; 
var arr = new Array(); 
for(var count = 0; count < project_area_ids.length; count++ ){ 
    var project_area_id = project_area_ids[count]; 
    project_area_id = project_area_id.replace(/\'/g, ""); 
    arr.push(project_area_id); 
} 
vars["project_area_array"] = arr;
Listing 4. Add to priority_map
var priority_id = row["PRIORITY_ID"]; 
var wi_priority = row["WI_PRIORITY"]; 
var arr = vars["project_area_array"]; 

if(priority_id != null){ 
    for(var count = 0; count < arr.length; count++){ 
        var project_area_itemid = arr[count]; 
        if(priority_id.indexOf(project_area_itemid)>= 0){ 
            vars["priority_map"][priority_id] = wi_priority; 
        } 
    } 
}
  1. Right-click Variables, select New Variable, enter these values, and click OK:
    • Type: Report Variable
    • Name: priority_map
    • Default value: new Object()
  2. Select Priority data set, select the Script tab, select onFetch, and enter the scripts (Listing 4).

Note:
The script stores PRIORITY_ID and WI_PRIORITY into priority_map variable as key and value, respectively.

  1. Click Live_Workitem_Cnt, and select Computed Columns.
  2. Click New, enter these values, and then click OK.
    • Column Name: priority_label
    • Data Type: String
    • Expression: Enter scripts (Listing 5)
Listing 5. An expression of priority_label
var map = vars["priority_map"]; 
var label = ""; 
for(var key in map){ 
    var val = map[key]; 
    if(key.indexOf(row["WI_PRIORITY"]) >= 0){ 
        if(val == "High"){ 
            label = "id0:" + val; 
        }else if(val == "Medium"){ 
            label = "id1:" + val; 
        }else if(val == "Low"){
            label = "id2:" + val; 
        }else if(val == "Unassigned"){
            label = "id3:" + val; 
        } 
        break; 
    } 
} 
label;

Create a joint data set that includes the Live_Workitem_Cnt_with_Iteration from Live_Workitem_Cnt and Iteration data sets. In the joint data set, create a computed column, deadline. The deadline is the due date if it exists or the end date of the iteration if not. The deadline column is used for sorting a table.

  1. Right-click Data Sets, and select New Joint Data Set.
  2. Select and enter these values, and then click Finish.
    • Left pane
      • Pulldown: Live_Workitem_Cnt
      • Menu: ITERATION_ITEMID
    • Right pane
      • Pulldown: Iteration
      • Menu: ITERATION_ITEMID
    • Join Types: Left Outer Join
    • Data Set Name: Live_Workitem_Cnt_with_Iteration
  3. Click Live_Workitem_Cnt_with_Iteration, select Computed Columns, and select and enter these values:
    • Column Name: deadline
    • Data Type: Date
    • Expression: Enter scripts (Listing 6)
Listing 6. An expression of deadline
if(row["DUE_DATE"]){ 
    row["DUE_DATE"]; 
}else if(row["ENDDATE"]){ 
    row["ENDDATE"]; 
}else{ 
    null; 
}

Create a report parameter to select the sort type

Create a SortType report parameter to sort by whether deadline or priority.

  1. Right-click Report Parameters, and select New Parameter.
  2. Enter and select these values:
    • Name: SortType
    • Prompt text: Select sort type.
    • Data type: String
    • Display type: Radio Button
  3. Click New, enter these values, and then click OK. Repeat the same step twice to add these two sets of values:
    • 1st
      • Display Text: deadline
      • Value: sort_by_deadline
    • 2nd
      • Display Text: priority
      • Value: sort_by_priority

Create the layout

You need to add dynamic text bound to the Priority data set. Without this, an onFetch script would not run and the priority_map variable at the Priority data set would remain empty.

  1. Add Dynamic Text from the Palette view.
    • Enter scripts to calculate the project_area_array variable (Listing 3).
    • Select Hide Element for all outputs at the Visibility tab on the Properties tab in Property Editor.
  2. Add Dynamic Text from the Palette view.
    • Enter texts, "Priority data set for script onFetch".
    • Select Hide Element for all outputs on the Properties tab in the Property Editor.
    • Select the Priority at Data Set on Binding tab in Property Editor.
  3. Add Table, and set the Live_Workitem_Cnt_with_Iteration at Data Set on the Binding tab in the Property Editor.
  4. At the added table, select these output columns:
    • Live_Workitem_Cnt::WI_ID
    • Live_Workitem_Cnt::SUMMARY
    • Live_Workitem_Cnt::priority_label
    • Live_Workitem_Cnt::PROJECT_AREA_NAME
    • Iteration::ITERATION_NAME
    • deadline
  5. In the Property Editor at the added table, click Add on the Sorting tab, enter and select these values, and then click OK.
    • Key: Enter scripts (Listing 7)
    • Direction: Ascending
    • Locale: Auto
    • Strength: ASCII
  6. Troubleshoot:
    • Run a data collection job if the data does not appear at Preview Result in each data set. At application administration, click Reports, and then click Run all data warehouse collection jobs.
    • To change the look and feel of table, click the left-top header of table, and edit properties in the property editor. For example, in the Advanced tab, set solid and thin to style and width at Box property, respectively.
Listing 7. Primary key at sorting tab
var sorted_by = params["SortType"].value; 
sorted_by = sorted_by.replace(/\'/g, ""); 
if(sorted_by == "sort_by_deadline"){ 
    row["deadline"]; 
}else if(sorted_by == "sort_by_priority"){ 
    row["priority_label"]; 
}
Figure 7. Layout of reporting assigned work items
two texts, dynamic texts, and tables of BIRT
Figure 8. Request parameter
selection of three parameters

To create the Figure 2 table report, Listing 8 shows parameters for APPROVAL_STATE at Live_Workitem_Cnt to report work items where approvals are pending.

Listing 8. Pending state set to APPROVAL_STATE
"com.ibm.team.workitem.approvalState.pending"

Unfinished work items in iterations

This section complements explanations of both reports of unfinished defects in order of severity and work items in order of priority.

Table 7 shows the values of STATE_NAME and WI_TYPE parameters to report unfinished defects. Unfinished means one of these four states:

  • New
  • In progress
  • Resolved
  • Reopened
Table 7. STATE_NAME and WI_TYPE at Live_Workitem_Cnt
NameData TypeExpression
STATE_NAMEString'\'1\',\'2\',\'3\',\'6\''
WI_TYPEString"defect"

If WI_SEVERITY at Live_Workitem_Cnt is not in human-readable format, it can be converted to WI_SEVERITY at Severity by a relation (Listing 9). First, selected project areas are stored into the project_area_array variable (Listing 3).

Listing 9. A relation between SEVERITY_ID and WI_SEVERITY
SEVERITY_ID (at Severity) = PROJECT_AREA_ITEMID (at Project_Area) + "v" + 
        WI_SEVERITY (at Live_Workitem_Cnt)

Next, SEVERITY_ID and WI_SEVERITY at Severity are stored in severity_map (Listing 10).

Listing 10. severity_map onFetch at Severity
var severity_id = row["SEVERITY_ID"]; 
var wi_severity = row["WI_SEVERITY"]; 
var arr = vars["project_area_array"]; 

if(severity_id != null){ 
    for(var count = 0; count < arr.length; count++){ 
        var project_area_itemid = arr[count]; 
        if(severity_id.indexOf(project_area_itemid) >= 0){ 
            vars["severity_map"][severity_id] = wi_severity; 
        } 
    } 
}

If SEVERITY_ID in severity_map includes WI_SEVERITY at Live_Workitem_Cnt, WI_SEVERITY in severity_map is returned with prefixes of numeric values that show smaller values as higher in severity (Listing 11).

Listing 11. severity_label computed column at Live_Workite_Cnt
var map = vars["severity_map"]; 
var label = ""; 
for(var key in map){ 
    var val = map[key]; 
    if(key.indexOf(row["WI_SEVERITY"]) >= 0){ 
        if(val == "Blocker"){ 
            label = "id0:" + val; 
        }else if(val == "Critical"){ 
            label = "id1:" + val; 
        }else if(val == "Major"){ 
            label = "id2:" + val; 
        }else if(val == "Normal"){ 
            label = "id3:" + val; 
        }else if(val == "Minor"){ 
            label = "id4:" + val; 
        }else if(val == "Unclassified"){ 
            label = "id5:" + val; 
        } 
    } 
} 
label;

iteration_param is calculated at onFetch in Live_iteration (Listing 12).

Listing 12. iteration_param onFetch at Live_iteration
var userIter = params["Iteration"].value 

if(userIter == null || userIter == ""){ // only devline is selected. 
    var itemId = row["itemId"]; 
    var str = vars["iteration_param"]; 
    // itemId of one iteration is added to str at once. 
    if(itemId != null && str.indexOf(itemId) == -1 ){ 
        str += '\'' + itemId + '\'' + ","; 
        vars["iteration_param"] = str; 
    } 
}else{ // iteration is selected. 
    var str = vars["iteration_param"]; 
    if(str == ""){ 
        str = userIter + ","; 
        vars["iteration_param"] = str; 
    } 
}

After calculation, iteration_param is set to ITERATION_ITEMID at Live_Workitem_Cnt (Listing13).

Listing 13. iteration_param set at Live_Workitem_Cnt
var iteration_param = vars["iteration_param"]; 
if(iteration_param.length > 0){ 
    iteration_param = iteration_param.substr(0, iteration_param.length - 1);
} 
iteration_param;

Table 8 shows report items at layout. These items are placed in order, from top to bottom.

Table 8. Report items at layout
Report ItemsBound tableExpression
Dynamic textNoneAdded for calculation of the project_area_array variable (Listing 3).
Dynamic textLive_iterationAdded for calculation of the iteration_param variable at onFetch, not shown in the report (by checking hide element at Visibility in the property editor).
Dynamic textSeverityAdded for calculation of the severity_map variable at onFetch, not shown in the report.
TableLive_Workitem_CntPROJECT_AREA_NAME, WI_SEVERITY, WI_COUNT are selected at output columns, and severity_label is created at computed columns (Listing 11). Here are detailed settings:

  1. Create the group by selecting Insert Group on row header.
    • Name: ProjectAreaGroup
    • Group On: PROJECT_AREA_NAME
  2. In each group, the severity_label number (calculated from WI_SEVERITY) is counted by WI_COUNT.
  3. Chart is put on Group Header Row.
  4. Set severity_label on sorting tab:
    • Sort Key: row["severity_label"]
    • Sort Direction: Ascending
    • Sort Locale: Auto
    • Sort Strength: ASCII
Chart(Inherit Data from Container: Inherit Columns and Groups)Shown in the report. This Chart report item is put on group header row in the Table report item above.

Here are detailed settings:
  • Chart Type: Pie
  • Output Format: PNG (if SVG does not work in a browser view.)
  • Inherit Data from Container: Inherit Columns and Groups
  • Category Definition: row["severity_label"]
  • Slice size definition: row["WI_COUNT"]
  • Chart Title: Unfinished defects in order of severity
TableLive_Workitem_Cnt_listOptional if lists of work items need to be reviewed.
Figure 9. Layout of unfinished defects report
dynamic texts, pie chart, a text, a table of BIRT

To create the pie chart report shown in Figure 4, Table 9 shows values of STATE_NAME and WI_TYPE parameters to report unfinished work items except defects and track build items. Unfinished means two state groups: Open or In progress, for each work item type. These are defined in the project area of the scrum process.

Table 9. STATE_NAME and WI_TYPE at Live_Workitem_Cnt
NameData typeExpression
STATE_NAMEStringListing 14
WI_TYPEStringListing 15
Listing 14. STATE_NAME expression
'\'1\',\'2\',\'com.ibm.team.apt.epic.workflow.state.s1\',\'com.ibm.team.apt.epic.workflo
w.state.s2\',\'com.ibm.team.apt.story.idea\',\'com.ibm.team.apt.story.tested\',\'com.ibm
.team.apt.story.defined\',\'com.ibm.team.workitem.retrospectiveWorkflow.state.new\',\'co
m.ibm.team.workitem.retrospectiveWorkflow.state.inprogress\',\'com.ibm.team.workitem.imp
edimentWorkflow.state.s1\',\'com.ibm.team.rtc.workflow.adoption.state.s1\',\'com.ibm.tea
m.rtc.workflow.adoption.state.s2\''
Listing 15. WI_TYPE expression
'\'com.ibm.team.apt.workItemType.epic\',\'com.ibm.team.apt.workItemType.story\',\'com.ib
m.team.workItemType.adoption\',\'com.ibm.team.workitem.workItemType.impediment\',\'com.i
bm.team.workitem.workItemType.retrospective\',\'task\''

Report items that replace Severity (dynamic text) and Live_Workitem_Cnt (table and chart) at Table 8 with Priority, Live_Workitem_Cnt (Table 10) are used for layout.

Table 10. Report items at layout, in order from top to bottom
Report itemsBound tableExpression
Dynamic textPriorityAdded for calculation of the priority_map variable at onFetch, not shown in the report.
TableLive_Workitem_CntWI_SEVERITY and severity_label (Table 8) are changed to WI_PRIORITY and priority_label, respectively.

Set priority_label on the Sorting tab.
Chart(Inherit Data from Container: Inherit Columns and Groups)Shown in the report. This Chart report item is put on group header row in the Table report item above.

Settings other than described here are the same as Table 8.
Category Definition:
row["priority_label"]

Productivity and contributions

This section complements explanations of reports of how many work items are finished and approved in each iteration.

Table 11 shows values of STATE_NAME to report finished work items, except for a track build item (Table 11). "Finished" means closed state groups for each work item type. (It indicates that defects with the Resolved state are also counted.) It is defined in the project area of the scrum process.

Table 11. STATE_NAME at Live_Workitem_Cnt
NameData typeExpression
STATE_NAMEStringListing 16
Listing 16. STATE_NAME expression
'\'3\',\'4\',\'com.ibm.team.workitem.taskWorkflow.state.s4\',\'com.ibm.team.apt.epic.wor
kflow.state.s3\',\'com.ibm.team.apt.epic.workflow.state.s5\',\'com.ibm.team.apt.epic.wor
kflow.state.s6\',\'com.ibm.team.apt.storyWorkflow.state.s1\',\'com.ibm.team.apt.story.ve
rified\',\'com.ibm.team.apt.storyWorkflow.state.s2\',\'com.ibm.team.workitem.retrospecti
veWorkflow.state.finished\',\'com.ibm.team.workitem.retrospectiveWorkflow.state.s1\',\'c
om.ibm.team.workitem.impedimentWorkflow.state.s2\',\'com.ibm.team.workitem.impedimentWor
kflow.state.s3\',\'com.ibm.team.rtc.workflow.adoption.state.s4\',\'com.ibm.team.rtc.work
flow.adoption.state.s3\''

contributor_param is calculated at onFetch in Live_Contributor (Listing 17).

Listing 17. contributor_param at onFetch in Live_Contributor
var itemId = row["CONTRIBUTOR_ITEMID"]; 
var str = vars["contributor_param"]; 
if( itemId != null && str.indexOf(itemId) == -1 ){ 
    str += '\'' + itemId + '\'' + ","; 
    vars["contributor_param"] = str; 
}

After calculation, contributor_param is set to CONTRIBUTOR_ITEMID at Live_Workitem_Cnt (Listing 18).

Listing 18. contributor_param set at Live_Workitem_Cnt
var contributor_param = vars["contributor_param"]; 
if(contributor_param.length > 0){ 
    contributor_param = contributor_param.substr(0, contributor_param.length - 1);
}
contributor_param;

Table 12 shows report items at layout. These items are placed in order, from top to bottom.

Table 12. Report items at layout
Report itemsBound tableExpression
Dynamic textLive_iterationAdded for calculation of the iteration_param variable at onFetch, not shown in the report (by checking hide element at Visibility in the property editor).
Dynamic textLive_ContributorIt's added for calculation of variable contributor_param at onFetch, not shown in the report.
ChartLive_Workitem_CntShown in the report. Here are detailed settings:

Select Chat Type: Bar
  • Select Subtype: Stacked bar charts
  • Output Format: PNG (if SVG does not work fine in a browser view.)
Category (X) Series: row["CONTRIBUTOR_NAME"]
  • Data Sorting: Ascending
  • Sort On: row["CONTRIBUTOR_NAME"]
  • Grouping Enabled: uncheck
Value (Y) Series: row["WI_COUNT"]
  • Aggregation expression: None
Optional Y Series Grouping: row["PROJECT_AREA_NAME"]
  • Data Sorting: Descending
  • Sort On: row["PROJECT_AREA_NAME"]
  • Grouping Enabled: checked
  • Type: Text
  • Unit: String
  • Interval:1
Chart Title: The number of finished work items.
TableLive_Workitem_Cnt_listOptional. Use it if lists of work items need to be reviewed.
Figure 10. Layout of Finished Work Items report by developer
dynamic texts, bar chart, a text, a table of BIRT

To create the Figure 6 bar chart report, Table 13 shows parameters to report how many work items are approved in iterations.

Table 13. Parameters set at Live_Workitem_Cnt
NameData TypeExpression
APPROVAL_STATEString"com.ibm.team.workitem.approvalState.approved"
APPROVAL_APPROVER_ITEMIDStringSet from contributor_param. (Listing 18)

Report items by replacing Live_Workitem_Cnt (Chart) at Table 12 with Live_Workitem_Cnt (Table 14) are used for layout of a report.

Table 14. Report items at layout
Report itemsBound tableExpression
ChartLive_Workitem_CntShown in report. Settings other than described here are the same as Table 12.

Category (X) Series:
  • row["APPROVAL_APPROVER_NAME"]

Summary

This article explained how to create reports to show developers and managers necessary information in Rational Team Concert by using BIRT. The article explained what information needs to be reported for each role, with use cases. It also explained how to implement them, step by step. By using these reports, each stakeholder can act to keep projects healthy.


Acknowledgement

The author thanks Masaki Wakao for technical advice.


Download

DescriptionNameSize
Sample report filessample_report_files.zip54KB

Resources

Learn

Get products and technologies

  • Download Rational Team Concert from Jazz.net (requires registration).
  • Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

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=795474
ArticleTitle=Creating customized reports through multiple project areas in Rational Team Concert
publish-date=02282012