Author name

Mon, 28 Mar 2022

5 min read

Integrating external data sources with LQE and Report Builder

Kathryn Fryer, IBM, Kevin Cornell, Persistent Systems, David Honey, IBM
Last updated: March 2022
Build basis: IBM Collaborative Lifecycle Management Solution (CLM) 6.0.3 or later; IBM IoT Continuous Engineering (CE) Solution 6.0.3 or later

This article is intended for developers who want to contribute data from 3rd-party applications or external data sources to the LQE data source for reporting. It includes references and links to a companion article that describes how LQE and Report Builder process the metadata to support reporting.

The Lifecycle Query Engine (LQE) is a data source provided with the IBM Collaborative Lifecycle Management (CLM) and IBM IoT Continuous Engineering (CE) solutions. This article describes how to publish data and metadata from your application or external data source to LQE so users can report on the data using Report Builder, as they do for the CLM/CE applications. This is particularly relevant if your application supports configuration management; LQE is the required data source to report on configuration-enabled projects and versioned data.

LQE supports the tracked resource set (TRS) specification, using TRS feeds contributed by the CLM lifecycle applications to create and maintain an index of link-accessible resources. Reporting applications such as Report Builder (RB) and Rational Engineering Lifecycle Manager (RELM) use LQE as a data source for reporting. (Note that this article does not address RELM requirements or usage, nor does it address data-warehouse-based reporting.)

To contribute your data to LQE, you need to:

Publish your application’s data and metadata as tracked resource sets in tracked resource sets:
- Process resources, including project areas, service providers, and access context
- Configurations and components, if you provide them
- Resource shapes for each type, with all defined properties for that type
- Data instance resources (which may be versioned)
For each kind of resource, provide the necessary metadata to include your resources and properties in Report Builder, including:
- Access control based on project area permissions
- Merging of equivalent types and properties across projects, using resource shapes and external URIs
- The ability to report on relationships in either direction
- Localization into different languages, if needed

Details follow on how to publish your resources with the appropriate metadata for RB to use. Refer also to the diagrams of published resource relationships which depict the metadata and how the resources reference each other. The Jazz.net article A look inside LQE and Report Builder describes how LQE and RB process metadata to surface resources to the report author and in report results.

Although this article references “your application”, the information applies to any external data source integrating with LQE.

You should be familiar with OSLC, RDF, and TRS fundamentals. For background on those topics, see the OSLC specifications listed at the end of this article. The Eclipse Lyo project offers workshops for OSLC and TRS providers.

Note: If your application or data source will contribute a significant amount of data to LQE, it could impact LQE and reporting performance. Familiarize yourself and your consumers with best practices for configuring LQE and monitor the amount of data you generate and its impact.

Publishing your metadata and data

There are essentially two ways to publish your metadata and data:

Static vocabularies
Tracked resource set (TRS) 2.0 providers (feeds to LQE)

Typically, static vocabularies define generic RDF types (usually OSLC types) that might be referenced by multiple tools and used for cross-project reporting. The CLM/CE solution includes many static vocabularies which are automatically published when you set up LQE; you can find and browse them on an LQE server at https://server:port/lqe/admin/vocabularies. This article includes a list of published vocabularies and the prefixes commonly used to reference them under Common Prefixes for metadata vocabularies.

TRS providers, registered as feeds in LQE, publish new and updated metadata such as types and properties. They also publish the data instance resources (the artifacts and properties) to LQE. Applications can reference and extend the static vocabularies in their TRS feeds.

Third parties can define additional vocabularies if they implement types that could be used across applications. An administrator can manually add the vocabularies to LQE. Because of the nature of static vocabularies, as well as some known issues, most third-party applications or external data sources should provide primarily TRS feeds.

Defining static vocabularies

Static vocabularies are typically defined in RDF or Turtle files, using OWL-based ontologies. If you provide a vocabulary, define an ontology as:

<ontologyURI> rdf:type owl:Ontology.

Define each resource type that belongs to an ontology as a Class (rdfs:Class):

<typeURI> rdf:type rdfs:Class ;
   rdfs:isDefinedBy <ontologyURI> .

Define each property or attribute for the resource type as a Property (rdf:Property), including the type that asserts it (rdfs:domain predicate) and the target type of its expected value (rdfs:range):

<propertyURI> rdf:type rdf:Property ;
   rdfs:domain <typeURIorClass> ;
   rdfs:range <typeURIorClass> .

If a single property can be asserted by different types of resource (more than one Class), omit the rdfs:domain statement. (According to the RDF specification, multiple rdfs:domain statements imply an AND relationship, where the subject resource of the property is an instance of all of the defined types, which might not be true.) Instead, define the property in each of the resource shapes for the types that assert it. See the section Publishing OSLC resource shapes, as well as the article A look inside LQE and Report Builder, for more information about reporting on types and shape types.

Static vocabulary issues

When integrating third-party applications with LQE and RB, you should be aware of several known issues with vocabulary-based RDF types:

In most cases, RB automatically exposes all RDF types in the Choose an Artifact section. However, RB coded logic to hide certain RDF types that were not useful to report on. If your application adds a new RDF type to a vocabulary, the type might or might not appear in the Choose an Artifact section of the report editor. You can’t specify whether to display or hide the RDF type.
RB also uses hard-coded logic to automatically add default properties to RDF types, so that report authors can always extract some standard information for resources of that type (for example, dcterms:title, dcterms:creator, and similar properties). The default properties can vary by RDF type, and you cannot specify which properties to add to your RDF types.

Work item 387256 on Jazz.net tracks these issues. Because of these issues, most third-party applications or external data sources should use TRS feeds instead of static vocabularies.

Defining TRS providers

Applications should define TRS providers consistent with the OSLC 2.0 specification, especially if publishing versioned resources and configurations. The OSLC Tracked Resource Set 2.0 and Indexable Linked Data Provider 2.0 specifications provide general details on how to define tracked resource sets and TRS providers, and the Eclipse Lyo project includes a TRS provider workshop; this document focuses specifically on what is required for reporting with the Jazz Reporting Service LQE data source and Report Builder user interface.

Most applications need to define at least two TRS providers:

One that defines process resources, like project areas and OSLC providers
One (or more) that defines the data resources and metadata that users report on, including configuration and components, resource shapes, and instance resources

To understand the relationships between the different kinds of published resources, see Diagrams of published resource relationships.

Each TRS provider must define the dcterms:type property to classify the feed’s resources; the value (object) is usually an OSLC domain URI such as:

http://open-services.net/ns/am#
http://open-services.net/ns/cm#
http://open-services.net/ns/qm#
http://open-services.net/ns/rm#
http://open-services.net/ns/config#
http://jazz.net/ns/process#

LQE uses this type property when merging resource shapes, as described in the article A look inside LQE and Report Builder.

Each TRS provider can also define one or more oslc:domain properties to indicate the types of resources provided.

Publishing process resources

There are three categories of process resources to define:

Project area and related resources
OSLC service provider resources
OSLC access context resources

RB and LQE use these resources to define a user’s access and visibility to the metadata (usually based on project area permissions) and for filtering in both the RB UI and generated report queries.

If your application is based on the Jazz Application Framework (JAF) SDK, you can define your process TRS feed simply by adding the following TRS 2.0 provider definition to your application’s discovery page:

<trs2:TrackedResourceSet>
   <trs2:trackedResourceSet rdf:resource="https://host:port/app/process-trs2"/>
      <dcterms:title>TRS 2.0 for XXX Process Resources</dcterms:title> 
      <dcterms:description>Process resources in XXX</dcterms:description>
      <dcterms:type rdf:resource="http://jazz.net/ns/process#"/>
      <oslc:domain rdf:resource="http://jazz.net/ns/process#"/>
</trs2:TrackedResourceSet>

If your application is not built on JAF, you must define your own TRS process feed as defined in the following sections.

Publishing project area and related resources

Your TRS feed must define your application’s project areas and related resources as defined by the Jazz Foundation Process Vocabulary, including (where applicable):

Project area (rdf:type process:ProjectArea)
Team area (rdf:type process:TeamArea)
Iteration (rdf:type process:Iteration)
Timeline (rdf:type process:Timeline)

