Reporting on metrics and historical trends across projects with Report Builder

By using Report Builder, you can create reports to identify trends in project or team progress and quality throughout a release, a sprint, or a specific time range.

Report on a single trend or several historical trends in your data. You can define conditions to focus only on the data you need. You can specify whether conditions can be changed when the report is run, so other organizations can reuse and tailor your report.

Before you begin

If you use a Lifecycle Query Engine (LQE) data source, you must first configure LQE to collect metrics. Then, you can report on metrics and historical trends. For more information, see Collecting metrics for historical trends reports.

About this task

As you build your report, you can see your choices on the right side of the page in the My Choices pane. The My Choices pane is collapsed by default. Click the Show My Choices (Chevron button to expand the My Choices pane) icon to expand the My Choices pane. You can either click the heading of a section on the Build report page or the pencil Edit icon of a section in the My Choices pane and edit your choices.
Note: You can collapse the My Choices pane by clicking the Hide My Choices (Chevron button to collapse the My Choices pane) icon.


  1. Choose data.
  2. Format results.
  3. Optimize the report.
  4. Name and share the report.
  5. Run the report.

What to do next

  • To see your report in the list of other reports, click All Reports or My Reports.
  • To further edit your report, click a pencil in the My Choices pane at the right. Click Save to save your changes.
  • You can export your report to a spreadsheet or to IBM® Engineering Lifecycle Optimization Publishing as a document-style report. You can also export a report graph to an image file. See the related topics.

Step 1. Choose data


  1. Open Report Builder.

    Go to https://server_name:port/rs. On the Reports page, click Build report. If the page doesn't open, contact your application administrator.

  2. Choose a report type.
    • Click the pencil Edit icon to select the data source. If only one data source is defined, it is selected by default. To decide what data source to choose, read this topic.
    • Select Historical Trends (time series) to report on trends and metrics for projects.
  3. Limit the scope.

    Choose the projects to report on, and click Continue. If you don't select any projects, the report includes all projects that you can access.

    The list shows the projects that you can access in the data source that you selected. If your projects are not in the list, see the administrator who created the data sources for Report Builder.
    • For Data warehouse, all projects are listed.
    • For Lifecycle Query Engine, only projects that are not enabled for configurations are listed.
    • For Lifecycle Query Engine scoped by configurations, only configuration-enabled projects are listed.

    Some artifact trends are project-specific. Go to step 4 to select the trend, then return here, and select List only the projects that contain the artifact for your report.

  4. Focus on artifact trends.

    Select one or several artifact trends to report on, and, click Continue. The trends are organized under the artifacts in the lists, so you might have to expand some artifacts to choose a trend.

    If you select an artifact trend that is project-specific, you can return to the Limit the scope section, and select List only the projects that contain the artifact for your report.

    Note: For LQE, if you report on the Work Item Totals trend, the report returns only the work items closed in the last year.
  5. Set a time range.

    The time range that you select is added as a condition in the Set conditions section.

    Note: To report on specific quarters, months, or days, go to the Set conditions section, and add a condition for the Date [Type:Date] type; then, select the day, month, period, or quarter to report on.
  6. Set conditions.
    To further refine the content of your report, specify conditions. You can set conditions for any attribute of the artifact trend that you selected.
    Note: If you selected more than one trend in step 4, some of the conditions that you apply to one trend must also be applied to the others. For example, if you selected the Creation and Resolution trends for Work Item and you want to know about defects for a particular version, the Type and the Planned for attributes must be applied to both trends.
    1. Click Add condition.
    2. From the list, select an artifact type.
    3. Choose the attribute that you want to specify a condition for, and select the values to return the artifacts you want.
    4. To keep the window open for adding other conditions, click Add. Otherwise, click Add and Close.
    5. Optional: Change the lock Lock icon to control whether people can or must supply a value for the condition when they run the report.
    • To edit a condition, click the pencil Edit icon beside it.
    • To create logical groups of consecutive conditions, select them, and click Group.
    • To create nested groups of conditions, use the grouping buttons or drag conditions to existing groups.
    • To exclude data from a report by grouping conditions, use the Not all match (AND NOT) or None match (OR NOT) options.
    • To reorder conditions, drag them into position.
    • To remove conditions, select them, and click Remove.

    After you create your conditions, click Continue.

Step 2. Format results

