Migrating queries

In IBM® Rational® Engineering Lifecycle Manager 4.0.3 and later, some data representations in the lifecycle index have changed. These changes might require updates to your SPARQL queries, including queries that are used in views. This topic describes the changes and explains how to write queries that work in all versions.

Changes to product representation

The data representation changed in version 4.0.3 to be more compatible with the evolving Linked Data Platform in the following ways:
  • The link between products and their views now uses the pd:view link from the product to the view, rather than a pd_ext:isViewOf link from the view to the product.
  • The title string for the product (pd:Item) and part (pd:Part) has changed to type rdf:XMLLiteral from a simple string literal.
  • The previous version of a product is now indicated by using the link prov:wasRevisionOf rather than dcterms:replaces

Update your queries to use both forms of the link, and to cast the title to a string before using it or searching on it. You can use a SPARQL property path to match several alternatives. Therefore, you can use a UNION of two alternatives, or a property path such as prov:wasRevisionOf|dcterms:replaces, to match both the 1.x and 4.0.3 and later representations.

In product definitions where the version information requires you to identify a specific graph, property paths such as pd:view|^pd:isViewOf do not work because the two alternatives are in different graphs. In this case, you must use a UNION.

If you are querying for a product with a title that includes quotation marks, ampersands, or less than symbols, those characters must be XML-encoded in the 4.0.3 and later XMLLiteral representation.

For example, the following query shows products whose title includes the characters "auto&boat", the previous version, and the immediate child products of each of those products:

PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX prov: <http://www.w3.org/ns/prov#>
PREFIX pd: <http://jazz.net/ns/pd#>
PREFIX pd_ext: <http://jazz.net/ns/pd/extensions#>

SELECT ?parentVersion ?predecessor ?childVersion
WHERE
{
   GRAPH ?parentVersion
   {
      ?parent a pd:Item ;
         dcterms:title ?title .
      OPTIONAL { ?parent prov:wasRevisionOf|dcterms:replaces ?predecessor }
   }
   FILTER regex(str(?title),".*auto(&|&)boat.*","","i")
   {
      { GRAPH ?parentVersion { ?parent pd:view ?view } }
      UNION
      { ?view pd:isViewOf ?parentVersion }
   }
   OPTIONAL { ?view dcterms:hasPart/pd_ext:binding ?childVersion }
}

Changed identifier for products

The dcterms:identifier for a product is now a long unique string. If possible, use a different known property of the product in your queries. Otherwise, update queries that use the dcterms:identifier to use the new identifier.

New dimension properties for product branches

Version 4.0.3 indexes data about the dimension properties for product branches. For example, you can augment the previous query to show the dimension (branch) information for the parent product:

PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX prov: <http://www.w3.org/ns/prov#>
PREFIX pd: <http://jazz.net/ns/pd#>
PREFIX pd_ext: <http://jazz.net/ns/pd/extensions#>

SELECT ?parentVersion ?dtitle ?dvalue ?predecessor ?childVersion
WHERE
{
   GRAPH ?parentVersion
   {
      ?parent a pd:Item ;
         dcterms:title ?title .
      OPTIONAL { ?parent prov:wasRevisionOf|dcterms:replaces ?predecessor }
      OPTIONAL { ?parent pd_ext:dimensions ?bn }
   }
   FILTER regex(str(?title),".*auto(&|&)boat.*","i")
   {
      { GRAPH ?parentVersion { ?parent pd:view ?view } }
      UNION
      { ?view pd:isViewOf ?parentVersion }
   }
   OPTIONAL { ?view dcterms:hasPart/pd_ext:binding ?childVersion }
   ?bn ?dimension ?dvalue .
   ?dimension dcterms:title ?dtitle .
}

Changes to user data

In all previous releases, the index represented a user's email address with incorrect URL encoding. For example, the email address URI mailto:susan@example.com was represented in the index as mailto:susan%40example.com. This defect was fixed in Jazz™ 4.0.3, but not in the DOORS® 9 release. As a result, queries must allow both forms of the email address:

PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
PREFIX oslc_cm: <http://open-services.net/ns/cm#>

SELECT ?cr ?title ?contribMbox
WHERE {
  ?cr a oslc_cm:ChangeRequest ;
    dcterms:type "Task"^^xsd:string ;
    dcterms:title ?title ;
    dcterms:contributor/foaf:mbox ?contribMbox .
  FILTER regex(str(?contribMbox),"susan(@|%40)example.com")
}

Feedback