Reporting on a reporting tool.

Initially, it sounds like an odd concept right? It’s actually a very useful capability.

Jazz Reporting Services Report Builder (JRS) provides a web-based UI for designing reports. These reports are primarily focused on presenting live data, typically on dashboards, in the form of tables or graphs. While these can be exported to physical documents such as word or pdf, those documents are pretty basic. What I mean by that is that they only contain the table or graph that would otherwise be presented on a dashboard. They are not complete production-ready documents, there is no facility to add stylesheets, headers, footers, cover pages and so on. That’s not the purpose of JRS – its the purview of PUB. Combining the two provides the best of both worlds.

JRS can take the heavy lifting out of designing traceability tables. For example, a table of requirements in a module in DOORS next along with their linked test cases and the test results of those test cases can be designed in JRS in a matter of minutes. The same table in PUB would take much longer and would involve multiple data source schemas and multiple data source configurations as you switch from a module to the text in it, to a test case, to test results.

Also, JRS can produce pie graphs, bar charts, and line graphs all using a simple, intuitive UI.

By exporting these JRS reports out in PUB format we can then edit them in PUB Document Studio, combining them with other data and adding the headers, footers and so on that go into creating a production-ready document.

Getting Reports Out of JRS

There are two ways you can get a report out of JRS and into PUB:

• Export from JRS (this is done in the JRS web UI)
• Import to PUB (this is done in the Document Studio URI)

Exporting from JRS

First, we will need some sort of report in JRS. Once saved,  we can run it and on the results page is an Export button that allows us to export that report to various formats, including PUB (in version 6.x this is still called Rational Publishing Engine).

The export then provides us with the following options:

• Create a PUB Document
  • This option creates a complete template file (DTA) and a document specification file (DSX)
  • We can then edit that template just like any other
• Add to an Existing PUB Document
  • This does not give us the report in the form of a table (or any other format). Instead, it gives us the data that the report contains, in the form of a data source schema URL and a data source URL. We are then responsible for creating our template by iterating over the results of the report.
• Insert a Report Image into a PUB Document
  • This is the simplest option and provides a URL that we can use as the Content property for an image node in any template

Let’s take a closer look at those three options.

Create a PUB Document

This option provides two clickable links that we can use to download both a template and a document specification (and we can choose whether the template presents the report as a table or a list. If the report is also capable of being displayed as a graph then that option would also be available).

Important Note: After downloading the files, make sure you open the template in Document Studio before switching to the launcher perspective and opening the document specification. If you open the document specification first and then open the template, Document Studio will replace the doc spec with a new, empty one and you will have to re-open the downloaded document specification again.

If we examine the template we can see that there is a single data source – the JRS report and the table (or list) iterates over results/result:

If we examine the document specification we can see it is fully configured (we can go ahead and generate it without any further configuration).

Things to note:

• The data source URL is ‘fully configured’ – what I mean by that is that the single URL contains not only the data source but also the configuration on which to report.
• The authentication is already configured using a web cookie

Both of the above will become more important when we want to add more data sources or combine this template with other templates. More on that later.

Add to an Existing PUB Document

As mentioned above this option does not give us any new files, but instead provides us with two URLs:

• The Data Source Schema URL (We use that to insert a new REST Data Source to our template)
• The Data Source URL (We use that to configure the URL in our document specification – we will also need to add credentials to generate a report)

We can then build our template by iterating over the results of the report.

If what we wanted was to insert a report table into an existing template, then we would not use this option at all. Instead, we would use the first option to generate a new template and insert that new template into our existing one in Document Studio (Template > Insert Template / Insert Template Special). We would also need to copy the entries from the generated document specification into our document specification.

Insert a Report Image into a PUB Document

This is the simplest option and merely provides a URL. In our template we add an Image node and use the URL as the Content:

Authenticating

As this is still a JRS report, we still need to authenticate to ensure we only see data we are allowed to see. However, there is no ‘data source’ entry in the document specification for an image node. So if we use this method, we must specify our credentials in the Template entry:

Importing Reports into Document Studio

There are two ways to start the import operation.

• Drag and drop from the URL of the JRS report in the web browser address bar into Document Studio
  • Before trying this make sure you click inside a template in Document Studio or the drag and drop operation will fail
• Use the menu Template > Import Web Resource
  • Before trying this make sure you click inside a template in Document Studio or the menu entry will be greyed out

