Rational Publishing Engine RQM Multi Level Report Tutorial

1. Rational Publishing EngineRQM Multi Level Report Tutorial David Rennie, IBM Rational Services A/NZ drennie@au1.ibm.com

2. Agenda Rational Publishing Engine - RQM Multi Level Report Tutorial 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

3. Documentation Rational Publishing Engine - RQM Multi Level Report Tutorial 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

4. 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 Rational Publishing Engine - RQM Multi Level Report Tutorial

5. 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 Rational Publishing Engine - RQM Multi Level Report Tutorial

6. Objective Rational Publishing Engine - RQM Multi Level Report Tutorial 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.

7. RQM Limitations Rational Publishing Engine - RQM Multi Level Report Tutorial 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.

8. Stage 1 – Getting Started • In this stage you will create a basic template with a link to RQM and generate the report. Rational Publishing Engine - RQM Multi Level Report Tutorial

9. Create a new Document Template Rational Publishing Engine - RQM Multi Level Report Tutorial 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.

10. 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. Rational Publishing Engine - RQM Multi Level Report Tutorial

11. Schema locations for this tutorial • 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 Rational Publishing Engine - RQM Multi Level Report 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.

12. 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. Rational Publishing Engine - RQM Multi Level Report Tutorial

13. Generate the document Now 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 Rational Publishing Engine - RQM Multi Level Report Tutorial

14. 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 Rational Publishing Engine - RQM Multi Level Report Tutorial

15. 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 containers Test 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. Rational Publishing Engine - RQM Multi Level Report Tutorial

16. Structure • Your template should now look something like this • You will not have the paragraphs and text Rational Publishing Engine - RQM Multi Level Report Tutorial

17. Configure Data Source Configuration To 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. Rational Publishing Engine - RQM Multi Level Report Tutorial

18. 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. Rational Publishing Engine - RQM Multi Level Report Tutorial

19. 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 Rational Publishing Engine - RQM Multi Level Report Tutorial

20. Stage 3 – Sort and Filter your Report • Sort the report. • Filter the report Rational Publishing Engine - RQM Multi Level Report Tutorial

21. 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 Rational Publishing Engine - RQM Multi Level Report Tutorial

22. 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 Rational Publishing Engine - RQM Multi Level Report Tutorial

23. 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 Rational Publishing Engine - RQM Multi Level Report Tutorial

24. 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 Rational Publishing Engine - RQM Multi Level Report Tutorial

25. Structure of the Second Level The 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 containers Test 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. Rational Publishing Engine - RQM Multi Level Report Tutorial

26. Configure the testCase feed Data Source To 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). Rational Publishing Engine - RQM Multi Level Report Tutorial

27. 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. Rational Publishing Engine - RQM Multi Level Report Tutorial

28. 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 Rational Publishing Engine - RQM Multi Level Report Tutorial

29. 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. Rational Publishing Engine - RQM Multi Level Report Tutorial

30. 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. Rational Publishing Engine - RQM Multi Level Report Tutorial

31. 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 Rational Publishing Engine - RQM Multi Level Report Tutorial