Queries (7.9)

Since 8.0 Queries functionality has been renamed to Reports and has extended functionalities and completely changed user interface, see here Reports

Queries is a new project independent way (since 7.9.0) to search/filter work items ad-hoc or for later reuse across multiple projects using cbQL .

Handling Queries

By default Queries opens a New Query, you can create simple queries via the query condition editor or complex queries in advanced mode using the cbQL syntax.

When first saving your query you need to give it a name and optionally you can add roles from projects that you want to share the query with and a description.

Two kind of access level can be assigned: read and write, write also gives read permission.

When assigning permissions you select a project you have access to and then select one or multiple roles, select access level and press the add button.

After the first save you can simply update your query with the save button the properties window will not popup, if you want to modify other

aspects of the query you can use the context menu.

• Revert changes: reloads the current query, useful when you modified the query but not saved yet.
• Duplicate: open the properties overlay, but instead of updating the current query when saving it will create a new one.
• Properties: opens the overlay you used to first save the query, you can rename, add description, add/remove permissions.
• Delete: after a confirmation you can delete your query
• Unstar: all new queries are stared by default you can unstar it with this menu item

My Queries

In the my queries section you have predefined queries and starred queries.

• Predefined Queries: predefined queries are created by codeBeamer and cannot be modified
• Starred Queries: are your queries or queries that are shared with you that you star

Find Queries

You can find queries that you created or that are shared with you, you can also star and unstar them.

Export to Excel

Queries can be also exported to excel:

There are three types to export to excel:

• simple: export with the same set of columns you can see in the search results table
• extended: export with the extended set of columns
• template: export via template

Queries widget

You can use the Query widget to easily build your own Query. The widget is for adding different (mostly useful) conditions without you have to type cbQL language syntax.

By default you can see the Project, the Tracker and the Status selectors. Furthermore you can add the following conditions by using the condition context menu clicking the button inside the widget:

• Assigned to
• Category
• End Date
• Modified at
• Owner
• Priority
• Resolution
• Severity
• Start Date
• Story Points
• Submitted at
• Submitted by
• Summary
• Reference to
• Reference from

Between the selected conditions there is AND connection, and where you can choose multiple values from a list, there is OR connection between the selected values. Example: you select one project (projectId = 123), one tracker (trackerId = 456), and in the Status selector two status meanings, Resolved and Closed. In this case the operators between the conditions look like: project.id = 123 AND tracker.id = 456 AND (workItemStatus = 'Resolved' OR workItemStatus = 'Closed").

Except Reference to and Reference from options all options can be selected only once in one Query. If a condition is already present in the widget, you are not able to select once more (they will be disabled in the context menu). You are able to remove conditions by clicking the button next to each condition boxes.

If you are ready setting the desired conditions, click on button to see the result.

Type of the conditions

Project/Tracker selectors

You can filter the tracker items firstly by projects and then by trackers. At the beginning of the project list you can see your recently visited projects, after the other projects. Once you choose some projects in project selector, the tracker selector will be refreshed by the selected projects. If you have many projects/tracker, you can filter the lists by starting type in Filter input box inside the selectors.

Field value/meaning type selectors

The following conditions belong to this selectors: Category, Priority, Resolution, Severity, Status.

The possible values of these fields depend on which trackers are selected in the Tracker selector, in the list you will see the field values grouped by the selected trackers. Once you select or deselect tackers in Tracker selector, these fields will be refreshed automatically and will show always a consistent state.

Furthermore if you select Status or Resolution, you can filter also by meanings of the field values. The Status and Resolution meanings for values can be set on Tracker customization page. On Query widget the meanings do not depend on selected trackers, have fix values, which are the followings:

• Status: Unset, In progress, Resolved, Closed, Obsolete
• Resolution: Unsuccessfull, Successfull, Obsolete

You also can use the Filter option inside these selector for filtering meanings / field values.

User type selectors

The following conditions belong to this selectors: Assignedto, Owner, Submitted by.

By selecting these conditions, you will see a list of users and roles (except Submitted by) depending on which projects are choosen in the Project selector. If you does not select any projects, you will not see any roles, and all of the visible members of the projects assigned to the current user will appear. At the beginning of the values there is a "Me" option which means the current user. The values of these fields are also refreshing automatically if you change projects in the Project selector.

Three properties of the users are appearing in the list: the user name (or user alias configured in general.xml), the real name, and the domain of the user's email address. You can filter by these three properties if you begin to type in the Filter input box inside the selector.

Date conditions

The following conditions belong to this selectors: End Date, Modified at, Start Date, Submitted at.

By selecting date conditions, you will see a small control box, in which you can set your date ranges. Two options are available:

• Range by Date: in this case you can specify exact "from" and "to" dates using datepicker.
  
  
• Range by Period compared to today: in this case you can set relative date range compared to today (n days/weeks before/after today, where n is a positive integer).
  
  

You can use only one of these options.

Text conditions

The following condition belongs to this selector: Summary.

You can filter by summary (name) field of the tracker items. SQL wildcards and negation are allowed to use here. Example: if you would like to see tracker items where the summary not contains "test", you should type here: "%test%" and check the "not" checkbox.

Number field conditions

The following condition belongs to this selector: Story Points.

You can filter by Story Points field of tracker items. You should set the operator (greater than >, greater than or equals to >=, equals =, less than or equals to <=, less than <) and the integer number.

Reference conditions

The following condition belongs to this selector: Reference from, Reference to.

You are able to filter tracker items by downstream and upstream references. By clicking a selected reference type conditions, a small overlay opens, in which you can set the desired referring tracker items. Firstly you have to select one ore more project(s) then one or more tracker(s), and then you can use the autocomplete field or the pencil icon to select the tracker items. Only valid items will appear, so according to the selected trackers. Between the selected items there will be OR connection. You are able to add more Reference to and Reference from conditions to be able to perform the AND connection.

Order by

It is able to order the result by the followings:

• Assigned to
• End Date
• Modified at
• Priority
• Resolution
• Severity
• Start Date
• Status
• Submitted at
• Submitted by
• Summary
• Tracker
• Item ID

You can define here reverse order by switching on the DESC checkbox. You are able to add more Order by options, the order of this options will define the ordering of the result table.

Advanced mode

The Query widget with the conditions is just for helping define the most useful queries without learning and typing cbQL query language, but does not contain all of the functionalities what cbQL language knows. There is an Advanced mode where you can define cbQL expression whatever you want, just click on Advanced in the right side of the widget container. You can see more details about cbQL language here: cbQL.

Known limitations

• During the rendering of Queries, Charts or even Views field values are considered into Results regardless of the Current User Field or Work Item status Permission.
• Legacy field types are not supported. Supported tracker types: (Bug, Change Request, Component, Configuration Item, Issue, Platform, Release, Requirement, Risk, Task, Team, Test Case, Test Configuration, Test Run, Test Set, Time Recording, User Story)
• Only one custom field supported for Groups and Order by
• Custom fields with the same field names are not supported
• Field and Status permission not supported
• Color and table fields are not supported
• Group value formatting and ordering are not supported
• Filter Work Items by Roles are no longer supported because of server limitations
• Reconfigured default fields are not supported (reference configured as choice option or vica versa)