Managing queries

A Query is a mean to create a set of source artifacts, and potentially explore the relations between this source set and target artifacts that respect certain given properties / relations.

SECollab lets you create queries to analyze your current engineering data:

• To further explore relations between artifacts
• To enable reporting capabilities

We have 2 types of queries

• Simple query to get a set of artifacts, if any
• Join query to get a set of "source artifacts" mapped to "target artifacts", if any.

Creating queries

To create Queries, go to the Project Administration's "Queries" section:

• Click the "+ New query" button
• Set a title and a description
• Select the query type between Simple query or Join query
• Complete query details according to mandatory fields

Creating a Simple query

• Select the Source type to get an initial set with all compatible artifacts in the project
• Write an optional Source filter allowing to restrict this initial set with a specific condition. Filter can be a restriction on the existence of a link, or on the value of a property of the artifact itself, or any linked artifact. The query will return all the artifacts matching this filter.

Creating a Join query

• Choose the type of the source artifacts that this query should apply on
• Choose the type of the target artifacts that this query should try to map
• Write the source filter to limit to source artifacts of interest to your analysis
  e.g. you selected the source type "requirement", but are only interested in DOORS' and not in Word's
• Specify the join condition that maps source artifacts to target artifacts, by selecting among Free query and Typed query
  • Writing a Free query filter allows you to write a specific condition clause to compute from the filtered source related elements
    e.g. you filtered out DOORS requirements for source, and diagrams for target, and now want to see how those resources are traced through a custom collaborative link that you previously defined
  • Setting a Typed query filter allows you to specify an existing collaboration link to compute from the filtered source related target elements
    Note: Typed Query are mandatory to create Matrix Report because we need to select a unique collaboration link to display in the matrix
• Write the target filter to fetch only target artifacts that are of interest to your analysis
  e.g. you selected the target type "requirement", but are only interested in DOORS' and not in Word's

A SECollab query (depending on its type) can then be decomposed from one up to tree separate clauses: source filter, join condition and target filter.

Writing query filters (source & target)

When creating a query, you need to write a clause that fetches relevant resources. Such a query is meant to check if a resource has a given set of properties, or if one of its linked resources has a given set of properties. To access a property, you need to write the namespace prefix and the property name, such as `dcterms:title`. Backquotes are required to express properties. Double quotes (") are used to express strings, and <> are used to express URI.
E.g.:

• to check a title is exactly "hello": `dcterms:title` = "hello"
• to check a title is not "hello": `dcterms:title` != "hello"
• to check a title starts with "hello": `dcterms:title` =~ "hello*"
• to check a title contains "hello": `dcterms:title` =~ "*hello*"
• to check a doors custom property named ieobjecttype contains "REQ" : `doors:ieobjecttype` =~ "*REQ*"
• to check a doors custom property named iepuid is empty (literal value) : `doors:iepuid` != ""
• to check for a URI property, use <> instead of "", e.g. when testing if the design was published by the DOORS publisher: `clm:design`.`clm:tool` = <https://secollab.acme.com:8443/secollab/clm/services/tool/com.sodius.mdw.clm.client.tool.doors>
• to ensure an object value (property pointing a resource and not a literal) exists, use NULL as to confirm there is a description on your resource: `dcterms:description` != NULL
• you can use AND, OR and parenthesis to write your query: (`dcterms:title` =~ "*hello*" OR `dcterms:description` =~ "*hello*") AND `clm:design`.`clm:tool`.`dcterms:title` = "DOORS"

Writing a query filter is the same as writing a resource type's query. Please check Managing resource types for more details.

Writing join conditions

A join condition is typically written as a test that a relationship exists.

• to check a collaborative link exists: `clm_custom:myLink` != NULL
• to explore multiple links: `clm_custom:myLink`.`clm_custom:myOtherLink` != NULL
• you may use the OR operator in join queries
• you should not use the AND though, which is not supported

Custom Collaborative links and resource types are always prefixed with clm_custom.