Rhapsody Model Manager (RMM) provides two reporting schemas:

• Rhapsody Model Schema
  • Provides some basic information about the model stored in RMM
  • If you intend a more detailed report then you should design and run the report against the Rhapsody desktop client
• Rhapsody Traceability Statistics Schema
  • Provides statistical information of traceability from model elements in RMM to other artifacts across the lifecycle

This article will focus on the schema for Rhapsody Traceability Statistics.

Obtaining a Data Source Schema

As with any PUB report, the first thing we need is a data source schema. This API is relatively new so there is no UI support for it at all – we must manually construct all URLs.

The URL for obtaining the schema for a statistics report is:

<RMMServer>/reporting/rhapsody/ArchitectureElementStatistics?metadata=schema

For example:

https://ibmjazz:9443/am/reporting/rhapsody/ArchitectureElementStatistics?metadata=schema

If you are using V9 with the combined AM and CCM server then you would use:

https://ibmjazz:9443/ccm/reporting/rhapsody/ArchitectureElementStatistics?metadata=schema

We can use that URL to add a new REST Data Source Schema to our template:

Creating a Template

We can now create our template by iterating over any one of the schema nodes shown above. In this simple example, we’ll report the numberOfElementsWithoutLinks.

Later we will configure the report to report on specific types of model elements and specific types of links.

Configuring the Data Source

This is the complex part of the process as we have to construct the data source URL manually, and it has several mandatory and several optional parts. I recommend compiling the URL in a text editor before copying and pasting it into the Document Studio document specification URL field.

First of all, the base URI for reporting statistics is the same as that which we used to get the schema (minus the ?metadata=schema part)

<RMMServer>/reporting/rhapsody/ArchitectureElementStatistics

For example

https://ibmjazz:9443/am/reporting/rhapsody/ArchitectureElementStatistics

The first mandatory argument is the project on which we want to report. How we specify that information depends on whether the project is GC-Aware or not.

If the Project is GC Aware

In this case, we must supply the projectId parameter.

Obtaining the Project ID

To obtain the project ID, open the administration page for the RMM project (open the project and then click the admin cog and select Manage this Project Area).

In the web browser address bar, the final parameter is itemId – this value is used as the projectId parameter in the compiled reportable URI. For example:

Our reportable URL would now look like this:

https://ibmjazz:9443/am/reporting/rhapsody/ArchitectureElementStatistics?projectId=_34xkkCh3EemuGZki5LfU2g

If the Project is Not GC Aware

In this case, we have two options:

• Supply the context parameter. Not only will this focus the report on a specific local stream, but the RMM project will also be derived from this.
• Do not supply the context parameter. The report will run on the base stream – but in this case, we must instead supply the projectId parameter as above.

Obtaining the Context

To obtain the local context, open the administration page for the RMM project (open the project and then click the admin cog and select Manage this Project Area).

In the web browser address bar, look for the oslc_config.context parameter:

Our reportable URL would now look like this:

https://ibmjazz:9443/am/reporting/rhapsody/ArchitectureElementStatistics?oslc_config.context=https%3A%2F%2Fibmjazz%3A9443%2Fam%2Frtcoslc%2Fscm%2Fconfig%2Fs%2F_5MU3ICh3EemuGZki5LfU2g

Additional Mandatory Parameters

Regardless of whether the data source is GC aware or not, the URL must also include the following two parameters:

• filterTypes: Filter the report on only specific model element types
• filterLinkTypes: Filters the report / calculations on only specific link type(s). Possible types are:
  • derives
  • refine
  • satisfy
  • trace
  • validatedby
  • elaborates
  • external

When adding parameters to a REST URI, the first parameter name should be prepended by ? whilst any subsequent parameters should be prepended by &

Our (GC Aware) reportable URL might now look something like this:

https://ibmjazz:9443/am/reporting/rhapsody/ArchitectureElementStatistics?projectId=_34xkkCh3EemuGZki5LfU2g&filterTypes=UseCase,SequenceDiagram&filterLinkTypes=trace,refine