Also, in either case, make sure it is the report URL you use – not the report result URL. That is, click the report name in JRS and take the URL before it has been run. The difference is that the report URL looks like this:

https://ibmjazz2:9445/rs/reports#view=7

Whilst the report result URL looks like this:

https://ibmjazz2:9445/rs/reports#view=7&filterValues=%7B%22version%22%3A%222.0%22%2C%22values%22%3A%7B%22ProjectIds%22%3A%5B%22https%3A%2F%2Fibmjazz%3A9443%2Frm%2Fprocess%2Fproject-areas%2F_JOJ8ACh4EemVPLB5OjtkPg%22%5D%2C%22oslc_config.context%22%3A%5B%22https%3A%2F%2Fibmjazz%3A9443%2Fgc%2Fconfiguration%2F4%22%5D%7D%7D

Dragging a URL or using the Import Web Resource menu will start the import wizard, which presents two options:

• Create a link within the existing template
  • This option is not at all useful for Jazz based resources and should be ignored
• Create a new template for the web resource URL
  • This is almost analogous to the Create a Pub Document export option from JRS (in that it creates a new template and a new document specification) but there are some differences, which we’ll look at now.

First, the wizard presents the option to create the template in Book, Table or Graphic format:

These are the same options that we had in JRS Export, except Document Studio calls the List option ‘Book’. The generated template is the same but the document specification is slightly different in that it adds basic authentication rather than a web cookie:

Combining JRS Reports With Existing Templates

The concept is very simple – let’s say we wanted to create a template in Document Studio that reported on a module of requirements, and then insert a table of traceability and a graph that we produced in JRS for that same module. We would first export the JRS reports as full templates with their corresponding .dsx files. In our main template, we can then import those two other templates. This is where we run into some limitations which we can overcome but we need to be aware of them.

Each Inserted Template Appears in the DSX File as a Separate Entry

Unlike data source configurations that can inherit from other data sources (allowing us to hide them from the data source specification), data sources cannot inherit from other data sources. That means our DSX file would have three entries (the module we are reporting on and the two JRS reports) and we would have to supply credentials and URLs for each (the URL we can copy from the auto-generated DSX file and we can use the username and password fields to authenticate).

Each Data Source Must Be Manually Kept in Sync

Let’s say in our JRS report, we configure it to report on requirements module X (by adding a condition to the report). Then in our DSX file, we configure our (manually created) data source to also report on module X using the OSLC resource picker. Now we want to report on module Y instead. We can use the OSLC picker again to select module Y for our data source – but what about the two JRS reports? Both of those have the data source encoded into their URL. We have to modify those URLs manually. Similarly, if the data source is GC-aware then the choice of configuration is also coded into that URL.

We can overcome both of those issues, but to do so we need to dissect the auto-generated URL. Here is an example of a URL generated from a JRS report, reporting on a module, with a single condition – the id of the module on which to report:

https://ibmjazz2:9445/rs/query/66/dataservice?oslc_config.context=https%3A%2F%2Fibmjazz%3A9443%2Fgc%2Fconfiguration%2F4&pName=parmVar_0&pVal=305&rpe=true&basicAuthenticationEnabled=true&limit=-1&report=65&templateFormat=table

The part in green is the configuration on which to report. The part in red is the condition.

The first thing we can do is remove the configuration part completely (and instead use the Configuration-Context field in the Document Studio UI). Note however that since that is the first argument it is prepended by a question mark and subsequent arguments are prepended by ampersands and we need to keep that structure, so the new URL would look like this:

https://ibmjazz2:9445/rs/query/66/dataservice?pName=parmVar_0&pVal=305&rpe=true&basicAuthenticationEnabled=true&limit=-1&report=65&templateFormat=table

We can then modify the URL to use the ID of module Y rather than module X. Of course, these conditions are not identified by name so if you have multiple conditions in your JRS report then you need to take care you are modifying the correct ones.

Other Limitations

Models are not (yet) supported by JRS

Report on model data in the usual way directly in Document Studio

One JRS report = One Table

If you want a table of traceability to tests, followed by a separate table of traceability to model elements then you need two JRS reports – and you need to keep the dsx entries consistent with the rest of your template as described above.

That’s it for this time! In the next posting, we’ll explore the new reportable API in Rhapsody Model Manager which is all about getting model traceability statistics.

Check out Part Eight in this series: Reporting on RMM Traceability Statistics

Andy Lapping
Technical Enablement Specialist
Watson IoT & Engineering Lifecycle Management