®
IBM Software Group
© 2009 IBM Corporation
Rational Publishing EngineRQM Multi Level Report Tutorial
David Rennie, IBM Rational Services A/NZ
IBM Software Group | Rational software
2
Rational Publishing Engine - RQM Multi Level Report Tutorial
Agenda
Introduction – Setup Considerations
Stage 1 – Getting Started
Stage 2 – Create a report of TestCases in TestPlans
Stage 3 – Sorting and Filtering a Report
Stage 4 - Create another level in your report – Test Scripts
Appendix A – Adjust the number of entries per page in RQM
IBM Software Group | Rational software
3
Rational Publishing Engine - RQM Multi Level Report Tutorial
Documentation
RPE Online Help
http://publib.boulder.ibm.com/infocenter/rsdp/v1r0m0/index.jsp?topic=/com.ibm.help.download.tpe.doc/topics/publishingengine_version1_1.html
RQM Usage Examples
http://www.ibm.com/developerworks/wikis/display/rpe/RQM+Usage+Example
http://www.ibm.com/developerworks/wikis/display/rpe/RQM+2.0
RQM API
https://jazz.net/wiki/bin/view/Main/RqmApi
IBM Software Group | Rational software
4
Rational Publishing Engine - RQM Multi Level Report Tutorial
Pre-Requisites
Installed and running Software
Rational Publishing Engine 1.1.1
RQM 2.0.1
License Server 8.1
Information
RQM UserName and Password
IBM Software Group | Rational software
5
Rational Publishing Engine - RQM Multi Level Report Tutorial
RQM Data Source Basics
RQM Schema Location: <<Schema>>
https://host:9443/jazz/service/com.ibm.rqm.integration.service.IIntegrationService/schema/
RQM Feed: <<Schema>>feed.xsd
RQM Details: << Schema>>qm.xsd
RQM Resources <<Resources>>
https://host:9443/jazz/service/com.ibm.rqm.integration.service.IIntegrationService/schema/resources/
RQM Project: <<Resources>><RQMProjectName>/
RQM Resource Type:
<<Resources>><<RQM ProjectName>>/<resourcetype>?abbreviate=false
IBM Software Group | Rational software
6
Rational Publishing Engine - RQM Multi Level Report Tutorial
Objective
This tutorial demonstrates how to create a multi level RPE report accessing data from an RQM database.
The report created will list the test scripts, for each test case, in the test plans.
a variable will be used which may limit the scope of the report to single testplan.
RPE requires a template and a document specification to create a report.
The template defines the layout of the report and the relationship between the data sources
The document specification defines the location of the report data and output, it may also include variables used to filter the report.
IBM Software Group | Rational software
7
Rational Publishing Engine - RQM Multi Level Report Tutorial
RQM Limitations
There are currently some limitations using RQM with RPE
The number of entries per page is limited and needs to be adjusted in RQM. Instructions for this can be found in appendix A.
The New Template Wizard should not be used to create data schemas but can be used for it’s other functionality.
IBM Software Group | Rational software
8
Rational Publishing Engine - RQM Multi Level Report Tutorial
Stage 1 – Getting Started
In this stage you will create a basic template with a link to RQM and generate the report.
IBM Software Group | Rational software
9
Rational Publishing Engine - RQM Multi Level Report Tutorial
Create a new Document Template
Use File New “Document Template” or “New Template Wizard” to create a new Template
This may enable you to import data from another template.
You should not include Data Source Schemas while using the New Template Wizard as they do not load correctly.
RPE automatically creates a basic document specification when you create a template.
IBM Software Group | Rational software
10
Rational Publishing Engine - RQM Multi Level Report Tutorial
About Data Source Schemas
Data Source Schemas provide RPE with information about the structure of the information needed in the report.
The minimum requirement for an RQM report is a feed schema. This is the schema that RQM scrolls through when identifying relevant records.
If the report simply reported on TestPlans it would be possible to use just a test plan feed. If we want to include information from the testcases, or other child objects we need a details feed as well.
In this report we use three levels, Plans, Test Cases and Scripts.
One way to achieve this is using two feeds and two details feeds.
IBM Software Group | Rational software
11
Rational Publishing Engine - RQM Multi Level Report Tutorial
Schema locations for this tutorial
The feed file location: https://server:port/jazz/service/com.ibm.rqm.integration.service.IIntegrationService/schema/feed.xsd
The details file location: https://server:port/jazz/service/com.ibm.rqm.integration.service.IIntegrationService/schema/qm.xsd .
Add Data Source Schemas using the menu or from the outline pane.
The schema type is REST.
Insert the relevant schema file.
Provide a meaningful name eg. TestPlan_Feed,
For this report you will need:
TestPlan_Feed
TestCase_Details
TestCase_Feed
TestScript_Details
IBM Software Group | Rational software
12
Rational Publishing Engine - RQM Multi Level Report Tutorial
Getting started on your Template
Templates are structured using Paragraphs and Containers, each can occur within the other.
Containers are designed to iterate through sets of data.
Paragraphs are designed to contain report details.
Details can be added to the template by dragging from the palette or by right clicking in the outline and using the context menu.
The structure can easily be modified by using drag and drop in the outline.
Start by adding a paragraph to your template, Insert a Text box and add a basic description of the template. This will ensure you get a minimum output as you develop the report. The Text box can be removed later.
Then add a container within the paragraph after the text box.
IBM Software Group | Rational software
13
Rational Publishing Engine - RQM Multi Level Report Tutorial
Generate the documentNow that you have a basic template, switch to the RPE Launcher
view and set the parameters for the document specification
Map the Output Targets to folders in your project folder. For a simple project these may be just separate folders for each type of output. Ensure the document name is included in the path. Eg C:\RPE\<ProjectName>\HTML\MyTemplate
Map the path to the Data Source feed. This path was shown on the Data Source Basics page earlier in this presentation. It includes the basic path to the schema, followed by resources/<RQM_ProjectName>/<feedname>?abbreviate=false Feedname is the type of object in the feed, eg testplan, testcase
Include the RQM Username and Password in the feed properties where required.
Generate the document using the “Publish Generate Current Document” option or the icon on the toolbar.
If the document is generated correctly you can view the reports from a menu that pops up. This will contain just the text you entered in the text box
Once the document is generated save the description to a document specification folder with the same prefix as the template
IBM Software Group | Rational software
14
Rational Publishing Engine - RQM Multi Level Report Tutorial
Stage 2 – Create a report of TestCases in TestPlans
In this stage you will create a two level report that lists the test cases in all test plans
For each level you will include the title and description of the object
IBM Software Group | Rational software
15
Rational Publishing Engine - RQM Multi Level Report Tutorial
Structure of the Report
The report will be created using three nested containers
Cont 1 – Test Plan Feed
Cont 2 –Test Case Data Configuration
Cont 3 – Test Case Details
Add the data sources to the containersTest Plan Feed : This container is populated by dragging the feed
object (feed.entry.object.testplan) from the data source to the container.
TestCase Data Configuration:
drag the testplan reference to the test case (feed.entry.object.testplan.testcase) to the container
drag a Data Source Configuration object to the container
drag the Data Source Schema (testCase_Details), from the outline, into the Data Source Configuration object.
Test Case Details
Finally drag the testcase object from the testCase_details data source in the TestCase Details container.
IBM Software Group | Rational software
16
Rational Publishing Engine - RQM Multi Level Report Tutorial
Structure Your template should now look
something like this
You will not have the paragraphs and text
IBM Software Group | Rational software
17
Rational Publishing Engine - RQM Multi Level Report Tutorial
Configure Data Source ConfigurationTo see the properties of an object, right click on it in
the template outline.
It is strongly recommended that you name and describe the object using the Metadata properties This makes the outline much more understandable.
Open the Data Source Configuration properties and set the following properties.
Formatting Data target data source: This is the details data source name eg. testCase_Details
Formatting Data inherited data configuration:
This is the feed data source name eg. testPlan_Feed
Formatting Dynamic configuration URI:
This is the location of the links that map from the feed to the details. In this case, feed.entry.content.testplan.testcase.href
This can be entered using the browse option when the value field is selected.
IBM Software Group | Rational software
18
Rational Publishing Engine - RQM Multi Level Report Tutorial
Add Content Add the paragraphs and text boxes as
shown
In the Test Plan Feed container drag the title and description from the test plan feed source into the text boxes
In the Test Case Details Container drag the title and description from the Test Case Details source into the text boxes
In the paragraph with <styled text> all a line to separate the test plan details from the test case details.
Generate the report Now generate the report using the
menu option. Publish Generate Document or the icon. As you have already set up your document specification you do not need to switch to the Launcher, however if you have closed the template since you last generated the report you must check the launcher to ensure the correct document specification is opened.
IBM Software Group | Rational software
19
Rational Publishing Engine - RQM Multi Level Report Tutorial
Outcome of Stage 2
You should now be able to generate a report of test cases with test plans in the four standard formats
Provided you have succeeded with this save your template and move on to Stage 3
IBM Software Group | Rational software
20
Rational Publishing Engine - RQM Multi Level Report Tutorial
Stage 3 – Sort and Filter your Report
Sort the report.
Filter the report
IBM Software Group | Rational software
21
Rational Publishing Engine - RQM Multi Level Report Tutorial
Sort the report
You sort the report by setting the Data Sort property in the report feed container.
Open the feed container properties and select the Data Sort property value
The Sort Editor will be displayed
Select the field you wish to sort on, and set the direction to Ascending or Descending
IBM Software Group | Rational software
22
Rational Publishing Engine - RQM Multi Level Report Tutorial
Filter the report – Add a variable
You can use a variable to restrict your report to the desired objects. This can be created in the outline under the Variables node.
This can be done using an external or internal variable.
An Internal variable can only be changed within the template or another template derived from the template
An External variable can be changed in the document specification.
An example of an internal variable might be a “Report Name” used where a set of reports have identical formats but different contents based on some value in the report eg. Status.
An external variable might be a project name, where the report is identical for different projects having different data locations or a field value where the specification restricts the report to objects with a particular value in a field
IBM Software Group | Rational software
23
Rational Publishing Engine - RQM Multi Level Report Tutorial
Filter the report
The report can be filtered by placing a filter on either the feed or the details container
Build the filter at the highest appropriate level
You can not apply a filter to the Data Configuration Container
Select the container Data Filter property value
Click on the browse button at the end of the value field
In the Scripted Filter panel build an appropriate filter
IBM Software Group | Rational software
24
Rational Publishing Engine - RQM Multi Level Report Tutorial
Stage 4 – Create another level in your report
This process is essentially the same as that for creating the first level.
In addition you need to configure the feed for the next level so that it is sourced from the primary level.
You will add test scripts to your test cases
IBM Software Group | Rational software
25
Rational Publishing Engine - RQM Multi Level Report Tutorial
Structure of the Second LevelThe test scripts section of the report will be created
using three nested containers as in the original report illustrated
In this case the Test Case Feed container will be inserted in the Test Case Details container of the first level report
Cont 1 – Test Case Feed
Cont 2 –Test Script Data Configuration
Cont 3 – Test Script Details
Add the data sources to the containersTest Case Feed : This container is populated by dragging the feed
object (feed.entry.object.testcase) from the data source to the container.
Test Script Data Configuration:
drag the testscript reference in the TestCase_Feed to the test case (feed.entry.object.testcase.testscript) to the container
drag a Data Source Configuration object to the container
drag the Data Source Schema (testScript_Details), from the outline, into the Data Source Configuration object.
Test Script Details
Finally drag the testscript object from the testscript_details data source into the TestScript_Details container.
IBM Software Group | Rational software
26
Rational Publishing Engine - RQM Multi Level Report Tutorial
Configure the testCase feed Data SourceTo see the properties of an object, right click on it in
the template outline.
It is strongly recommended that you name and describe the object using the Metadata properties This makes the outline much more understandable.
Link the subsidiary report to the main report by indicating the source of the data.
Open the properties for the Test Case Feed container.
Set the property Data ==> Data Source to the secondary feed data source (testCase_Feed)
Set the property Query to the appropriate object in the testCase_feed (feed.entry.content.testcase).
IBM Software Group | Rational software
27
Rational Publishing Engine - RQM Multi Level Report Tutorial
Configure Data Source Configuration
Open the Data Source Configuration properties and set the following properties.
Formatting Data target data source: This is the details data source name eg. testCase_Details
Formatting Data inherited data configuration:
This is the feed data source name eg. testPlan_Feed
Formatting Dynamic configuration URI:
This is the location of the links that map from the feed to the details. In this case, feed.entry.content.testplan.testcase.href
This can be entered using the browse option when the value field is selected.
IBM Software Group | Rational software
28
Rational Publishing Engine - RQM Multi Level Report Tutorial
Configure the Details Data Source Open the properties box of the
testScript_Details Data Source Configuration.
The following properties are critical to the setup.
Formatting Data target data source: This is the details data source name eg.
TestScript_Details Formatting Data inherited data
configuration: This is the feed data source name eg.
testCase_Feed Formatting dynamic configuration
URI: This is the location of the links that map
from the feed to the details. In this case, select feed.entry.content.testcase.testscript.href from the testCase_Feed data source
IBM Software Group | Rational software
29
Rational Publishing Engine - RQM Multi Level Report Tutorial
Add Content Add the paragraphs and text boxes as
shown
In the Test Case Feed container drag the title and description from the testCase_feed source into the text boxes
In the Test Script Details Container drag the title and description from the TestCase_Details source into the text boxes
In the paragraph with <styled text> all a line to separate the test case details from the test script details (optional).
Generate the report Now generate the report using the menu
option. Publish Generate Document or the icon. As you have already set up your document specification you do not need to switch to the Launcher, however if you have closed the template since you last generated the report you must check the launcher to ensure the correct document specification is opened.
IBM Software Group | Rational software
30
Rational Publishing Engine - RQM Multi Level Report Tutorial
Outcome of Stage 4
You should now be able to generate a report of Test Scripts, within Test Cases within Test Plans in the four standard formats
Provided you have succeeded with this you have completed the tutorial.
IBM Software Group | Rational software
31
Rational Publishing Engine - RQM Multi Level Report Tutorial
Appendix A - Adjust the number of entries per page in RQM
RPE 1.1.1.1 cannot consume immediately the feed protocol used by RQM.
This means that for collections spawning on multiple pages RPE will only fetch the first page.
A solution that works for collections with 500 records or less is to increase the “Max Feed Entries/Page” in the RQM UI.
Login to RQM with Administrator priviliges
Admin Jazz Server Administration
Configuration Advanced Properties
Locate Max Feed Entries/Page and set the Value to 500 or higher.
It is suggested that there is a hardcoded setting in RQM that prevents increasing this value beyond the 500 value however it is possible to record a higher value
NOTE: This work around will not be necessary with the future versions of RPE