Build a customized dashboard in Rational Team Concert using Report Builder
An agile perspective
It is challenging for line of business users and project executives of cross-project programs to get an overview of a project from a single place. To overcome the challenge of tracking progress on multiple team projects, you can use a customized IBM Rational Team Concert™ dashboard. The dashboard is created at the program level and customized in a way that scrum masters and executives can access the information relevant to them.
From an agile point of view, there are a few elements beneficial for an executive on any project:
- Project status, as-of-today, or in the current iteration
- How the project did in the past iteration
- Project trend since inception
This tutorial goes in-depth to show you how to customize a Rational Team Concert Dashboard. It describes some of the widgets available, custom work items, attributes, reusable and generic reports created in Report Builder, and snippets of code used to create some of the reports in Jazz™ Reporting Service. Agile concepts and recommended guidelines are also explored.
Dashboards are a primary and powerful component for tracking the overall status of a project. Various widgets in the dashboard provide a visual representation of the information to show the project progress and status of the application. Before creating a dashboard, it's important to decide on the goal and the editor or owner of the dashboard. After the goal is identified, create the dashboard using the widgets available in the tool. Some widgets are reports, some are RSS feeds, and others are web pages. A commonly used widget is Reports. This widget provides charts as a graphical representation of all the data in one place. Reports can generate comparison charts that showcase data from different quarters. This helps to identify the progress made since the previous quarter.
Generating reports using Report Builder
Report Builder is an intrinsic part of Jazz Reporting Service. It consolidates and displays data in the form of charts and tables from a variety of sources, including data warehouses or Lifecycle Query Engine. You can add Report Builder into a dashboard with the Reports widget, if the server that hosts the dashboards shares a friendly relation with the server running the Report Builder. When you generate a report, you have the option to choose a set of predefined reports or to create your own reports from the template. Depending on the requirements, either method can be used and in both methods, the reports can be private, public, and customizable. Predefined reports need to be activated by a user with JazzAdmin or JazzProjectAdmin privileges before they're available in the dashboard.
Sample dashboard and report widgets
Figure 1 is a sample dashboard developed for a cross-domain project. It consists of several charts and reports that show the progress of a project by iteration. The different domains in this report are:
- Dev Squad
- Tech Squad
- Test Squad
- Business Squad
Figure 1 shows the Current Status tab of the dashboard. This tab contains information about the overall health, open epics and stories per domain in the form of tables and charts. Everything shown on the Current Status tab pertains to the current iteration. The widgets shown in Figure 1 are described in detail individually below.
Figure 1. Current Status tab
Figure 2 shows open epics and user stories per domain. User story is a brief description of the requirement that can be accomplished in an iteration. Epics are bigger stories that cannot fit into a single iteration. These need to be broken down into smaller stories. It is beneficial to show the status of the stories and epics in the dashboard because they show the amount of work that has been completed so far and also can help determine if you can incorporate more stories or epics from the backlog into the current sprint.
Figure 2. Open Epics and Stories Per Domain
The Burndown chart in Figure 3 shows a graphical representation of the outstanding work in each iteration. This chart is calculated in the middle of an iteration. It helps you estimate how much work is complete and if the project is on schedule to complete all items in the current iteration. The Burndown chart helps you decide whether you can add more work into the current iteration or move some items to the next sprint. This all depends on the deviation the Remaining Work line has from the Ideal line.
In the diagram shown in Figure 3, there is a lot of deviation of the Remaining Work line from the Ideal line, meaning the team did not make much progress in the sprint. The recommendation is to either break down the current stories or move some items to the next sprint or to the backlog.
Figure 3. Burndown chart
The Accomplishments tab includes:
- Monthly highlights
- Team velocity
- Story points
Through the information on these widgets, the development team and managers know which business requirements have been met and the development team's productivity.
Figure 4 shows the Monthly Highlights and Team Velocity widgets. Monthly highlights are the key features completed in the iteration. Team velocity is the sum of estimation of completed stories per sprint. Velocity is calculated at the end of the iteration.
Figure 4. Accomplishments tab: Monthly Highlights, Team Velocity
Figure 5 shows the sum of the story points of completed stories by each squad in an iteration. It also shows the number of stories and epics closed during the iteration aligned by priority or iteration. This information reveals how much work can be delivered in each iteration and how many stories to include in the next iteration.
Story point is a number that defines how much effort is necessary to complete the story. With story points, the higher the number, the higher the difficulty level. For example, if story points are less than 13, the story is easy to implement. If they're greater than 13, then the story is difficult and might not be completed in one iteration.
Figure 5. Accomplishments tab: Story Points, Closed Stories
The Dashboard also has a Trends tab, which displays:
- Open impediments
- Impediments by iteration
- Work items
- Iteration details
Impediments are the blockers that suspend the work on a feature. Including impediments in a report provides a clear view any bottlenecks faced in an iteration. With this information, each squad can work to find a solution.
Figure 6. Trends tab: Impediments
A retrospective is a mechanism to validate what went well in the current iteration and what measures to take in the future.
Work items and story points define the features and functionality to implement. In Figure 7, work items based on their status (open, in-progress, implemented) are compared for each squad. This graph shows the number of items pending and completed by each squad. In preparation for a sprint planning meeting, you can look at this tab and easily know if the estimates of work and commitments were accurate or not.
Figure 7. Trends tab: Retrospective, Work Items, and Story Points
Figure 8 shows a detail of the Open Retrospectives with Age report. This report contains all the open retrospectives in the overall cross-team program. It defines a custom Age Open field in the underlying SQL that shows how many days a retrospective has been open.
Figure 8. Open Retrospectives: Age
Retrospectives are a key principle of the agile practice. Most people are familiar with the three topics discussed during each retrospective:
- What went well
- What did not go well
For most agile projects, retrospectives are captured well, but what happens next? Are they tracked and followed up on as well as they are created? Are there a lot of open retrospectives since the beginning of a release that have never been closed or tracked?
Not closing or tracking retrospectives happens often in sprints that last two weeks or more. This usually happens when the team focuses on delivering the agreed upon scope and loses focus of the retrospectives. A good start for a scrum master to remediate this practice is to have a report of open retrospectives sorted by the number of days open.
A snippet of the SQL query used to create the Open Retrospectives with Age report shown in Figure 8 is shown in Listing 1. Replace the xxx, highlighted on line 15, with your project's values.
Listing 1. Sample SQL query for the Open Retrospectives with Age report
SELECT DISTINCT T1.REFERENCE_ID, T1.NAME AS URL1_title, T1.URL AS URL1, CASE WHEN T1.RESOLVED_DATE IS NOT NULL THEN DAYS(T1.RESOLVED_DATE) - DAYS(T1.CREATION_DATE) ELSE DAYS(CURRENT_TIMESTAMP) - DAYS(T1.CREATION_DATE) END AS DAYS_OPEN, T1.REQUEST_CATEGORY_NAME FROM RIDW.VW_REQUEST T1 LEFT OUTER JOIN RICALM.VW_RQST_STRING_EXT T2 ON T2.REQUEST_ID=T1.REQUEST_ID AND T2.NAME='com.ibm.retrospective.type' LEFT OUTER JOIN RICALM.VW_RQST_ENUMERATION T2_1 ON T2_1.EXTERNAL_ID=T2.VAL AND T2_1.PROJECT_ID=T1.PROJECT_ID WHERE T1.PROJECT_ID = xxx AND ( T1.REQUEST_TYPE = 'Retrospective' AND (T1.REQUEST_STATE <> 'Invalid' AND T1.REQUEST_STATE <> 'Resolved' AND T1.REQUEST_STATE <> 'Abandoned' AND T1.REQUEST_STATE <> 'Done' ) AND T2_1.LITERAL_NAME = 'What Went Well' ) AND (T1.ISSOFTDELETED = 0) AND (T1.REQUEST_ID <> -1 AND T1.REQUEST_ID IS NOT NULL)
The Story Point report displays graphs that show the number of items pending, in progress, and completed by each squad. This one-page insight into the progress is invaluable for status reports.
Figure 9. Trends: Story Points
A snippet of the SQL query used to create the report in Figure 9 is shown in Listing 2. Replace the xxx with your project's values on lines 14, 16, 17, and 18.
Listing 2. Sample SQL query for Trends: Story Points report
Select distinct T1.REFERENCE_ID, T1.REQUEST_STATE, T1.SUMMARY, T2_1.LITERAL_NAME, T1.ITERATION_NAME, T1.ITERATION_ID, T1.TEAM_NAME FROM RIDW.VW_REQUEST T1 LEFT OUTER JOIN RICALM.VW_RQST_STRING_EXT T2 ON T2.REQUEST_ID=T1.REQUEST_ID AND T2.NAME='com.ibm.team.apt.attribute.complexity' LEFT OUTER JOIN RICALM.VW_RQST_ENUMERATION T2_1 ON T2_1.EXTERNAL_ID=T2.VAL AND T2_1.PROJECT_ID=T1.PROJECT_ID WHERE T1.PROJECT_ID = xxx AND ( T1.REQUEST_TYPE = 'Story' AND ((T1.REQUEST_CATEGORY_NAME <> <Project Name>) OR (T1.PROJECT_ID <> xxx)) AND T2_1.LITERAL_NAME <> '0 pts' AND T1.TEAM_NAME = ‘xxx’ AND (T1.ITERATION_ID = xxx) AND (T1.ISSOFTDELETED = 0) AND (T1.REQUEST_ID <> -1 AND T1.REQUEST_ID IS NOT NULL) ORDER BY T1.ITERATION_ID asc
Creating an effective dashboard: work items
As shown in the dashboard in Figure 1, it takes many tables and reports to display the cross-domain progress of a project. These widgets are created by leveraging a wide variety of work items provided in Rational Team Concert. The Knowledge Center contains information on how to create custom work items. Some of the work items that help in tracking important statistics required by the project manager/leads are:
The Highlight work item is created at the end of the iteration. As the name suggests, it highlights the key accomplishments of each team or squad during the iteration.
Figure 10. Sample Highlight work item
Hot Topic/High Priority
Label or tag the most critical items and tasks in each sprint with a priority as High or tagged with Hot-Topic. Doing this for each team or squad makes it easier to retrieve all the high-priority items in a single query. These items will display in a separate tab.
Figure 11. Hot Topics
Epic & Health
Every team has a roadmap of what they want to achieve in an iteration. In Rational Team Concert, this is called an epic. Epic has an attribute named Status Color. Domain scrum masters use this to indicate the health and status of an epic.
The colors and status are:
- Green: Complete
- Yellow: In progress
- Red: Not started/Blocked
The Roadmap Health widget (shown in Figure 12) lists all the epics in progress in the current sprint or quarter. Knowing the status of the epic being implemented in the current iteration/quarter is important information for the scrum master.
Figure 12. Roadmap Health
Risk is a custom work item that is created for domain leads to capture any potential risks in an upcoming iteration. The risk might occur in the future and could be a potential impediment (blocker for current development).
Figure 13. Defining Risk
An impediment, or issue, is something that impacts the project now. To track an impediment in Rational Team Concert, define a custom work item called Impediment. After this type is defined, team members can create work items of this type and assign the work items to people who can resolve the issue.
If an impediment moves between teams (for example, the owner of the same impediment changes over time), update the Filed Against field to reflect the appropriate team.
Impediment has two additional fields you can specify:
- Affected Teams: List any teams affected (directly or indirectly) by the impediment in the Affected Teams field.
- External Resources: A custom text field to identify any external team or person that might influence the impediment in question.
Link open impediments to the corresponding stories or epics that they affect, either directly or indirectly
Figure 14. Impediment
A retrospective is conducted to validate what went well in the current iteration and what areas need attention. It's a good idea to conduct a retrospective at the end of each iteration. A retrospective helps to analyze the problems that occurred during the iteration and define a solution to eliminate the issue in the next iteration. Retrospectives need to be linked with any Tasks/Stories opened against them.
When you create a retrospective, also create a corresponding work item (Task/Story) to capture the action items from the retrospective opened. Link that work item to the Resolved by field in the retrospective.
Figure 15. Trends: Retrospectives
Creating an effective dashboard: Practices
In addition to work items, there are other practices to consider when creating an effective dashboard. These practices are:
- Start each iteration with a sprint planning meeting. In this meeting,
decide which stories and tasks to complete in the current sprint.
Note: Before the sprint planning meeting, make sure the stories in the previous sprints are closed and any unfinished stories are moved to the new sprint.
- Define all user stories in a specific format. Ensure the definition of
the story is clear, brief, and contains a business value statement.
User stories contain only a high-level overview of the requirement.
Implementation details are not included.
As a PO, I would like <desired behavior>, so that <business value statement>.
For example: As a PO, I would like to add a business justification section to the request form, so that I can know why the user needs access to the application.
- To get an accurate estimation of the workload required for a story,
each user story must have an assigned story point. Stories with more
than 13 points might not get completed in the corresponding iteration
and need to be continued in the following sprint or broken down into
You can assign story points using several tools, including Planning Poker or Fibonacci, where an estimated value of the story points is decided with the consensus of the team. Story points are critical. They determine the velocity of the team and help with iteration planning in future sprints. In a multiteam project, the velocity of the different teams/squads cannot be compared. The velocity is unique to each team. When planning a future sprint, each team should consider the velocity of their respective team.
- Use story cards or a team collaboration tool such as Rational Team Concert to define user stories. For cross-team projects, online collaboration tools are the best option because all the team members can see and update the stories and tasks from the tool.
- Acceptance criteria is a must-have when defining a story. Acceptance criteria contains a list of steps or conditions to complete for a successful completion of the story.
- It is advisable to create a separate task for design, implementation, documentation, and test for each user story.
- Properly log the Estimation Time field when creating a task, and the Time Spent field upon task completion. This is important when creating a report that shows planned hours versus actual hours. If you're missing entries for any tasks, the numbers in the report might not be accurate.
Figure 16. Planned Hours vs Actual Hours tables
- If a story spans beyond a couple of iterations (moves from iteration to iteration), open an impediment and note the reasons why the story continues across iterations. This documentation is important.
- Link open impediments with their corresponding stories or epics that they affect, whether directly or indirectly.
- In addition to the sprint planning meeting, have daily-standup meetings among the team members doing the work. The daily standup should be brief. Each team member only discusses the progress of the items they are working on, and if there are any blockers. Avoid any further discussion. Have follow-up discussions after the standup, or schedule another meeting. Keeping the standup short and on topic saves time for team members who do not need to be part of the discussion.
- A wall of work or story wall is useful as a visual representation of progress when working on a cross-team project.
- Hold a scrum of scrums meeting for multiteam projects. The scrum master of each individual scrum team attends this meeting. Each member provides a high-level update of their team's progress and discusses if they need help from the other teams.
- At the end of each scrum, have a sprint-review meeting for team members and stakeholders. Each team member provides a demo of the work accomplished in the previous sprint and gets feedback. In multiteam projects, the scrum of scrum calls also has a sprint-review meeting. In consideration of time, the scrum master usually presents slides instead of an actual demo in this meeting.
- For multiteam projects, try to achieve minimal dependency between the teams. Dependency at the story level is better than dependency at the task level.
- Use Rational Team Concert for a code review. Before delivering the code to the stream, a developer can assign the code changes to another team member for review. If the reviewer approves the changes, the developer can deliver their change. If not, then the developer rolls back the changes, updates the code, and then redelivers the changes. This is a good practice to follow.
- If your project has a separate testing team: After the development work is complete, reassign the user story to the tester. The tester then tests to see if the functionality works and meets the expectations.
- During the sprint planning meeting, review the product backlog to see if there are any high priority stories or tasks that can be included in the current sprint.
- For each reported defect, create a defect in Rational Team Concert and include the details of the issue. After the defect is recorded, the user should create a story, including the required tasks to resolve the defect. Link the defect to the story using the Related To field.
- When tracking a team's progress in a multiteam project, use burn-up and burn-down charts for a visual representation of the work completed. Use different colors for each of the different teams.
- Each team should have a Product Owner (PO). For a multiteam project, you can also have a Sub PO who handles each individual squad. All of the Sub POs report to the Chief PO.
This tutorial introduced a set of capabilities and reports to help you set up dashboards to show the status of your entire project portfolio. These reports aggregate data across applications, projects, and even across timelines. The dashboard snapshots contain results from all the different teams working together on an application. You also learned important guidelines and agile concepts to apply to develop an effective dashboard.
- Recipe: How to create an agile report: Overall project iteration planning details
- Create a custom work item in Rational Team Concert
- Create, refine, and manage reports
- DevOps journeys on developer.ibm.com/code