LQE and RB use project areas to associate resources and resource shapes, to filter projects in the Limit Scope section in the report editor, as well as filtering the artifact types and attributes based on selected projects, and to scope report results.

To ensure project filtering works correctly, all data resources belonging to a project area must include the property:

<resourceURI> process:projectArea <projectAreaURI>.

where the project area’s URI has the format https://server:port/app/process/project-areas/projectGUID .

For more information on how LQE and RB use project area information for report authoring, see the separate article A look inside LQE and Report Builder.

If your application does not define project areas

If your application does not define project areas consistent with the CLM applications, you must take additional steps to enable the desired access control and RB UI behavior for your users. You must either:

Simulate one or more project areas for your resources (recommended).
Simulating project areas allows for a more granular level of access control for your application’s resources. It also ensures that RB can include those project areas in its Limit Scope and runtime filters, and correctly filter the resources.
Decide whether your application’s resources should be treated as a single monolithic project area or subdivided into smaller logical project areas, based on how granular you want to make the access control and filtering options for report users. Based on that decision, define one or more resources of rdf:type process:ProjectArea to represent your logical project areas, with equivalent OSLC service provider resources as described in OSLC service provider resources.
For each resource shape, include both the oslc:serviceProvider and process:projectArea properties for the corresponding project area. Each instance resource must also define the correct process:projectArea value for the project area it belongs to. To enable access control for reporting, your process and resource graphs must also define and reference access context resources, as described in OSLC access context resources.
With the metadata described above, RB will recognize your application’s simulated project areas and correctly associate its resource shapes and resources. RB will include your simulated project areas in the Limit Scope section of the report editor, and display the associated types and properties for those project areas.
Omit the project area concept entirely. (Note: limited testing has been done for this scenario.)
Do not publish any OSLC service provider or project area resources in your process TRS feed, and do not include oslc:serviceProvider or process:projectArea properties for your resource shapes or instance resources.
In this case, all your application resources must define the same access context, as described in Defining access contexts for applications without project areas; users will have permission to report on either all or none of the resources for your application.
Omitting project areas impacts the reporting user. RB will not display any identifier for your application in the Limit Scope section. Although users can still report on your application’s resources, any report that specifies a project area scope will exclude resources from your application, since they do not belong to any project area. For this reason, we suggest simulating at least one project area for your application.

Publishing OSLC service provider resources

OSLC service providers can correspond to a project area or to a configuration or component. The service provider for the project area resource defines one OSLC Publisher resource and one or more OSLC Service resources that indicate the domains (oslc:domain) of the resources in the project area.

Note: If your application does not define project areas, you must either simulate them and define appropriate service provider resources, or omit project areas and OSLC service providers entirely, as described in the section above.

In your process TRS feed, publish a single graph that includes all 3 types of OSLC resources (service provider, publisher, and services) as shown in the following example (URIs differ by application):

<oslc:ServiceProvider rdf:about="<serviceProviderURI>">
   <oslc:details rdf:resource="<projectAreaURI>"/>
   <jfs_process:globalConfigurationAware>configSupport</jfs_process:globalConfigurationAware>
   <dcterms:publisher>
      <oslc:Publisher rdf:about="<application-aboutURI>">
      <dcterms:title>Application Name</dcterms:title>
      <dcterms:identifier>http://jazz.net/application/xx</dcterms:identifier>
      <oslc:icon rdf:resource="<Application_16x16_IconURI>" />
      </oslc:Publisher>
   </dcterms:publisher>
   <oslc:service>
      <oslc:Service>
         <oslc:domain rdf:resource="http://open-services.net/ns/xx#"/>
      </oslc:Service>
   </oslc:service>
</oslc:ServiceProvider>

A service provider can define multiple oslc:details properties; RB relies on the oslc:details property that defines the URI of the corresponding project area resource. RB uses that value to associate project areas to resources and resource shapes; resources and resource shapes must reference the project area where they are defined (using the oslc:serviceProvider property).

RB uses the oslc:domain property for the OSLC service resources to indirectly identify the types of resources found in the project area. RB can then warn the user if they choose to report on domain-specific types, but none of the selected projects provide resources for that domain.

The Jazz-specific property jfs_process:globalConfigurationAware indicates what support the application and project area provide for configurations and versioned artifacts. As described in the Jazz.net article on enabling your application for configuration management, set the value of this property to one of:

yes – the project area supports configurations and versioned resources.
no – the project area has no support for configurations or versioning.
compatible – the project area does not have configurations or versioned data, but can still link to or interact with versioned resources. For example, the Rational Team Concert Change Management application has compatible project areas that can inter-operate with both configuration-enabled and non-enabled projects.

RB uses this value to filter projects in the Limit Scope section based on which data source the report author selects. When the user selects the “LQE scoped by a configuration” data source, RB shows projects where the value is yes or compatible. When the user selects the “LQE” data source, RB shows projects where the value is no or compatible.

If the RB interpretation of jfs_process:globalConfigurationAware is not appropriate for your application’s project areas, you can override it by setting the jrs:projectConfigSupport property for either the service provider or individual project area resources to one of the following values:

yes – Include this project when the user selects the “LQE scoped by a configuration” data source.
no – Include this project when the user selects the “LQE” data source.
compatible – Include this project when the user selects either LQE data source option.
hide – Do not display this project in Limit Scope (used for system projects that the user should never select when specifying scope).

RB will then use the jrs:projectConfigSupport value and ignore the jfs_process:globalConfigurationAware value for reporting purposes.

Publishing OSLC access context resources

LQE uses the access contexts defined in application TRS feeds to set permissions for users to report on the application resources. In the CLM/CE applications, each project area specifies read permissions in its Access Control settings (usually based on project membership). LQE automatically maintains consistency between the project settings and reporting permissions. (Note that the LQE Administrator can grant additional reporting permissions, as described in the Managing user access topic in the IBM Knowledge Center.)

To control reporting access to your external data, your TRS feeds must define access context resources for the project areas in your application, and reference those contexts in all your resources. The sections that follow describe how to define these resources.

Note: If your application does not define project areas, how you define access contexts depends on whether you simulate project areas or omit them entirely, as described in Defining access contexts for applications without project areas. Deciding whether to simulate or omit project areas affects more than access control; see If your application does not define project areas to determine what is best for your application.

Your TRS feed and published access context resources appear in the LQE administration Permissions page. The LQE administrator can then add individuals or groups to those access contexts, granting those users permission to report on the resources that reference that access context.

Alternatively, you can define a special access context property value to permit all authenticated Jazz Reporting Service users to report on your application’s resources, as described in Setting access to all reporting users. In that case, access is granted automatically; the LQE administrator does not need to manually assign permissions.

For more information on how RB and LQE implement access control, see the article A look inside LQE and Report Builder.

Defining access context resources

Your application’s process TRS feed must define access context resources for each project area or simulated project area in your application. All your application’s resources, including process resources, resource shapes, and instance resources, must reference the appropriate access context for the project area they belong to.

To define access context resources:

In your application’s process TRS feed, publish a single acc:AccessContextList resource:
```
<accessContextListURI> rdf:type acc:AccessContextList.
```
The graph for the acc:AccessContextList must contain an acc:AccessContext resource for each project area in your application. Each acc:AccessContext in the graph defines the following properties:
```
<accessContextURI> rdf:type acc:AccessContext ;
   dcterms:title “name of project area” ;
   dcterms:description “project description”.
```
For every published resource in your resource TRS feeds, including resource shapes and the process:projectArea resources, define the acc:AccessContext property in its resource graph URI, referencing the accessContextURI for the project area it belongs to:
```
<resourceURIgraph> acc:accessContext <accessContextURI>.
```
For non-versioned resources, the resourceURIgraph is the concept resource URI; for versioned artifacts, use the versioned resource URI.

Once the LQE administrator assigns user permissions to the access contexts on the Permissions page, those users can report on the application resources associated to that access context (project area).

Defining access contexts for applications without project areas

