Reporting on data in configurations with Report Builder
Before you begin
Reporting on data in configurations is available, but there are limitations. For details, see Getting started with reporting by using Lifecycle Query Engine data sources on Jazz.net.
About this task
- You must use an LQE data
- Lifecycle Query Engine: For reporting on components and configurations themselves. Example: Report across all components and configurations in a configuration-enabled project area, as in these scenarios:
- Show all the components of a Car project
- Show all the streams of the Engine component in the Car project
- Show the artifacts (for example, test plans) in a stream of the Engine component
- If your report contains Artifact A in the results, and different configurations in the project area have different versions of Artifact A, your report will contain information about all the versions. Your report will contain information about all the versions of the selected artifact in those configurations.
- Lifecycle Query Engine scoped by
a configuration: For reporting on a specific global configuration, or on local
configurations that are not in a global configuration. When you run the report, you must choose a
configuration. Choosing a component is optional. If you have a versioned type system, such as for
IBM Engineering Requirements Management
see Reporting on applications that have versioned type systems.Example: Report on artifacts in multiple projects in the same domain, such as showing all incomplete test cases assigned to you.
- Lifecycle Query Engine: For reporting on components and configurations themselves.
- Report Builder reports with the data warehouse data source will not contain information for these projects.
- BIRT-based reports will no longer be available for these projects.
- Choose data.
- Format results.
- Name and share the report.
- 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 various document types (Microsoft Word, PDF, HTML). To do further editing on the report, export it to IBM Engineering Lifecycle Optimization - Publishing if you have a license. You can also export a report graph to an image file. See the related topics.
Step 1. Choose data
Go to https://server_name:port/rs. On the Reports page, click Build report. If the page doesn't open, contact your application administrator.
Choose a report type.
- Select Current Data (table or graph) to report on the latest information about artifacts in and across projects.
- Click the pencil icon to select the LQE data source depending on what you want to report on: a specific configuration or all configurations. If only one data source is defined, it is selected by default. To decide what data source to choose, see the About this task section, and read this topic.
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 Lifecycle Query Engine, only projects that are not enabled for configurations are listed. If you select List all projects when reporting on configurations themselves, configuration-enabled projects are included in the list. To limit the configuration results, select specific projects. Reporting on a mix of configuration-enabled and non-enabled projects might generate invalid results because there might be several versions of the same artifact.
- For Lifecycle Query Engine scoped by a configuration, only configuration-enabled projects are listed. When you run the report, you must choose a configuration.
Some artifact types are project-specific. Go to step 4 to select the artifact type, then return here, and select List only the projects that contain the artifact for your report.
Choose an artifact.
Select an artifact or specific types, and, click Continue. You might have to expand some artifacts to make a choice; if you don't expand the artifact, and select it, all of its types are included in the results.
If you select an artifact type 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.Tip: To report on requirements from specific modules, click Requirement, and select the types. You specify the requirement collections or modules later.
Trace relationships and add artifacts.
Explore how your artifacts are linked to other artifacts from the same, or from other lifecycle tools. Click Add a relationship. For each artifact type, you see all the existing relationships. Pick one, and click OK.Note: Some custom link types are not shown in the list of existing relationships: for example, custom link types from artifacts that do not own the link. For more information, contact your administrator, or see Getting started with reporting by using Lifecycle Query Engine data sources on Jazz.net.You can select multiple relationships between two artifacts of the same type, as shown in the following example:Example: To show that a requirement is validated by a test case, click Add a relationship, and under QM Test Case, select the Validated by relationship. To also list the work items that are associated with the test cases, click , and then click OK. To specify what type of related change request to add, select Work Item, and click OK. In the Set conditions section, you can further define the relationships.Tip: When you name and share your report, include the traceability link names so that team members can find your report easily.To trace multiple relationships from one artifact, or to add source artifacts, select the checkbox.
Example: You can trace how features are linked to work items, test cases, and child requirements. You see all the relationships in a single table.
- From one artifact, you can trace multiple relationships to other artifacts, and show all the
results in the same report. Choose how to for combine the results:
- The results are shown in the same rows.
- The report shows the results for each traceability relationship. All the source artifacts are in the same column.
- Append in new columns
- To count the source artifact relationships separately, append the results in different columns.
- Click Add an artifact, and select an artifact type.
To remove the last relationship from the right of an artifact, click Back. To remove an artifact or relationship and all the items to the right, click the X beside the item name.Tip: You can change the name of an artifact in the traceability box by double-clicking its name and typing the new one. For example, if you want your report to refer to related defects instead of change requests, double-click the Change Requests box in the traceability diagram, and type Defects. Changing the name in the traceability diagram makes it clearer to your team members, especially if your report uses custom artifact types or custom links.
After you build the artifact relationships, click Continue.
- From one artifact, you can trace multiple relationships to other artifacts, and show all the results in the same report. Choose how to for combine the results:
To further refine the content of your report, specify conditions. You can set conditions for any attribute of the artifact type that you selected, and any attribute of the related artifact types in your traceability paths. By setting conditions, you can further identify relationships among artifacts. For example, to show that a requirement is validated by a test case, select the Validated by relationship under QM Test Case. Then, set a condition to focus only on approved test cases. For the artifact type QM Test Case, choose the attribute Has Workflow State, and set the value to Approved.You can set a condition to return data only for specific components. You must select an application-specific artifact type (such as QM Test Case, or System Requirement). These artifact types contain a Component attribute that you can choose, and then select the component to report on. The Component attribute is not available if you select a global artifact type (typically the expandable top-level artifact type in the Choose an artifact section) or types from projects that aren't enabled for configurations.Tip: If you add the Component attribute as a column but do not add a condition for it, when you run your report you can select a component to filter the results that you see.
- Click Add condition.
- From the list, select an artifact type.
- Choose the attribute that you want to specify a condition for, and select the values to return the artifacts you want.
- To keep the window open for adding other conditions, click Add. Otherwise, click Add and Close.
- Optional: Change the lock to control whether people can or must supply a value for the condition when they run the report.
Note: If your condition uses an is not statement, the report shows only artifacts that have different values from the one you specified. If no value is selected for that attribute (the value is unassigned), the artifact is not included in the report.
- To edit a condition, click the pencil icon beside it.
- To create logical groups of conditions, select them, and click Group.
- To create nested groups of conditions, use the grouping buttons or drag conditions to existing groups.
- To reorder conditions, drag them into position.
- To exclude data from a report by grouping conditions, use the Not all match (AND NOT) or None of them match (OR NOT) options.
- To remove conditions, select them, and click Remove.
To include artifacts with different values from the specified one, and also artifacts with unassigned values, create two conditions and group them by using Any can match (OR).Example:If you group the conditions, you get the expected results, but the report takes longer to run.Sometimes several projects use the same custom attribute, and although the attribute has the same name across the projects, its ID is different in each project. To report on this attribute, add a condition for each project. Then, to consolidate them in your report, group the attributes by using an OR condition.Example: Each project you that report on has a risk status attribute, and it means the same to each project. Select this attribute for all the projects; then, group the attributes, and add an OR condition between them. To show the results in one column, instead of one column for each project, see the Show the report as a table section.Tip: To report on requirements in specific modules, from the attributes list, select the requirement or requirement type, and choose the Collection or Module attribute; then, choose the collections or modules, and click Save.
After you create your conditions, click Continue.
Step 2. Format results
- Format the results to determine whether to show the report as a table or a graph.
- Click Refresh to see a sample layout of your report. To see all the data, you must run the report.
Step 2a. Show the report as a table
Your report already has some columns, including columns for the attributes you created conditions for.
Add attribute columns: Select the artifact type from the drop-down list,
and the attributes to add to the report. Then, click Add.
To link directly to the artifacts in the lifecycle products include the Title and URL attributes in the report.
If you add the Component attribute as a column but do not add a condition for it, when you run your report you can select a component to filter the results that you see.
Add calculated value columns: Add columns that show calculations such as
averages, sums, or counts.
Example: To count the defects that were created in a specific time range, select . Then, set the time range.
- Select the artifact type.
- Select the calculation to show.
- Select the attribute for your calculation.
- To add other calculated values, click Add. Otherwise, click Add and Close.
Add custom expression columns if you are a report manager, and if your
data source is configured to allow report managers to edit queries: To show the data in the form
that you need, you can use attributes and functions to build custom expressions.
- Select the artifact type from the drop-down list.
- Add attributes (and functions if needed) one by one by selecting one and clicking Add.
Modify the expression in the Custom expression field.
For example, if you add a function to the custom expression, you must replace the placeholder text. In the custom expression, position the cursor at the placeholder text, choose an attribute, and click Add; then, delete the placeholder text.
If your custom expression includes a function or an aggregate expression, select the
Contains an aggregate expression checkbox.
Note: Aggregate expressions calculate a single value based on a set of values such as SUM, COUNT, AVG. Each database vendor has its own set of aggregate expressions. Check the vendor documentation.
- Optional: Specify how to display the values. You can use the default String.
- Validate your expression.
- Click Add to include the column in the report.
- Change the column name: Type in the Column Label field.
- Arrange columns: Click the drag handle beside the column label, and drag it to another location, or use the controls in the Actions column.
- Adjust the column width: Click the column boundary in the table layout at the top, and drag it into position.
- Sort columns: Select the sort method from the Sort Type list. You can sort more than one column. To change the sort order, edit the number.
- Color-code your report: Click in the Color section
to configure rules for highlighting specific data in your report. You can add multiple coloring
conditions. If several conditions target the same cells in your report, prioritize them:
- Within the same column: Drag a condition to adjust its priority. In a list, the priority increases from top to bottom. The first condition is met first. The last condition (at the bottom) can override the first one, so it has the highest priority.
- Across all columns in your report: Use the Priority field to define the sequence to apply your conditions in. Enter a value from 1 (highest) to 9 (lowest). To give a condition the lowest priority, leave the Priority field empty.
- Combine consecutive columns: Enter the same column label for equivalent
attributes that are grouped in one condition. Using the risk status example from Set conditions, for each instance of the
attribute (Risk Status in RM, Risk Status in QM, and so on), set the column label to Risk
Status. When you run the report, one Risk Status column shows data from all the
projects.Important: If the consecutive columns contain calculations, the labels are combined in the report that you export, but not on the Run Reports page.
- Remove columns: Use the controls in the Actions column.
Step 2b. Show the report as a graph
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.
- Enter the chart title.
Select the category to show on the X-axis (horizontal), and enter a label name.
Typically, you select what you want to measure.
- If you use a date attribute in the Group data by attribute field, 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 checkbox.
Select the quantities or units to show on the Y-axis (vertical), and enter a label name.
- Count all the results for the selected attribute, or select a unit to count. To compare different aspects of the value that you're measuring, select a dimension.
- If you use numeric values, add lines or bar segments.
Adjust what data to show in the graph.
- To show more data, click Add attribute data items.
- To add calculations such as averages, sums, counts, and so on, click Add calculated
value data items.
- Select the artifact type, calculation, and the attribute for your calculation.
- To add other calculated values, click Add. Otherwise, click Add and Close.
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.
- In time series reports you can add goal lines to compare the current state or values with target values. When you use the Add lines or bar segments for numeric measures option, click Add goal line. 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.
- In time series reports you can also add date lines to mark specific milestones. When you use the Add lines or bar segments for numeric measures option, click Add date line and specify the date. For each date line, select the graph type for your date line: the default, line, or dashed line.
- To show values or totals on the chart, click Graph type, and select the appropriate checkbox.
- When you finish arranging your report, click Continue.
Step 3. Name and share the report
- Give your report a name and a description. The description helps other team members find your report if it is public.
- 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.
Specify how to publish the report:
- Public (publish to catalog and visible to everyone): 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 creator and owners): The report is available only on the My Reports page.
- 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.
Click Add owner.
Your report can have multiple owners who can modify the report, and assign other owners.
- Click Select Folder and select a location to save your report.
- Click Save, and click Continue.
Step 4. Run the report
About this task
If you show the report as a table, you can add and change filters on columns by clicking the pencil beside a column name.
- To change the filter values, click that icon.
- To see which filter values are applied, hover over the column name.
You can export the filtered report results by clicking Export. Otherwise, your filtered results are not saved after you leave the page.Ask an application administrator to validate the TRS feeds for the application. See Validating TRS feeds and the LQE index.
Run the report with data completeness check enabled
You can use Data Completeness Check to check if a specific report has problems with the LQE data source. Problems that might affect the report results include skipped resources, missing resources, or resources with failed patches. If your reports do not show the artifacts that you expect, show artifacts more than once, or show a different number of artifacts when compared with the application, perform a data completeness check.
Before you begin
The Data Completeness Check option is not available on the Run reports page by default. If you want to use this option, contact your system administrator.
- Add the enable.lqe.data.completeness.check.feature property in the JTS_install_dir/server/conf/rs/app.properties file.
- Set the property value as true.
- Restart the Report Builder server.
- Click Filters.
- Click the Settings icon on the upper-right corner of the list box.
- Select the Data Completeness Check option.
- Run the report. The report displays information on skipped resources, missing resources, or resources with failed patches, if any.
- Optional: Contact your system administrator to troubleshoot the following
- For skipped resources, see Lifecycle Query Engine skips resources during indexing.
- For missing resources, see Validating TRS feeds and the LQE index.
- For failed patches, see Troubleshooting failed patches warnings.