The trend report is formatted as a graph by default. Report Builder picks the graph type based on your selections so far. Experiment to find the best graph type. Typically, line graphs convey trend information effectively, but you might find that a bar chart (stacked or grouped) works better with your data.


Before you can preview a graph, you must select a value for the unit of measure. You can also select the dimension.

Click Refresh to see a sample layout of your report. To see all the data, you must run the report.

  1. Enter the chart title.
  2. Select the category to show on the X-axis (horizontal), and enter a label name.
    Typically, you select what you want to measure.
    • Click Date scale, and choose what date range to show in the report: days, weeks, months, or years.
    • To show data gaps, select the Fill in gaps with zero value check box.
  3. Select the quantities or units to show on the Y-axis (vertical), and enter a label name.
    • If your report is for a single trend, select a unit to count. To compare different aspects of the value that you're measuring, select a dimension.
    • If you report on several trends and want to include each trend in the graph, select the Add lines or bar segments for numeric measures option, and click Measures. Choose a trend from the Attributes of list, select your attributes, and click Add.
      • To track a trend against a particular goal, click Goal line, and enter a start and end value. Choose a bar, a solid line, or a dashed line. Use an angled, curved, or an S-curve trajectory for the goal line. You can add several goal lines to your chart.
      • Add date lines to mark specific milestones. Click Date line and specify the date. For each date line, select the graph type for your date line: the default, line, or dashed line.
  4. Adjust the graph.
    • Change the colors of the lines or bars on the graph to make the categories more visible, or to comply with conventions in your organization.
    • Combine line and bar chart segments to show the dimensions in your report. For each segment specify the graph type: bar, line, or dashed line.
      Note: The orientation can be set only for the stacked bar and the grouped bar. The line chart and pie chart have only vertical orientation option.
    • To show values, totals, or grids on the chart, click Graph type, and select the appropriate checkbox.
      Note: The Show grids checkbox is only applicable for line and bar graphs.
  5. When you finish arranging your report, click Continue.

Step 3. Optimize the report


Generate alternate queries using the following options. To find what works best, try turning these options on and off. The options appear only when you select Lifecycle Query Engine or Lifecycle Query Engine scoped by a configuration as the data source.

  • Select the Defer finding relationships with an alternative query checkbox to generate an alternate query that filters on source artifacts before finding relationships. Try this option if your data has one-to-many relationships in the Artifacts relationships section.
  • Select the Defer scoping by projects with an alternative query checkbox to generate an alternate query that filters on artifacts first before scoping by projects. Try this option if your data has large number of projects in the 'Limit the scope section.

Step 4. Name and share the report


  1. Give your report a name and a description. The description helps other team members find your report if it is public.
  2. Tag your report to make it easy to find, or to group it with related reports. Each tag becomes a category on the All Reports and My Reports pages.
  3. Specify how to publish the report:
    • Public (publish to catalog): The report is in the Report Builder catalog. Team members can add the report as a widget to their Jazz dashboards.
    • Private (publish to catalog and visible only to creator and owners): The report is in the Report Builder catalog. Only the report creator and owners can add the report to a dashboard and see it. Other users see the widget, but they cannot run the report.
    • Private (visible only to me): The report is available only on the My Reports page.
  4. Specify whether the default visualization for your report is a table or a graph. For example, if you select Graph, but then run the report to generate a table, the next time you run the report, the results are shown again in a graph.
  5. To improve the performance of reports that do not the need the up-to-date data, set the Result timeout in seconds field. The report displays data at the configured time. Caching is implemented for the last report result to quickly display it on dashboard, reducing the load on LQE caused by automatically triggered query executions by each dashboard refresh.
  6. Click Add owner.
    Your report can have multiple owners who can modify the report, and assign other owners.
  7. Click Save, and click Continue.

Step 5. Run the report

To see the complete report, click Run report. Provide values for all required parameters or filters.

About this task

If you choose an LQE-based data source in step 2 and Report Builder reports don’t show the artifacts that you expect, show artifacts more than once, or show a different number of artifacts than application views, ask an application administrator to validate the TRS feeds for the application. See Validating TRS feeds and the LQE index.

If the report is incomplete due to different conditions, such as, data sources that are indexing, validating data, or being removed, appropriate error messages are displayed. You can rerun the report after the LQE processes are complete. The report also displays an information icon along with hover text, if LQE conditions affected the execution time of the report.