This is the first of a series of articles covering how to author reports in IBM Engineering Lifecycle Optimization – Publishing (PUB) Document Studio that report specifically on linked data, for example, requirements satisfied by model elements, rather than a detailed report on a single data source.

A POX on It!

Most of the ELM tools now support POX (that’s Plain Old XML) which makes reporting on any kind of linked data much easier – and that might be standard OSLC links or even ‘internally’ linked data such as, for example, a Module in DOORS Next uses requirements. Essentially a GET request with an extra POX header returns the reportable data rather than the user-level data. A simple example would be to use the ‘Share Link to Artifact’ menu for a requirement in DOORS Next – that gives you a URL that you can paste into a web browser and directly access that requirement. That same URL can be used by PUB to get the reportable data by adding POX to its request. This is important when creating reports as the link data returned by an artifact is often the ‘non-reportable’ or UI version of the link. POX means you do not have to manually transform that URL into the reportable one – it’s all handled by PUB. In practice it’s very easy to use and we’ll be using it in the sample templates we build in this series, but if you want more information on it you can find that here: POX

General Workflow

Reporting on linked data can be a bit of a black art and each tool handles it differently but in general the steps for the same:

Obtaining the Link URL

Obtaining the link URL is entirely dependant on the data source. For example, in DOORS Next, links are found underneath a Traceability node in the data source schema:

Data Source Configurations (DSC)

The core of reporting across different schemas in PUB, whether that’s reporting on requirements in a module or test cases that validate those requirements, is the Data Source Configuration. This instructs PUB to switch from the current data source schema to another one, effectively it tells PUB which ‘lens’ to use when looking at the linked data.

To use a DSC, first, add it into a container just like any other PUB element. If you are using drawers then you will find it in the Data drawer:

DSC Properties

A DSC has key properties on:

• The Data tab
• The Dynamic configuration tab (Note that this tab only appears after you click away from the newly-added DSC and then re-select it)

The Data tab

The Data tab has two key fields:

• Target data source: The new schema to use
• Inherited data configuration: This allows the data source schema to inherit from an existing one. This is very useful as you can also hide the data source schema, and the user of the report only has to enter their credentials once.

The Dynamic configuration tab

The Dynamic configuration tab has a few more fields but the two key ones you need are:

• URI: This is the URI of the linked element
• Extra Headers: Here you can select POX (if the URI above is non-reportable)

A note on data source schema inheritance: Using the Inherited data configuration field will make the DSC inherit everything – not just credentials but also things like Extra headers. Sometimes you will inherit the POX header when you don’t need it – which causes a problem. In such cases simply putting ‘dummy’ into the Extra Header field prevents it from inheriting POX. Don’t worry – in the examples, I’ll point out where this would happen.

Hiding Data Source Schemas

As mentioned above, a DSC can inherit from another one. In most cases, this means that the user should not have to enter any details about that data source – in which case you can hide it from them entirely. This keeps the DSX nice and clean and makes the template easier to consume. To hide a data source schema, select it in the Outline panel of the template editor and set its Configuration required property to hidden:

That’s it for now. In the following parts of this series, we will discuss how to use a REST client to interrogate your data sources so that you can ‘see’ what PUB sees, and we’ll cover how to report on linked data from any of the Jazz data sources to any of the other Jazz data sources, starting with reporting from requirements in DOORS Next to linked designs in architecture management, link test cases in test management and linked work items in workflow management.

Check out Part Two in this series: Using a REST Client to Interrogate Resources

Andy Lapping
Technical Enablement Specialist
Watson IoT & Engineering Lifecycle Management