If your application does not define project areas, decide whether to simulate or omit project areas for your application, as explained in If your application does not define project areas. How you define access contexts depends on your decision:

If you simulate one or more project areas, follow the instructions in the section above to define an acc:AccessContext resource for each project area, and reference that access context in each resource belonging to that project area. The LQE administrator will grant users access based on your defined project areas.
If you omit project areas entirely, choose one of the following alternatives:
1. Define a single acc:AccessContext resource for the entire application and all of its resources. The LQE administrator will grant users access to either all or none of your application resources.
2. Do not define any access context properties in your TRS feeds or resources. Only your application TRS feeds will appear in the LQE Permissions page; the LQE administrator will grant users access at the feed level (that is, all resources included in a particular TRS feed).
3. Define a special access context property in your TRS feed and in all your resources to make them available to all reporting users, as described in the following section, Setting access to all reporting users. In this case, access is granted automatically; the LQE administrator does not need to manually grant permissions.

Setting access to all reporting users

LQE supports access permissions based on defined project areas and their access contexts, as described above in OSLC access context resources, so users can report only on projects where they have access rights. Alternatively, instead of defining a specific access context resource for a project area or your application, you can make all resources available to all JRS users by defining a special access context property in each resource:

<resourceUri> acc:accessContext <http://jazz.net/ns/jrs#AuthenticatedUsers>.

If you specify this access context for all resources belonging to a project area, you would typically define it for the project area resource as well; then the project area would not need to define an acc:accessContext resource.

Similarly, if you specify this access context in all of your application’s resources, the process TRS feed can specify it as well, and would not need to define any acc:AccessContextList or acc:accessContext resources.

Any user with access to the LQE data source can automatically see and report on the resources that specify this access context property; the LQE administrator does not have to manually grant permissions.

Note: Setting this access context property does not affect how RB displays project areas in the Limit Scope section or runtime filter, other than making it visible to all users. RB uses OSLC service provider and project area metadata to determine the project area entries in Limit Scope, and filters types, attributes, and resources based on the project areas; the access context indicates which users can see and report on those project entries and resources. If your application does not publish project area metadata, that can affect how users see the data in Report Builder; see the earlier section If your application does not define project areas for more details.

Publishing OSLC configurations and components

If your application defines OSLC configurations, you must publish the configuration resources with the properties defined below to enable reporting and filtering of versioned artifacts.

As of version 6.0.3, the CLM/CE RM and QM applications support multiple components within a single project area (the GCM application provided this capability in earlier releases as well). If your application also supports components, publish the OSLC component resources with metadata as described in the following sections so that:

Every stream or baseline has one associated component resource
Every component resource has an associated project area
Every instance resource indicates the project area and component

The properties defined in the next sections are required for reporting with LQE and RB, although the OLSC Configuration Management specification might indicate they are optional; the specification might require additional properties unrelated to reporting that are not included here.

Publishing OSLC configurations

For each configuration your application publishes, include the following properties:

<configurationURI> 
   rdf:type oslc_configuration:Configuration;                (required)
   dcterms:title "Configuration Name" ;                      (required)
   acc:accessContext <accessContextURI> ;                    (required)
   oslc:serviceProvider <configurationServiceProviderURI> ;  (required)
   oslc_config:baselineOfStream <streamConfigurationURI> ;   (baselines only)
   prov:wasDerivedFrom <originConfigurationURI> ;            (streams only)
   oslc_component <componentURI> ;                           (required)
   oslc_config:contribution <contributionResourceURI> ;      (for global/aggregate configurations)
   oslc_config:selections <selectionsResourceURI> .          (for local/non-aggregate configuration)

rdf:type oslc_config:Configuration

A configuration must define this type. To distinguish streams from baselines, it can also optionally include a second type statement of either oslc_config:Stream or oslc_config:Baseline. If it does not specify the second type, it must include the oslc_config:mutable property, set to yes for streams and no for baselines. (Note: In 6.0.2, RB requires every configuration to include the oslc_config:mutable property; in later releases, this restriction no longer applies.) Personal streams can define an additional rdf:type property with the value oslc_config:PersonalConfiguration.

dcterms:title

A user-readable name for the configuration. RB shows this name in the filter where the user selects the configuration context for a report.

acc:accessContext

The configuration resource graph must define the access context URI to restrict user access based on project membership. See OSLC Access Context Resources for more details.

oslc:serviceProvider

At least one instance of this property with the URI of the configuration OSLC Service Provider. This configuration service provider is probably different than a project area service provider (whose oslc:details property is the URI of the Project Area resource).

oslc_config:component

The URI of a Component resource that is published to LQE. Like any other instance resource, the Component must include acc:accessContext and process:projectArea properties. (See Publishing OSLC components.)

oslc_config:baselineOfStream

Baseline configurations must define the stream configuration from which the baseline was created. The exception is if an application creates an empty baseline for an initial stream, which currently applies only to the GCM application; most applications create an initial stream without generating an empty baseline.

prov:wasDerivedFrom

Stream configurations define one or more baseline configurations that contain the initial resources for the stream (that is, the baseline from which the stream was created). If an initial stream does not have a root baseline, it would omit this property; currently, only the GCM application creates an empty baseline for its initial stream.

oslc_config:contribution

Global configurations, both streams and baselines, must define this property to indicate another configuration that contributes to the global configuration. This property is also required for any non-leaf local aggregate configurations, if the application supports them. Most global or aggregate configurations will have multiple contributions, and thus define multiple contribution properties. The value of each contribution property is the URI of an in-line oslc_config:Contribution resource (but the rdf:type triple is optional). Each Contribution resource defines the oslc_config:configuration property to indicate the associated configuration and optionally defines the oslc_config:contributionOrder property to indicate the relative order of this associated configuration in the hierarchy.

Note: at this time, third-party data providers are unlikely to need this property, since the GCM application allows only leaf (non-aggregate) contributions from other applications, and the CLM/CE applications do not support other global configuration management providers.

oslc_config:selections

Local application configurations, both streams and baselines, must define this property where the value is a published resource of type oslc_config:Selections. This Selections resource contains triples indicating the specific versions of resources that are included in the configuration. In the Selections resource, each oslc_config:selects reference corresponds to a versioned resource graph URI. See Data Instance Resources for more details. Global Configurations and non-leaf local aggregate configurations do not include the oslc_config:selections property; their selections are determined from the local configuration contributions. Typically, any given configuration will define either an oslc_config:selections property or a set of oslc_config:contribution properties, but not both.

Publishing OSLC components

If your application defines OSLC components, your TRS feed must include the following required properties for each component:

<componentURI> 
   rdf:type oslc_config:Component ;
   dcterms:title "Component Name" ;  
   acc:accessContext <accessContextURI> ;
   oslc:serviceProvider <serviceProviderURI> ;
   process:projectArea <projectAreaURI> .       (required if you have project areas)

rdf:type oslc_config:Component

All components must define this type.

dcterms:title

A user-readable name for the component.

acc:accessContext

The component resource graph must define the acc:accessContext property to restrict user access based on project membership. See OSLC Access Context Resources for more information.

oslc:serviceProvider

Components must define at least one instance of this property with the URI of the configuration OSLC Service Provider. This configuration service provider is probably different than a project area service provider (whose oslc:details property is the URI of the Project Area resource).

process:projectArea

Like instance resources, all components must define this property to indicate the project area in which the component resides. RB uses this property when displaying the configuration filter to determine the project and configuration hierarchy, and to filter the list of configurations based on projects selected in the Limit scope section of a report. If your application does not define project areas, see the earlier section on that topic in this article.

Publishing OSLC resource shapes

Resource shapes are the main construct for defining tool-specific metadata for LQE and RB. A resource shape defines a type of resource supported by the application and defines all the OSLC properties that such a resource might have. Instance resources of that type then refer to the resource shape and provide values for some or all of the properties defined in the shape.

Typically, your application will publish shapes per project. If your application supports configurations, you can also define them per configuration (which means they are versioned shapes).

For each resource type it supports, your application must publish a resource shape (per project or per configuration) that specifies all possible properties for that type in the application. Every instance resource of that type must include an oslc:instanceShape property that refers to that same resource shape.