Additional Mandatory Scope Parameter

Regardless of whether the data source is GC aware or not, the URL must also include at least one of the following scope parameters. Note that starting from version 7.0, the full scope of the project and configuration will be applied by default and these parameters become optional.

• componentName: Filters the report on a specifically named component in the project (multiple component names may be supplied separated by a comma).
• projectArea: Filters the report on the named project. The report will run on all the components in that project.
• resourceScope: Filters the report on a specific RMM artifact (and its aggregates)
  • Obtain the URI of an artifact by navigating to it in the RMM web client and clicking the chain symbol in the breadcrumb (and also remove the context information from the URL).

Our reportable URL now might look like one of these:

https://ibmjazz:9443/am/reporting/rhapsody/ArchitectureElementStatistics?projectId=_34xkkCh3EemuGZki5LfU2g&filterTypes=UseCase,SequenceDiagram&filterLinkTypes=trace,refine&projectArea=Adaptive Cruise Control Models

https://ibmjazz:9443/am/reporting/rhapsody/ArchitectureElementStatistics?projectId=_34xkkCh3EemuGZki5LfU2g&filterTypes=UseCase,SequenceDiagram&filterLinkTypes=trace,refine&componentName=ACC-System-Cmp

https://ibmjazz:9443/am/reporting/rhapsody/ArchitectureElementStatistics?projectId=_34xkkCh3EemuGZki5LfU2g&filterTypes=UseCase,SequenceDiagram&filterLinkTypes=trace,refine&resourceScope=https://ibmjazz:9443/am/resource-rmm/1014982

We can now paste that URL into the document specification, not forgetting to add credentials:

Reporting on Global Configurations

If the data source is GC-aware then you must specify a context in Document Studio document specification. You can do this by using the OSLC picker in Document Studio (OSLC Configuration Selection).

You would need to supply the rootservices path to your global configuration application, for example, https://ibmjazz:9443/gc/rootservices.

You can also add the configuration manually, by obtaining the URL for a configuration and pasting that into the Configuration-Context field.  The GC configuration URL may be obtained from the GC tool by accessing the specific configuration you want to report on and clicking the Copy Link button:

And that’s all you need to generate a document.

Reporting Percentages

The percentage of figures returned by RMM are all decimals but that can be easily turned into more human-readable text with a bit of JavaScript:

var p = percentageOfElementsWithoutLinks * 100;
p = p.toFixed(2) + '%';
p

Referring to the Data Source Specification in the Template

In a ‘regular’ report we might iterate over a project and, although we specify which project in the data source specification, we can report the project name by iterating over the node from the schema. The statistic schema is different in that you are not iterating over a project – or the data source – but instead its statistics. If you want to report the name (or any other attribute) of the data source then it is useful to know how to extract that from the data source specification so that it can be referred to in the project. Fortunately, we can do that fairly easily with a bit of JavaScript at the start of our template that stores the different parts of the data source URI as variables that we can refer to later in the template.

First, we add a variable (we would usually add a variable for each piece of the puzzle, data source, link filter and so on but here we’ll just add one for the entire data source URL to demonstrate the concept).

We can then add a JavaScript node to the start of the template and access the predefined _sessionInfo variable to get the data:

_dataSourceURL = _sessionInfo.getDatasourceProperty('RMM Stats', 'URI', '');

After that, we could add more JavaScript to break the URI up into its component parts and store them in other variables. We can even use the URIs in data source configurations to interrogate the model elements if we wanted to.

We can find out the global configuration being reported on in the same way – all of which helps to make a decent cover page for this kind of report.

_gcConfigurationUri =  _sessionInfo.getDatasourceProperty('RMM Stats', 'Configuration-Context', '');

That’s it for this posting! Hopefully, it has given you a good starting point to create model traceability statistics reports.

Andy Lapping
Technical Enablement Specialist
Watson IoT & Engineering Lifecycle Management