Creating and running queries

Sometimes you need to gather a specific set of artifacts. You might want to compile a set of failing tests to include in a status report. Queries can gather a set of artifacts and display the results for you to act on.

Before you begin

Queries are written in the SPARQL query language. (SPARQL is the query language for Linked Lifecycle Data.) Therefore, you must know the SPARQL query language to create queries from scratch.

About this task

The following steps show how to create and run three custom queries. Each query is annotated so that you can customize it for your use.

Procedure

  1. Open the Query dialog box.

    In the main menu, select Queries > Create Query.

  2. In the Query dialog box, enter a name for the query.
  3. Enter a description of the query.

    The description displays when you hover over a query in the My Queries or Shared Queries screens.

  4. Save this query in the My Queries folder.

    Whenever you create a query for your use or your team's use, create the query and save it to the private folder, My Queries. After you test and refine the query to gather the artifacts you need, you can share the query.

  5. Change the sample query code by either replacing or modifying it.
    • Replace the sample query code. Choose a query from the three examples in the Example section below. Copy the query and paste it into the field.
    • Alternatively, modify the default sample SPARQL query code with your custom code.

      Standard editing keys are available for your platform. When you edit the SPARQL query, you can type Control+space to receive content assistance.

      If you need a different prefix from those shown, click the Add Prefix button.

      If you want to set a parameter to create a query that prompts users for a value, you can add it now or later. Parameters identify a characteristic for a set of artifacts that you are searching for. For example, you can add a parameter to search for artifacts that were modified since a certain date or artifacts that were modified by a certain user.

      Adding prompting parameters to a query makes the query more flexible because users can specify parameter values when they run the query. Parameter values are substituted into the query string, and customize the query results.

      Parameter values typically use a form like $workitem$

      Although the full syntax of what you can add as a parameter can be complex, the typical forms include:

      $name$

      $name.field$

      $name;format="formatString"$

      $name.field;format="formatString"$

      StringTemplate is a template engine used to implement parameter substitution in the SPARQL query string. Rational® Engineering Lifecycle Manager does not support parameters with spaces even though StringTemplate does.

      View a simplified set of syntax rules for StringTemplate at StringTemplate cheat sheet. You must use $...$ as the delimiter, not <...>, which is specified in the cheat sheet.

      If you use one or more parameters in your query, read about a known issue in Troubleshooting parameterized queries.

      To view a table of date, enumeration, and system parameters, and sample output for each, see Predefined query parameters.

      Learn more about setting parameters in the Query dialog box by hovering over the small question mark to the right of the SPARQL Query and Parameters sections to read hover help.

  6. Create the query by clicking Create.
  7. Run the query by clicking Run.
  8. Act on the artifacts in the Query Result page. Click an artifact and then click the arrow to the right to show the menu.
    • Open Artifact starts the native tool that the artifact was created in and displays the artifact in the tool.
    • Show Properties displays the properties of the artifact in a results window.
    • Start Analysis loads the default impact analysis profile. Click Run to start the analysis.

    Download the query as a .csv spreadsheet by clicking the Download as Spreadsheet icon in the upper right.

Example

The following example shows how to query for all open engineering change requests assigned to Susan.

Open ECRs assigned to Susan

# Name: Open ECRs assigned to Susan
# Description: Show all open ECRs assigned to Susan

# Prefixes used in this query
PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX oslc_cm: <http://open-services.net/ns/cm#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

SELECT ?cr ?title ?contrib
WHERE
{
	# Find all ECRs - in this example, we find work items of type "Task"; change this to the type of work item you use
	?cr rdf:type oslc_cm:ChangeRequest ;
		dcterms:type "Task"^^xsd:string ;
		dcterms:title ?title ;
		dcterms:contributor ?contrib .

	# Change the name string to match the user name you want
	FILTER regex(str(?contrib),"susan")

	# Find open CRs (those with status that is none of closed, fixed, or verified)
	# You can adjust this to use any combination of the OSLC CM state predicates
	# oslc_cm:closed, oslc_cm:inprogress, oslc_cm:fixed, oslc_cm:approved, oslc_cm:reviewed, and oslc_cm:verified
	{
		?cr oslc_cm:closed "false"^^xsd:boolean ;
			oslc_cm:fixed "false"^^xsd:boolean .
	}
	# for example, the following alternative to the above clause would find CRs that are either in progress or not closed:
	# {
	#	{ ?cr oslc_cm:inprogress "true"^^xsd:boolean } UNION { ?cr oslc_cm:closed "false"^^xsd:boolean }
	# }
}

The following example shows how to query for test cases that fail and are assigned to me.

Failing tests

# Name: Failing tests
# Descriptions: Testcases that fail and are assigned to me

# Prefixes used in this query
PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX oslc_qm: <http://open-services.net/ns/qm#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

SELECT ?testcase ?title
WHERE
{
	# Find failing test results, and their owning testcase
	?testResult rdf:type oslc_qm:TestResult ;
		oslc_qm:status "com.ibm.rqm.execution.common.state.failed"^^xsd:string ;
		oslc_qm:reportsOnTestCase ?testcase .

	# Select just the testcases assigned to me
	# Change the name string to match the user name you want
	?testcase dcterms:contributor ?user.
	FILTER regex(str(?user), "tony")

	# Find the matching testcase titles
	?testcase dcterms:title ?title .
}

The following example shows how to query for artifacts impacted by a change to a change request.

Arfifacts impacted by change to CR

# Description: Find artifacts impacted by a change to a Change Request
# Follows links such as CR->tracks->REQ->[elaboratedBy->REQ | specifiedBy->REQ]->[verifiedBy->TC | elaboratedBy->ME]

# Prefixes used in this query
PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX oslc_cm: <http://open-services.net/ns/cm#>
PREFIX oslc_rm: <http://open-services.net/ns/rm#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

SELECT ?cr ?type ?title ?owner
WHERE
{
	?cr a oslc_cm:ChangeRequest ;
		dcterms:identifier ?id ;
		(oslc_cm:tracksRequirement|oslc_rm:trackedBy|oslc_rm:elaboratedBy|oslc_rm:specifiedBy|oslc_rm:validatedBy)* ?uri .
	?uri dcterms:title ?title
	OPTIONAL
	{
		?uri rdf:type/rdfs:label ?type ;
	}
	OPTIONAL
	{
		# This part of the query picks up user names from either JTS user URIs or from DOORS FOAF entries,
		# and avoids getting the DOORS user URI as well as that FOAF entry
		{
			?uri dcterms:contributor/foaf:name ?owner
		}
		UNION
		{
			?uri dcterms:contributor ?owner
			FILTER NOT EXISTS { ?owner foaf:name ?x }
		}
	}
}

# Either provide one or more work item ID numbers here,
# or remove or comment out the entire VALUES section to look at all work items
VALUES ?id
{
	"626"^^xsd:string
	"627"^^xsd:string
}

What to do next


Feedback