Note: Some applications define shapes that might or might not be used by a project; publish only the shapes that are referenced by projects.

For non-versioned resource shapes, the graph URI and the main resource shape URI in that graph should be identical. If your application has versioned shapes, the graph URI will differ from the concept URI for the resource shape; instance resource shapes must reference the concept URI, and the configuration selection mechanism will associate the correct version.

If the resource shape graph is specific to a project, the graph must define the access context as described in OSLC Access Context resources:

<resourceShapeGraphURI> acc:accessContext <accessContextURI>

The resource shape itself must define the following basic properties, described below:

<resourceShapeURI>
   rdf:type oslc:ResourceShape ;                  (required)
   dcterms:title “Resource Shape Name” ;          (required)
   process:projectArea <projectAreaURI> ;         (required if you have project areas)
   dcterms:description “type description” ;       (optional)
   oslc:describes <anRdfTypeURI> ;                (zero or more)
   jrs:superShape <aResourceShapeURI> ;           (zero or more)
   oslc:property <#anonymousPropertyURI> ;        (one or more)
   oslc:serviceProvider <serviceProviderURI> ;    (required)
   oslc:hidden true .                             (optional)

rdf:type oslc:ResourceShape

Required type definition.

dcterms:title

A user-readable name for the component.

process:projectArea

The project area in which the component resides. If your application does not define project areas, see the earlier section in this article.

dcterms:description

Optional user-readable description of the resource shape.

oslc:describes

The RDF type that the shape extends. If the RDF type appears in the Choose an Artifact section of the report editor, the resource shape will appear beneath that RDF type in the hierarchy (unless the shape is hidden). If a resource shape describes more than one displayed RDF type, the resource shape will appear under each of those RDF types. For example, most DNG resource shapes describe both oslc_rm:Requirement and oslc_rm:RequirementCollection types, and therefore appear twice in the Choose an Artifact section.

oslc:property

The value is an anonymous resource of type oslc:Property. Most resource shapes define multiple oslc:property triples.

jrs:superShape

The OSLC Resource Shape 2.0 specification does not provide a way for resource shapes to extend other shapes (you can’t define an oslc:describes property where the value is another resource shape). However, with a complicated set of resource shapes, such as those representing the UML types, a hierarchy of resource shapes exists. Use the jrs:superShape attribute to refer to one or more higher-level resource shapes that this shape extends. In the Choose an Artifact section of the report editor, the types show a hierarchy with the resource shape appearing beneath any super shapes it references. For example, if resource shape XYZ defines resource shape ABC as a super shape, shape XYZ shows beneath shape ABC in the Choose an Artifact section.

oslc:serviceProvider

The URI of the corresponding project Service Provider resource for the resource shape (<serviceProviderURI>) that is published by the Process TRS 2.0 feed.

oslc:hidden

If a resource shape is not a primary type for reporting, set the value to true so RB does not display that shape type in the Choose an Artifact section. Users can still include hidden types in a report by adding a traceability relationship from another resource shape type, if such a relationship exists.

Publishing resource shape properties

LQE and RB expect every oslc:Property resource to include the properties listed below, in addition to any other properties they might include based on the OSLC Resource Shape 2.0 specification:

<#property>
   rdf:type oslc:Property ;                      (required)
   dcterms:title “Property Name” ;               (required)
   dcterms:description “description” ;           (optional)
   oslc:propertyDefinition <predicateURI> ;      (required)
   oslc:hidden true ;                            (optional)
   oslc:name “internal property name” ;          (optional)
   oslc:valueType <anXsdOrOslcTypeURI> ;         (see property topics that follow)
   oslc:allowedValue <enumerationValueURI> ;     (see property topics that follow)
   oslc:allowedValues <allowedValueResource> ;   (see property topics that follow)
   oslc:range <anRdfTypeURI> ;                   (see property topics that follow) 
   oslc:valueShape <aResourceShapeURI> ;         (see property topics that follow)
   jrs:inContainer true ;                        (extension to OSLC; see Using container resources)
   jrs:inversePropertyLabel “inverselabel” ;     (extension to OSLC; see Reversible Relationships )
   jrs:inversePropertyDefinition <propertyURI> . (extension to OSLC; see Reversible Relationships )

rdf:type oslc:Property

Required type definition.

dcterms:title

A user-readable name for the property.

dcterms:description

Optional user-readable description of the property.

oslc:propertyDefinition

The <predicateURI> stores the value for the property in the instance resources. If the property can define multiple values, there could be multiple oslc:propertyDefinition triples. In many cases, the predicate is a stable URI, meaning the URI can be used in resources in different projects and on different servers. Such predicates usually correspond to standard vocabularies such as Dublin Core or those defined by OSLC specifications. In any case, your application should publish a “vocabulary” resource of type rdf:Property for the predicate (where the subject is the <predicateURI>), defining its name and range. This vocabulary resource can be part of a static vocabulary, or more typically for an external data source, published by a TRS feed.

oslc:hidden

Optionally, set the value to true to indicate this property should be excluded from reporting.

oslc:name

