Advanced Usage

This document covers some of rtcclient more advanced features.

Query Syntax [2]

The following section describes the basic query syntax.

Comparison Operators

  • = : test for equality of a term,

  • != : test for inequality of a term,

  • < : test less-than,

  • > : test greater-than,

  • <= : test less-than or equal,

  • >= : test greater-than or equal,

  • in : test for equality of any of the terms.

Boolean Operators

  • and : conjunction

Query Modifiers

  • /sort : set the sort order for returned items

BNF

query      ::= (term (boolean_op term)*)+ modifiers
term       ::= (identifier operator)? value+ | (identifier "in")? in_val
operator   ::= "=" | "!=" | "<" | ">" | "<=" | ">="
boolean_op ::= "and"
modifiers  ::= sort?
sort       ::= "/sort" "=" identifier
identifier ::= word (":" word)?
in_val     ::= "[" value ("," value)* "]"
value      ::= (integer | string)
word       ::= /any sequence of letters and numbers, starting with a letter/
string     ::= '"' + /any sequence of characters/ + '"'
integer    ::= /any sequence of integers/

Notes

  1. a word consists of any character with the Unicode class Alpha (alpha-numeric) as well as the characters “.”, “-” and “_”.

  2. a string may include the quote character if preceded by the escape character “", as in “my "quoted" example”.

Compose your Query String

Based on the above query syntax, it is easy to compose your own query string.

Important Note: For the identifier in query syntax, please refer to field alias and Built-in Attributes.

Here are several examples.

Example 1: Query all the defects with tags “bvt” whose state is not “Closed”

Note: here defects’ state “default_workflow.state.s1” means “Closed”. This may vary in your customized workitem type.

>>> query_str = ('dc:type="defect" and '
                 'rtc_cm:state!="default_workflow.state.s1" and '
                 'dc:subject="bvt"')

Example 2: Query all the defects which are modified after 18:42:30 on Dec. 02, 2008

Note: here defects’ state “default_workflow.state.s1” means “Closed”.

>>> query_str = 'dc:type="defect" and dc:modified>="12-02-2008T18:42:30"'

Example 3: Query all the defects with tags “bvt” or “testautomation”

>>> query_str = 'dc:type="defect" and dc:subject in ["bvt", "testautomation"]'

Example 4: Query all the defects owned/created/modified by “tester@email.com

>>> user_url = "https://your_domain:9443/jts/users/tester@email.com"
>>> query_str = 'dc:type="defect" and rtc_cm:ownedBy="%s"' % user_url
>>> query_str = 'dc:type="defect" and dc:creator="%s"' % user_url
>>> query_str = 'dc:type="defect" and rtc_cm:modifiedBy="%s"' % user_url

Note: please replace your_domain with your actual RTC server domain.

Example 5: Query all the defects whose severity are “Critical”

>>> projectarea_name="My ProjectArea"
>>> severity = myclient.getSeverity("Critical",
                                    projectarea_name=projectarea_name)
>>> query_str = 'dc:type="defect" and oslc_cm:severity="%s"' % severity.url

Example 6: Query all the defects whose priority are “High”

>>> projectarea_name="My ProjectArea"
>>> priority = myclient.getPriority("High",
                                    projectarea_name=projectarea_name)
>>> query_str = 'dc:type="defect" and oslc_cm:priority="%s"' % priority.url

Example 7: Query all the defects whose FiledAgainst are “FiledAgainstDemo”

>>> projectarea_name="My ProjectArea"
>>> filedagainst = myclient.getFiledAgainst("FiledAgainstDemo",
                                            projectarea_name=projectarea_name)
>>> query_str = 'dc:type="defect" and rtc_cm:filedAgainst="%s"' % filedagainst.url