In the previous blog postings we’ve covered how to report on links from requirements to models, test cases and work items, and from model elements to test cases, work items, and requirements. In this article, we’ll cover how to start the report from a work item and obtain the links to those other artifact types.

Reporting on work items is somewhat different from reporting on models and requirements as we’ve done in previous articles. The Engineering Workflow Management (EWM) REST API:

• Has no support for POX – all links must be manually constructed using javascript
• Provides no mechanism to report on a single artifact (directly), instead, the API accepts a query that returns a collection of elements (you could, of course, construct that query such that it returns a single element)

This approach adds flexibility and in some cases can be more performant – for example, if you wanted all ‘high priority’ work items, those can be retrieved directly from the data source by constructing an appropriate query, rather than retrieving all work items and having Document Studio then filter them afterward. However, the downside is that the construction of the template is a little more complex.

Interrogating EWM Using a REST Client

The base reporting URI for EWM is:

 https://<servername>:<port>/<ccmContextRoot>/rpt/repository

This will then first be appended by the ‘monolithic’ resource type – of which there are five:

• foundation: Common artifacts such as project areas, team areas, contributors, iterations, and links
• SCM: Source Control artifacts such as streams and components, as well as stream sizing deltas
• build: Build artifacts such as build results, build result contributions, build definitions, and build engines
• apt: Agile Planning artifacts such as team capacity and resource schedules and absences
• workitem: Work Item artifacts such as work items, categories, severities, and priorities

Then the URL is appended with ?fields= and various paths to construct a query that defines what you want to retrieve. Here are some examples using the workitem monolithic resource:

Retrieve the ID of every work item:

https://ibmjazz:9443/ccm/rpt/repository/workitem?fields=workitem/workItem/id

Retrieve the summary and id of every work item:

https://ibmjazz:9443/ccm/rpt/repository/workitem?fields=workitem/workItem/id

Retrieve the summary and id of all work items in the MTM Planning project:

https://ibmjazz:9443/ccm/rpt/repository/workitem?fields=workitem/workItem[projectArea/name='MTM Planning']/(id|summary)

Refer to this page for other examples and a full list of the available parameters: https://jazz.net/wiki/bin/view/Main/ReportsRESTAPI#

This is not only useful for testing your data but you will also need to add information like this to your template as you will see later.

Reporting on Work Items

Obtaining a Work Item Schema

To obtain the schema for the data source we simply add ?metadata=schema to the base artifact reporting URI, for example:

https://ibmjazz:9443/ccm/rpt/repository/workitem?metadata=schema

Document Studio already has work items as one of its predefined Schemas (as before you only need to add the server, port, and credentials)

Reporting Work Item Details

Now we can iterate over workitem/workitem and report any of the details we want:

Configuring the Document Specification

To configure the document specification, we use the same URL that we used to obtain the schema (without the ?metadata=schema part). For example:

https://ibmjazz:9443/ccm/rpt/repository/workitem

And of course, we still need to add credentials:

We can now test the report BUT with the current configuration we will get every work item in the database – so test it by all means, but we should use Preview Document rather than Generate Document

Filtering the Work Item Data

Here is where we need the field selection and filtering options, we referred to briefly in the section above on interrogating EWM using a REST client. The specific section in the wiki can be found here: https://jazz.net/wiki/bin/view/Main/ReportsRESTAPI#Field_selection_and_filtering

When we run a report, Document Studio will construct the necessary query. Some parts of that query are created automatically, others we will have to provide. Take this sample query that retrieves the id and summary of every work item in the MTM Planning project:

https://ibmjazz:9443/ccm/rpt/repository/workitem?fields=workitem/workItem[projectArea/name='MTM Planning']/(id|summary)

The part in blue we provide in the Document Specification URI property

The part in red is automatically constructed by Document Studio from our template (when we add a text element and select the id and summary attributes)

Document Studio also adds the other necessary characters like ?fields=, square brackets and so on

What we need to add to the template is the criteria that filter the returned data, highlighted in green in the query above, that is projectArea/name=’MTM Planning’

These filters are added in the Native Filter tab in the Document Studio editor:

Obtaining Link Data

There are multiple types of ‘link’ in the EWM schema. Links to requirements, tests and model elements all appear under auditableLinks

This information also appears in the wiki we referenced earlier:

So we can start by iterating over those auditableLinks:

Adding a Data Source Schema for Links

Even though the link data appears in the workitem schema – schemas are not re-usable in Document Studio and so we must add a second ‘RTC Workitem’ data source schema with the same URL we used previously, but with a different name:

Adding a Data Source Configuration for Links

Now we can switch schemas using a Data Source Configuration:

Then we can iterate over the auditableLink node – making sure its the one from the RTC Links data source, not the one for the original Workitems data source:

Reporting on Link Targets

At this point, we have a link where the name attribute gives us the link type, and targetRef subnode gives us the link URL. All we need to do is filter the link to make sure we know what type of thing we are reporting on, and then add another data source configuration to switch to a schema for requirements, models, or tests. All of that is covered in previous posts but one thing to note is that so far we have not used POX at all in this template, so if the target of the link is (for example) a requirement, then we will need to add POX in the data source configuration.

Here is an example of reporting linked requirements:

 

That’s it for now – in the next blog posting, we’ll tackle how to start a report from a test case.

Check out Part Six in this series: Reporting from Engineering Test Management

Andy Lapping
Technical Enablement Specialist
Watson IoT & Engineering Lifecycle Management