Optionally, the local name of the defined property; this is typically the portion of the defined oslc:propertyDefinition <predicateURI> that follows the last hash (#) or slash (/).

The remaining properties are described in the sections that follow.

Many applications support custom properties or custom enumeration values, generating property predicate URIs that are project-specific and can complicate cross-project reporting. Where possible, allow the user to specify an external URI for these custom properties, which they can reuse for equivalent properties in other projects. See Specifying external URIs for predicates and enumerations for more details on how to publish custom properties with external URIs to facilitate cross-project reporting.

An OSLC property definition can define different kinds of properties:

Attribute properties have a target type that is a data type (string, integer, boolean, etc.) or the foaf:Person type.
Enumeration properties are a special kind of attribute property where there is a specific list of possible values.
Relationship properties have a target type that is another resource type.

Details on specifying these different property types are described in the sections below. If your application supports multiple languages, also refer to the section Enabling localization.

Defining attribute properties

An attribute property stores data about a resource; the type of data is typically an XSD type such as string, integer, date, or a property that refers to a person (foaf:Person). Although a foaf:Person value is effectively a link to another resource, RB treats it as an attribute.

Use the oslc:valueType property to define the type for the attribute’s value. Attribute property definitions must not specify any oslc:allowedValue, oslc:allowedValues, oslc:valueShape or oslc:range properties.

If a property value is a URI, RB treats it as a relationship property (with the exception of foaf:Person properties and enumerations, described below). In some cases, the property value might be a URI for a resource not published in LQE, such as a data file. To treat that property as an attribute, specify oslc:valueType as xsd:anyURI; the report results display that URI value as a hyperlink, but without any hover help.

Many applications support custom properties, generating a property predicate URI that is project-specific and complicates cross-project reporting. Where possible, allow the user to specify an external URI for these custom properties, which they can reuse for equivalent properties in other projects. See Specifying external URIs for predicates and enumerations for more details on how to publish custom properties with external URIs to facilitate cross-project reporting.

If your application allows tags for an artifact, use the dcterms:subject property, which takes a string value. See Specifying tag values.

Defining enumeration properties

An enumeration property always specifies a list of possible values in the property definition. Usually, the resource shape definition for the enumeration specifies an oslc:allowedValue property for each enumeration value resource URI. Alternatively, the resource shape can define a single oslc:allowedValues property that refers to an anonymous resource of type oslc:AllowedValues, which defines the oslc:allowedValue properties for all the enumeration values. That oslc:AllowedValues resource must be in the same RDF graph as the resource shape that owns the property that references it. If it is in a different RDF graph, the user might not see the enumeration values of that property in Report Builder’s type system model.

In general, all enumeration values for a given property should be resources with the same RDF type. Use the oslc:range property to define the corresponding RDF type of the enumeration value resources.

Typically, define all the possible values for the enumeration in a single graph, where the main resource corresponds to the enumeration RDF type:

<enumTypeURI> rdf:type rdfs:Class

The graph must also define the acc:accessContext URI, as described in OSLC AccessContext Resources.

The remaining resources correspond to the individual enumeration values of the same RDF type:

<enumValueURI> rdf:type <enumTypeURI>

For each enumeration value resource, specify a name using the rdfs:label attribute. If the enumeration value is associated with an external URI to facilitate cross-project reporting, specify that URI with the owl:sameAs attribute. The section Specifying external URIs for predicates and enumerations provides more details including a brief example for enumeration types and values.

Instead of defining the values individually, you can define a hierarchy of enumeration values using the skos:broader property. In an enumeration hierarchy, RB considers a parent enumeration value to be more generic (broader) than a child enumeration value. A child enumeration resource would specify the triple:

<childEnumURI> skos:broader <parentEnumURI>

The following example shows how you might define an enumeration hierarchy, using stable URIs to define the enumeration type and its possible values.

Example of enumeration attribute hierarchy

This example illustrates an enumeration value hierarchy for a fictional “Buy or Sell” site. The site categorizes items in a hierarchy, for example:

Buy or Sell
   Books
   Home
       Appliance
Refrigerator

Stove

Bedroom

Bed

Dresser

The graph to define the vocabulary for this enumeration might have the URI http://buysell.com/AdCategory, and might contain the following triples:

<http://buysell.com/AdCategory/> rdf:type rdfs:Class ;
    rdfs:label “Ad Categories”;
    acc:accessContext <accessContextURI>.
<http://buysell.com/AdCategory/BuySell> rdf:type <http://buysell.com/AdCategory/>;
    rdfs:label “Buy or Sell”.
<http://buysell.com/AdCategory/Books> rdf:type <http://buysell.com/AdCategory/>;
    rdfs:label “Books”;
    skos:broader <http://buysell.com/AdCategory/BuySell>.
<http://buysell.com/AdCategory/Home> rdf:type <http://buysell.com/AdCategory/>;
    rdfs:label “Home”;
    skos:broader <http://buysell.com/AdCategory/BuySell>.
<http://buysell.com/AdCategory/Appliance> rdf:type <http://buysell.com/AdCategory/ ;
    rdfs:label “Appliance”.
    skos:broader <http://buysell.com/AdCategory/Home>.
<http://buysell.com/AdCategory/Fridge> rdf:type <http://buysell.com/AdCategory/>;
    rdfs:label “Refrigerator”;
    skos:broader <http://buysell.com/AdCategory/Appliance>.
<http://buysell.com/AdCategory/Stove> rdf:type <http://buysell.com/AdCategory/>;
    rdfs:label “Stove”;
    skos:broader <http://buysell.com/AdCategory/Appliance>.
<http://buysell.com/AdCategory/Bedroom> rdf:type <http://buysell.com/AdCategory/>;
    rdfs:label “Bedroom”;
    skos:broader <http://buysell.com/AdCategory/Home>.
<http://buysell.com/AdCategory/Bed> rdf:type <http://buysell.com/AdCategory/>;
    rdfs:label “Bed”;
    skos:broader <http://buysell.com/AdCategory/Bedroom>.
<http://buysell.com/AdCategory/Dresser> rdf:type <http://buysell.com/AdCategory/>;
    rdfs:label “Dresser”;
    skos:broader <http://buysell.com/AdCategory/Bedroom>.

The enumeration property in the resource shape would define oslc:allowedValue entries for each of the enumeration values: <http://buysell.com/AdCategory/BuySell>, <http://buysell.com/AdCategory/Books>, and so on. The enumeration property would also define oslc:range as the type <http://buysell.com/AdCategory/>.

This example uses stable URIs to define the enumeration type and its possible values. Many applications use custom enumeration URIs that are specific to a project and server. Ideally, the application enables the user to specify external URIs for custom enumeration types and values, which can then be reused across projects and servers, and facilitate cross-project reporting. See Specifying external URIs for predicates and enumerations for more details.

Using container resources to store property values

When a resource has a property with multiple values, your application can publish multiple triple statements for that property with the same predicate, but different objects representing the values. Alternatively, you can publish a single property triple where the object is an anonymous container resource (an RDF bag or sequence) that contains all the triple statements for the property’s values.

If you use a container resource for the values, when you define the property, set the jrs:inContainer attribute to true to ensure RB can correctly associate the container resource to query and obtain the values.

For example, suppose you publish a definition for an appliedStereotypes property, with jrs:inContainer set to true. For a resource with that property, your published RDF might be:

<theArtifactResource> myvocab:appliedStereotypes <#appliedStereotypeContainer> .
<#appliedStereotypeContainer> rdf:type rdf:Seq .
<#appliedStereotypeContainer> rdf:_1 <stereotypeUri_a> .
<#appliedStereotypeContainer> rdf:_2 <stereotypeUri_c> .
<#appliedStereotypeContainer> rdf:_3 <stereotypeUri_b> .

When RB generates the report query, it ignores the rdf:type triple and the actual value predicates (rdf:_1, rdf:_2 and rdf:_3). The query also ignores any rdf:type predicates in the container that do not refer to the correct object type. The result would be the same as specifying:

<theArtifactResource> myvocab:appliedStereotypes <stereotypeUri_a> .
<theArtifactResource> myvocab:appliedStereotypes <stereotypeUri_c> .
<theArtifactResource> myvocab:appliedStereotypes <stereotypeUri_b> .

Defining relationship properties

A relationship property stores a reference (or link) to another resource, where the metadata describing the properties of that target resource are also published. Set oslc:valueType to indicate the value is a resource and how the target resource is identified, as defined by the Resource Shape 2.0 specification:

oslc:Resource must be identified with a URI
oslc:LocalResource must be identified with a blank node
oslc:AnyResource must be identified with either a URI or a blank node.

Relationship property definitions must not specify any oslc:allowedValue or oslc:allowedValues properties.

Typically, the target resource in a relationship has a specific RDF type, such as oslc_rm:Requirement. Use oslc:range to specify the target RDF resource type. If the target could be one of multiple distinct RDF types, specify multiple oslc:range properties. If the target shape does not describe an RDF type, omit the oslc:range property.

If the target type is a resource shape, define oslc:valueShape with the URI of that resource shape.

If a relationship property defines one or more target types, when the user selects that relationship in the RB Traceability section, the user can then choose the appropriate target type from a list of all specified target types and their derived types.

If the possible target resources of a relationship do not have any published metadata (are an unknown RDF type or resource shape), then do not specify either oslc:range or oslc:valueShape. Instead, define oslc:valueType as oslc:Resource, which corresponds to a generic OSLC resource that optionally has a dcterms:title property. In the RB Traceability section, this target resource type displays as “Some Resource”. In the report results, the title and URI for the generic resource are combined as a hyperlink, but without any hover help.

In many cases, especially with versioned artifacts, relationships are directional; only one of the related artifacts asserts or stores the relationship property. However, users might want to report on that relationship from either artifact. The following section on reversible relationships describes how to define your metadata so that RB can construct a reversible relationship to enable reporting in either direction.

Establishing reversible relationships

With linked data resources, a report author might want to trace a relationship between two types of resources in either direction, for example, from change request to test artifact or vice versa, regardless of which resource asserts or stores the relationship. With the right metadata, RB can build these “reversible relationships” into its metamodel to enable bidirectional traceability.

There are two possible scenarios that require reversible relationships:

Only one type asserts the relationship in its metadata.
One type has metadata that defines a relationship to another; the target type does not include any metadata about that relationship. For example, a test plan has a qm:usesTestCase property, but the test case metadata has no inverse relationship property to the test plan.
Both types define the relationship in their metadata; either type can assert the relationship.
The metadata for each type defines a relationship to the other, typically using different predicates. Resources of either type can assert the relationship, meaning either type can be the source or the target. For example, a change request can assert the oslc_cm:testedByTestCase relationship to a test case, or the test case can assert the oslc_qm:testsChangeRequest relationship to the change request.

Unless the resource uses back-link synchronization (which is not used for projects with versioned artifacts), the relationship would not be asserted on both sides.

The sections below provide more details on the metadata required, and examples for both scenarios.

Note: This is not necessarily related to which instance resources store or publish the relationship. Although versioned artifacts use directional linking (only the source resource publishes the relationship triple), the second scenario still applies in many cases, and for all OSLC-defined link pairs like the change request and test case example above. In the actual versioned instance resources, only the change request resources will publish the triple for this relationship. However, the metadata for both types still define properties for that relationship, in accordance with the OSLC specification, and to support non-configuration-management use cases where either type could express the relationship. RB still requires the additional reversible relationship metadata to establish the bidirectional traceability for reporting, as described in the sections that follow. The first scenario applies only where no relationship metadata exists for the target type.

Defining metadata for reversible relationships

For RB to establish a reversible relationship, applications must publish metadata that defines the relationship property for the type, including its target type, as well as the logical “inverse relationship” from the target back to the source. RB requires metadata for both the vocabulary property definition and the resource shapes for both involved types, regardless of whether the target type actually generates triple statements for the relationship.

This metadata is specific to reporting, and includes the OSLC property olsc:inverseLabel and extensions defined in the JRS namespace (http://jazz.net/ns/jrs#): jrs:inversePropertyLabel and jrs:inversePropertyDefinition. These properties do not apply to any other attribute type, or to relationships that are not reversible (for example, that target a foaf:Person value).

For each type that asserts a relationship to reverse:

Ensure the relationship property definition defines the correct target type.
Use oslc:range or oslc:valueShape to define the target RDF shape or resource shape (see Specifying relationship properties for more details).
Specify the label for the inverse relationship – how the target type would express the relationship.
RB requires this label to identify a reversible relationship. You can specify the label in one of two ways:
1. In the vocabulary property definition, add the oslc:inverseLabel property
2. If you can’t modify the vocabulary (for example, because it’s a static public vocabulary), add the jrs:inversePropertyLabel attribute to the appropriate resource shape property definitions.
For both attributes, the value is the label for the inverse relationship property on the target type. You can specify multiple labels to support different languages; see Enabling localization for more details.
If the target type can also assert the relationship, add the jrs:inversePropertyDefinition attribute to the resource shape relationship property.
This applies only to pairs of resource link properties such as those defined in the OSLC 2.0 specification. The value of this attribute is the predicate URI of the corresponding inverse property on the target type. The inverse property definition must exist in the target type’s metadata for RB to construct the reversible relationship.
A relationship can have more than one inverse predicate URI; for example, the oslc_qm:relatedChangeRequest relationship can have inverse properties of oslc_cm:relatedTestCase, oslc_cm:relatedTestExecution, or oslc_cm:relatedTestPlan, depending on the test resource asserting the relationship. Define inverse labels to address each property.

The following sections describe how RB processes this metadata to construct the relationships, and provides examples of metadata for reversible relationships.

How RB processes reversible relationship metadata

When generating the reporting metamodel, when RB finds the oslc:inverseLabel or jrs:inversePropertyLabel attribute for a type, it identifies a potential reversible relationship. It uses the oslc:range and oslc:valueShape attributes to determine the target types for the relationship.

If the relationship property does not specify jrs:inversePropertyDefinition, RB expects the relationship to be asserted only by the type defining the relationship properties. In the target type, RB constructs an inverse relationship property using the label specified in oslc:inverseLabel or jrs:inversePropertyLabel. (If both are specified, jrs:inversePropertyLabel takes precedence.) If the target type metadata already has an inverse property definition, RB uses that property and ignores oslc:inverseLabel and jrs:inversePropertyLabel values.

If the relationship property does specify jrs:inversePropertyDefinition, RB expects the relationship could be asserted by either the defining type or the target type. RB queries the target type for an inverse relationship property corresponding to the attribute value. If the relationship defines multiple jrs:inversePropertyDefinition values, RB also validates that the target type’s inverse relationship specifies the correct original type (for example, if TypeA specifies the target as TypeB, TypeB’s inverse relationship specifies the target as TypeA). If RB does not find the specified inverse property on the target, or if the types don’t match, it will not create the reversible relationship. When creating the relationship, RB uses the label from the jrs:inversePropertyDefinition on the target type, and ignores the oslc:inverseLabel and jrs:inversePropertyLabel values defined by the original relationship property.

In the report editor, reversible relationships are transparent: users can select either artifact type as a starting point, and trace the relationship in either direction. The generated queries differ depending whether one or both resources can assert the relationship. If only one type can assert it, regardless of which type the user selects as a starting point, RB queries only the asserting type for the relationship.

If either type can assert the relationship, RB queries the relationship on both types and does a union of the two queries.

Examples of reversible relationship metadata

The following examples illustrate metadata for defining reversible relationships for scenarios where only one type asserts the relationship, or where either or both types define the relationship, showing the additions to both the vocabulary definitions and resource shapes.

Example 1: Only one type defines the relationship

This example uses the oslc_qm:usesTestCase relationship from a test plan to a test case, a relationship that is only defined and asserted by the test plan resource.

Note: In the example, some of the vocabulary definitions include attributes to illustrate how you might define property ownership (rdfs:domain) and the target type of a property (rdfs:range). In the published vocabularies, these attributes might not be defined. Always reference resource shape properties by its owner resource shape (using oslc:property) and define the target type using oslc:range or oslc:valueShape.

The vocabulary definition might specify:

oslc_qm:usesTestCase
   a rdf:Property ;
   rdfs:label “Uses Test Case” ;
   rdfs:domain oslc_qm:TestPlan ;
   rdfs:range oslc_qm:TestCase ;
   oslc:inverseLabel “Used by Test Plan” .

A resource shape that describes oslc_qm:TestPlan (for example, QM Test Plan) might specify:

<#propUsesTestCase>
   a oslc:Property ;
   dcterms:title “Uses Test Case” ;
   oslc:range oslc_qm:TestCase ;
   oslc:propertyDefinition oslc_qm:usesTestCase .

Because the Test Plan resource shape does not define jrs:inversePropertyDefinition, RB assumes that the link is directional and only ever asserted by the Test Plan type, and that the Test Case type does not define an inverse property.

To establish the reversible relationship, RB creates a meta-property for the Test Case type with a relationship target to Test Plan and the label defined by the inverseLabel in the vocabulary (“Used by Test Plan”). To report on the traceability between Test Plan and Test Case, the user can choose either resource as the starting point. Regardless of which resource is chosen to start with, the generated query always uses the Test Plan as the subject resource for the triple, for example:

?testPlan oslc_qm:usesTestCase ?testCase.

Example 2: Either or both types can define the relationship

This example illustrates the scenario where either type can assert the relationship to the other. It shows what you would add to the vocabulary definitions and resource shapes so RB can establish the reversible relationships.

The relationships shown are between oslc_qm:relatedChangeRequest (used by multiple test types) and oslc_cm:relatedTestCase, oslc_cm:relatedTestPlan, and oslc_cm:relatedTestExecutionRecord. These relationships are all defined by the OSLC specification.

The vocabulary might specify:

oslc_cm:relatedTestCase
   a rdf:Property ;
   rdfs:label “Related Test Case”;
   rdfs:domain oslc_cm:ChangeRequest ;
   rdfs:range oslc_qm:TestCase ;
   oslc:inverseLabel “Related Change Request” .

oslc_cm:relatedTestExecutionRecord
   a rdf:Property ;
   rdfs:label “Related Test Execution Record”;
   rdfs:domain oslc_cm:ChangeRequest ;
   rdfs:range oslc_qm:TestExecutionRecord ;
   oslc:inverseLabel “Related Change Request” .

oslc_cm:relatedTestPlan
   a rdf:Property ;
   rdfs:label “Related Test Plan”;
   rdfs:domain oslc_cm:ChangeRequest ;
   rdfs:range oslc_qm:TestPlan ;
   oslc:inverseLabel “Related Change Request” .

oslc_qm:relatedChangeRequest       (this property is used in multiple resource shapes - see examples that follow)
   a rdf:Property ;
   rdfs:label “Related Change Request”;
   rdfs:range oslc_cm:ChangeRequest ;
   oslc:inverseLabel “Related Test Artifact” . (this generic label will not be used – see explanation below)

A resource shape that describes the oslc_cm:ChangeRequest type (for example, Work Item) might specify:

<#propRelatedTestCase>
   a oslc:Property ;
   dcterms:title “Related Test Case”;
   oslc:range oslc_qm:TestCase ;
   oslc:propertyDefinition oslc_cm:relatedTestCase ;
   jrs:inversePropertyDefinition oslc_qm:relatedChangeRequest .

<#propRelatedTestExecutionRecord>
   a oslc:Property ;
   dcterms:title “Related Test Execution Record”;
   oslc:range oslc_qm:TestExecutionRecord ;
   oslc:propertyDefinition oslc_cm:relatedTestExecutionRecord ;
   jrs:inversePropertyDefinition oslc_qm:relatedChangeRequest .

<#propRelatedTestPlan>
   a oslc:Property ;
   dcterms:title “Related Test Plan”;
   oslc:range oslc_qm:TestPlan ;
   oslc:propertyDefinition oslc_cm:relatedTestPlan ;
   jrs:inversePropertyDefinition oslc_qm:relatedChangeRequest .

A resource shape that describes oslc_qm:TestCase (for example, QM Test Case) might specify:

<#propRelatedChangeRequest>
   a oslc:Property ;
   dcterms:title “Related Change Request”;
   oslc:range oslc_cm:ChangeRequest ;
   oslc:propertyDefinition oslc_qm:relatedChangeRequest ;
   jrs:inversePropertyDefinition oslc_cm:relatedTestCase .

A resource shape that describes oslc_qm:TestExecutionRecord (for example, QM Test Execution Record) might specify:

<#propRelatedChangeRequest>
   a oslc:Property ;
   dcterms:title “Related Change Request”;
   oslc:range oslc_cm:ChangeRequest ;
   oslc:propertyDefinition oslc_qm:relatedChangeRequest ;
   jrs:inversePropertyDefinition oslc_cm:relatedTestExecutionRecord .

A resource shape that describes oslc_qm:TestPlan (for example, QM Test Plan) might specify:

<#propRelatedChangeRequest>
   a oslc:Property ;
   dcterms:title “Related Change Request”;
   oslc:range oslc_cm:ChangeRequest ;
   oslc:propertyDefinition oslc_qm:relatedChangeRequest ;
   jrs:inversePropertyDefinition oslc_cm:relatedTestPlan .

The vocabulary definition for oslc_qm:relatedChangeRequest does not specify the rdfs:domain attribute because the property is used by multiple QM resource shape types. The jrs:inverseLabel “Related Test Artifact” for oslc_qm:relatedChangeRequest is not used because each of the QM resource shape types defines its own jrs:inversePropertyDefinition attribute. Because of that attribute, RB expects the corresponding inverse property to exist for the oslc_cm:ChangeRequest, and uses that label instead. (If the QM shapes had also defined a jrs:inversePropertyLabel value, RB would have ignored it as well, for the same reason.)

The generated query to find the relationships between Work Items and Test Plans would look for the relationship to be defined on either resource, similar to:

{
?changeReq oslc_cm:relatedTestPlan ?testPlan.
} UNION {
? testPlan oslc_qm:relatedChangeRequest ?changeReq.
}

Specifying external URIs for predicates and enumerations

Many applications create project-specific URIs for enumeration value resources and sometimes project-specific predicate URIs for custom properties. For example, two project areas might define the same custom property of “Importance”, but each has a URI specific to the project it’s in. From a metadata perspective, those properties are unique because their URIs are unique. To report on Importance across both projects, the user would need to set a filter for each one, which can greatly complicate cross-project reporting.

To facilitate cross-project reporting, allow your application users to define an external URI for custom or generated project-specific property predicates and enumeration values. Users must reuse the same external URI for equivalent properties or enumeration values in all their projects. This is a best practice to encourage. If your application provides templates that generate project-specific URIs for properties and enumerations on instantiation, consider adding predefined external URIs for those properties and enumerations.

For properties or enumerations with an external URI, your application’s TRS feed must publish an owl:sameAs property with the value of the external URI, as described in the following sections – essentially defining equivalence statements. RB can then use the external URI to query all the predicates or values that reference that URI across all the projects.

Note: The owl:sameAs statement must be in the form <internalUri> owl:sameAs <externalUri> and not in the form <externalUri> owl:sameAs <internalUri>.

Publishing external URIs for property predicates

When a user or application creates a custom property, the application often generates a project-specific predicate URI for the property, which is published in the vocabulary. The resource shapes referencing the custom property define that predicate URI using oslc:propertyDefinition, and instance resources use the predicate to store the property value. When the user specifies an external URI for that property predicate, your application must republish the vocabulary for that property to include the owl:sameAs property. (Note: these changes require a refresh of the data source metamodel before users can see them in RB.)

For example, suppose a custom property “Status” has a generated predicate http://myhost.com/app/attr/_GUID. The initial vocabulary definition for that property predicate might look like:

<http://myhost.com/app/attr/_GUID> rdf:type rdf:Property ; 
   rdfs:label “Status” .

If the user specified the external URI http://jazz.net/ns/app/status for the “Status” property predicate, the application would publish (or republish) the vocabulary for the “Status” property as follows:

<http://myhost.com/app/attr/_GUID> rdf:type rdf:Property ;
   rdfs:label “Status” ;
   owl:sameAs http://jazz.net/ns/app/status .

Other project shapes using the same custom property and external URI would include the same owl:sameAs value. When RB generates the reporting metamodel, it uses the owl:sameAs values to merge equivalent properties to make it easier to report across components and projects. The application does not need to republish the resource shapes or resources that define or reference the property; new and modified resources should continue to use the project-specific URI.

Publishing external URIs for enumeration values

Like custom properties, specifying external URIs for enumeration values that are common or equivalent across projects can simplify cross-project reporting. When a user or application specifies an external URI for an enumeration value, your TRS feed must modify the enumeration value resource to include an owl:sameAs triple with the external URI as its value. Your application must republish the graph that contains the enumeration value resource.

(Note: these changes require a refresh of the data source metamodel before users can see them in RB.)

Using the earlier Example of enumeration attributes, consider the “Dresser” resource with its default URI of http://buysell.com/AdCategory/Dresser. Suppose a user added an external URI http://jazz.net/ns/adCategory/dresser, with the intent of adding equivalent resources like “Bureau” and “Wardrobe” that would use the same external URI.

The application would publish an updated enumeration resource like the following:

<http://buysell.com/AdCategory/Dresser> rdf:type http://buysell.com/AdCategory/ ;
   rdfs:label “Dresser” ;
   skos:broader http://buysell.com/AdCategory/Bedroom ;
   owl:sameAs http://jazz.net/ns/adCategory/dresser .


<http://buysell.com/AdCategory/Bureau> rdf:type http://buysell.com/AdCategory/ ;
   rdfs:label “Bureau” ;
   skos:broader http://buysell.com/AdCategory/Bedroom ;
   owl:sameAs http://jazz.net/ns/adCategory/dresser .


<http://buysell.com/AdCategory/Wardrobe> rdf:type http://buysell.com/AdCategory/ ;
   rdfs:label “Wardrobe” ;
   skos:broader http://buysell.com/AdCategory/Bedroom ;
   owl:sameAs http://jazz.net/ns/adCategory/dresser .

The application does not need to modify or republish any resource shapes that refer to the enumeration value (with oslc:allowedValue) or any instance resources that have that enumeration property. New and modified resources continue to use the project-specific URIs for the enumeration value.

Enabling localization for different languages

Like the rest of the CLM/CE solution, Report Builder is available in multiple languages. RB also supports localization of data for reporting, based on the locale set in the user’s browser.

To support different languages for your application data, provide translations for the names of all types, properties, and enumeration value resources. Typically, the metadata for the name is defined by the dcterms:title or rdfs:label property. For each supported language, define the property triple with an xml:lang attribute set to the 2-character language identifier, and the string value in the corresponding language. You must also publish a default name triple that does not define any language; the default name is used if the user’s locale does not match any of the provided locale names.

The following example shows how you might specify translated names for a resource in RDF/XML:

<dcterms:title>Default resource name</dcterms:title>
<dcterms:title xml:lang=”en”>Resource name in English</dcterms:title>
<dcterms:title xml:lang=”fr”>Resource name in French</dcterms:title>
<dcterms:title xml:lang=”de”>Resource name in German</dcterms:title>

For a complete list of 2-character language identifiers, see http://www.loc.gov/standards/iso639-2/php/code_list.php.

Publishing data instance resources

The data instance resources are the actual artifacts or resources that your users report on. Publish every instance resource in one or more graphs. For unversioned resources, you typically publish a single graph, with a resource concept URI that is identical to the graph URI. For versioned resources, publish multiple graphs for the same concept resource, one for each version; the graph URI for the versioned resource will always differ from the concept resource URI it contains. See Publishing versioned resources below for more details.

Note: if your application supports versioning resources in some projects and not others, you must publish versioned resources for all projects, as described below.

All instance resource graphs must contain a triple defining the acc:accessContext property that controls access to all resources in the graph, as described in OSLC access context resources.

A concept resource must identify its associated type with the rdf:type property and corresponding RDF type URI. If the resource is constrained by a resource shape, define oslc:instanceShape with the concept URI of that resource shape. Concept resources must also define the process:projectArea triple, with the following exceptions:

Dynamic vocabularies like enumeration type graphs do not need the process:projectArea triple
If your application does not define project areas, do not include the process:projectArea triple for your instance resources. See If your project does not define project areas for more details.
If your application simulates project areas, but your resource shapes use the oslc:serviceProvider property instead of process:projectArea, do not include the process:projectArea triple for your instance resources. See If your project does not define project areas for more details.

Users must have access to both the instance resource and its resource shape to report on a resource, based on the project area permissions and access context settings.

Instance resources also include triples for all associated attributes or properties for reporting.

Specifying tag values

Many applications allow users to associate one or more tags with an artifact. To specify tags for a resource, use the dcterms:subject property, which takes a string value.

When a resource has multiple tag values, report users often want to see a single entry or row for that resource with all its tags listed in a single column, instead of a separate row for each defined tag. To cause this behavior, instead of using multiple dcterms:subject definitions for the tags, publish a single dcterms:subject triple where the value is a comma-separated list of all the defined tags for the resource. For readability, include a space after each comma, for example:

<resourceURI> dcterms:subject “Tag1, Tag2, Tag3” .

RB then generates a tags filter to examine the individual tags in the string, and provides conditional operators for the tags (such as contains, is, is not, and so on).

Publishing versioned resources

When a resource is versioned, the graph containing the concept resource for the artifact must also define the following triples:

<versionedResourceGraphURI> rdf:type oslc_config:VersionResource ;
   acc:accessContext <accessContextURI> ;
   dcterms:isVersionOf <resourceConceptURI> .

Local (non-aggregate) configurations define an oslc:Selections resource that refers to the graph URI of the versioned resource, as described in Required properties for OSLC configurations. When the versioned resource is modified, publish a new version (graph) of the resource, and update the corresponding oslc:Selections resource for the appropriate configuration.

If your application supports versioned and non-versioned resources

Some applications allow configuration management to be enabled per project, meaning some projects version resources and others do not. If this applies to your application, you must take additional steps to ensure correct scoping of artifacts in report results.

When a user builds a report using the “LQE scoped by a configuration data” source, the generated query includes all resources specified in the selections for the configuration or its contributions (further filtered by any projects selected in the Limit Scope section). That query scope also includes all unversioned resources, to include potentially relevant resources from “compatible” projects such as Rational Team Concert. (If the user limits scope to selected project areas, the query includes only resources from those project areas.)

If your application publishes both versioned and unversioned resources, the query described above could include the unversioned resources from your other project areas, yielding incorrect and unexpected results.

To prevent this scenario, publish versioned resources for all your project areas. For project areas that do not support configuration management, publish a single versioned resource for each artifact. When the artifact is modified, either publish the changed content to the existing versioned resource, or publish a new version and delete the existing one. You can optionally publish a single configuration for each non-enabled project.

Applications that do not support configurations in any way should always create unversioned resources and their service provider should set jfs_process:globalConfigurationAware to no (as described in OSLC service provider resources).

Diagrams of published resource relationships

The following diagrams illustrate how the various published resources reference each other. In the diagrams, < > represents a property value corresponding to a resource URI.

Unversioned resource relationships

This diagram illustrates relationships between resources that are not versioned, meaning configuration management is not enabled for requirement or test artifacts.

Versioned resource relationships

This diagram illustrates relationships for artifacts that are versioned, meaning configuration management is enabled for requirement and test artifacts.

Additional resources

The following sections provide additional reference information pertinent to this document and to implementing your integration. You might also want to consult:

A look inside LQE and Report Builder, which describes how LQE and RB surface the metadata to the reporting user
The IBM Knowledge Centre CLM/CE reporting topics for more details on LQE and Report Builder usage and administration
The Jazz.net library for other articles on reporting

OSLC specifications

The following OSLC specifications might be helpful in understanding various aspects of integrating with LQE and RB, including tracked resource sets, resource shapes, types and properties associated with different domains, and artifact versioning.

OSLC Core Specification (v2.0): http://open-services.net/bin/view/Main/OslcCoreSpecification
OSLC Change Management (2.0): http://open-services.net/bin/view/Main/CmSpecificationV2
OSLC Quality Management (2.0): http://open-services.net/bin/view/Main/QmSpecificationV2
OSLC Requirements Management (2.0): http://open-services.net/bin/view/Main/RmSpecificationV2
OSLC Resource Shape (2.0): https://www.w3.org/Submission/2014/SUBM-shapes-20140211/
OSLC Tracked Resource Set (2.0): http://open-services.net/wiki/core/TrackedResourceSet-2.0/
OSLC Configuration Management (2q2015 draft – corresponds to initial implementation in CLM /CE 6.0.x): https://tools.oasis-open.org/version-control/svn/oslc-ccm/branches/2q2015/specs/config-mgt.html
OSLC Configuration Management latest working draft (now part of OSLC Core 3.0 workgroup): https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/config/#_trunk_specs_config

In addition, the Eclipse Lyo project includes an OSLC Workshop and a Tracked Resource Set Provider workshop that might be helpful. For those looking toward what the future might hold, drafts of OSLC Core 3.0 specifications can be found at https://wiki.oasis-open.org/oslc-core/.

Common prefixes for metadata vocabularies

This article references published metadata vocabularies with the commonly-used prefixes listed below. Your vocabularies and TRS feeds will also need to reference the appropriate vocabularies.

acc             http://open-services.net/ns/core/acc#
clm_acc         http://jazz.net/ns/clm/acc#
dcterms         http://purl.org/dc/terms/
foaf            http://xmlns.com/foaf/0.1/
jfs_process     http://jazz.net/xmlns/prod/jazz/process/1.0/
jrs             http://jazz.net/ns/jrs#
merge           http://jazz.net/ns/lqe/merge/
oslc            http://open-services.net/ns/core#
oslc_am         http://open-services.net/ns/am#
oslc_cm         http://open-services.net/ns/cm#
oslc_config     http://open-services.net/ns/config#
oslc_qm         http://open-services.net/ns/qm#
oslc_rm         http://open-services.net/ns/rm#
owl             http://www.w3.org/2002/07/owl#
process         http://jazz.net/ns/process#
prov            http://www.w3.org/ns/prov#
rdf             http://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfs            http://www.w3.org/2000/01/rdf-schema#
skos            http://www.w3.org/2004/02/skos/core#
trs2            http://open-services.net/ns/core/trs#
xsd             http://www.w3.org/2001/XMLSchema#

About the authors

Kathryn Fryer is a Senior Solution Architect who works closely with clients, field, and development to develop usage models, aid adoption, and improve product offerings. Kathryn can be contacted at fryerk@ca.ibm.com.
Kevin Cornell is a Senior Software developer who played a significant role in the development of Report Builder and JRS before retiring in 2017.
David Honey is Technical Lead for Global Configuration Management. David can be contacted at david.honey@ibm.com.

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Feedback

Was this information helpful?

2 people rated this as helpful.