Features

All TeamCompanion features documented with detailed description, images and videos.

Work Item Query Editor

TeamCompanion features an enhanced version of the grid based Work Item Query Editor. It supports all standard actions related to the management of all query types: Flat List, Work Items and Direct Links and Tree of Work Items. Besides that, it expands the editing experience with many additional features, allowing you to create and edit your work item queries in the easiest and most efficient way.

You can edit existing work item queries and add new queries under My Queries, Team Queries or any of their query subfolders.

Editing and adding Work Item Queries in Query Editor
TeamCompanion's Query by Example Editor - QBE

The TeamCompanion's smart Query by Example - QBE editor is a simplified work item query editor that makes it easier to define frequently used flat work item queries. Queries are defined by entering values in existing placeholders preset for most frequently used work item fields (like State, Priority, Iteration, Area Path, etc.). QBE also supports full text search in any text or html work item field.

TFS standard Query Editor and Column Options, and enhanced Query Results viewer embedded in TeamCompanion

TeamCompanion features the standard grid based Query Editor as well. These two editors are synchronized, what means that you freely switch between them while editing your search conditions.

The embedded Query Results editor window enhances the standard TFS preview of work item query results.

Editing and Adding Work Item Queries

To open an existing work item query in the Query Editor, click on it in the team project subtree, and on the Work Item(s)/Query tab, in the Query group, click on the Edit button. Alternatively, you can right-click on it and select the same action from its context menu.

To add a new work item query under My Queries, Team Queries or under one of their query subfolders, click on the corresponding node or folder in the team project subtree, and on the Work Item(s)/Query tab, in the Query group, click on the Add button. Alternatively, you can right-click on the node or query folder and select the same action from its context menu.

The Query Editor appears in a separate modeless window, and you can switch context between this window and the main Outlook window. It consists of following areas:
- the top Query Toolbar;
- the tabs Query by Example, Query Editor, Column Options and Query Results.

Editing and adding Work Item Queries in Query Editor
TFS standard Query Editor and Column Options embedded in TeamCompanion

Using the Query Toolbar and the controls in the top part of the tabs Query Editor and Column Options, you can perform all standard actions related to work item query management. TeamCompanion uses the standard look and feel for the full action set described in the corresponding MSDN documentation. The Column Options tab contains additional options for saving query grouping setting.

The bottom part of the tabs Query Editor and Column Options contains the grid with Query Results together with an embedded Query Results Toolbar. For more information about them see under Viewing query Results.

Enhanced TFS Query Results viewer and TeamCompanion's Query by Example editor - QBE

The added value of the TeamCompanion's query editing experience is implemented on the tabs Query by Example and Query Results.

Query by Example Editor - QBE

The Query by Example Editor is the TeamCompanion's custom simplified work item query editor for editing work item queries of type Flat List. It is usually referred to just as QBE and can be found on the tab Query by Example of the Work Item Query Editor supported by TeamCompanion.

The standard TFS query editor is powerful, very flexible and supports a wide range of options, which makes it too complex for most standard everyday queries. Although there are only a handful of work item fields usually used in queries, the user needs to pick them from a long list of fields each time he works with the query. Furthermore, field names are not always intuitive, what creates a lot of confusion, especially if you are a novice user. These are only some of the issues of the standard query editor that led us to the idea of presenting you with a better querying experience.

In QBE, frequently used work item fields are already predefined in form of dropdown controls labeled with user friendly field names. In order to define your search criteria, you only need to choose the desired fields and fill in the values of corresponding controls. Defining your search criteria this way is more intuitive, easier, faster and certainly more straightforward – most of the queries can be defined with just a few clicks.

The top part of the tab Query by Example implements the custom query editor using 5 (right) tabbed panels. Work item fields and querying options are grouped in 5 different groups and presented on these panels as follows:
- the tab General contains general query filter fields like Project name, State, Work Item Type, Area, Iteration, etc.;
- the tab State transitions contains work item fields related to work item state transitions like Created on, Created by, Resolved on, etc.;
- the tab Text contains controls for full text search over different text work item fields;
- the tab Historical Queries is used when you need to evaluate the conditions defined in your query at a specific point of time in the past;
- the tab Additional criteria appears when your query uses conditions for fields not provided by previous 4 tabs.

The bottom part of the tab Query by Example contains the grid with Query Results together with an embedded Query Results Toolbar. For more information about them see under Viewing Query Results.

TeamCompanion's Query by Example Editor - QBE
QBE – General query conditions

In order to explain the usage of TeamCompanion's Query by Example (QBE) Editor, we will start creating the following query:
Return all active tasks and user stories assigned to me in the current project.
Position on the tab General and create your query with following few clicks:
- the condition for the Project dropdown is already set to the current team project;
- select "@Me" from the Assigned to dropdown;


- select "Active" from the Status dropdown;
- check the checkboxes for work item types Task and User Story.
Run your query to preview its results.

QBE – State transitions query conditions

Next, we will add this additional criteria from the State transitions tab:
Return only work items that I have activated in the last 30 days.
Refine your query with another few clicks:
- select "@Today-30" from the Activated date dropdown;
- select "@Me" in the By dropdown in the same row.
Run your query again to preview its refined results.

QBE – Text query conditions

Finally, we will add additional full text search criteria to our query on the Text tab:
Return only work items that contain words "review" and "reports" in the fields Title or Description.
Refine your query furthermore with just another few clicks:
- enter the words "review" and "order" in the Search for text box;
- select "Any Terms" radio box under Match;
- check the checkboxes for work item fields Title and Description.

Run your query again to preview its final results. You can make additional changes to your query using the described QBE tabs and controls. Names of QBE tabs that contain current conditions are bolded.
To fully define the output of your query, switch to the Column Options tab and configure column options, sorting order and grouping.
Finally save the query for later usage.

Query edited using QBE show in embedded TFS Query Editor

To understand the level of complexity of this query, switch to the Query Editor tab. The same query we just defined in QBE is presented in the standard TFS grid based editor and is quite complex. Creating the same query in this editor, demands an advanced knowledge of work item field names, rules for setting conditions and various other query rules. On the other hand, by using QBE, you created a complex query in an intuitive way, very quickly and with just a few mouse clicks.

The same query can be further refined in the standard query editor. You can change any of the existing criteria or add some completely new criteria. QBE has a finite set of fields available, while the standard grid has no such restrictions. You can add a condition for any other field and, as long as you choose the AND operator while adding new fields, you will be allowed to switch back to QBE and continue editing the query there.

Adding conditions to QBE query through the embedded TFS Query Editor (1)

As example, we will add this additional condition to our existing query:
Return only items worth more than 4 story points .
To extend your query, you must add this condition in the query editor, by adding a new clause with the right work item field and condition value.

Adding conditions to QBE query through the embedded TFS Query Editor (2)

Now, when you switch back to QBE, the tab Additional criteria appears, containing controls that allow you to manipulate conditions for the newly added work item field.

If QBE were just an elegant way to define queries using a hardcoded set of fields, it would clearly be of limited use. To maximize the number of query scenarios QBE can cover, TeamCompanion handles custom fields added in Query Editor, and not provided by default in QBE, by adding sets of ad-hoc controls to the Additional criteria tab. As long as the query structure is such that QBE can present it, such fields will be available on this tab.

The basic condition a query needs to satisfy to be editable in QBE is that it is flat and that all filter clauses at the root level must be connected using the AND operator. There are some operators, like IN, that QBE doesn’t support. QBE does not support hierarchical queries.

Conditions added through TFS Query Editor unsupported by QBE

TeamCompanion tracks each change made in the query editor or on the top query toolbar (where you can change the type of query), and parses the new query to determine if it can further be edited in QBE. If you switch to a hierarchical query or your changed conditions are not supported (editable) in QBE, the Query by Example tab is disabled. As soon as you remove unsupported clauses or return to a flat query, QBE is enabled again.

This full two-way synchronization between QBE and the standard Query editor, delivers you the best of both worlds: QBE efficiency and ease of use and Query Editor flexibility. In most cases you can easily and freely switch between these two editors and use the one that best suits your current needs and work item querying habits.

Tipp: On the General tab, QBE support a quick way to remove any clause defined using the operator combo and a value control (like State, ID, Priority, etc.). Simply clear the operator by choosing the empty string from the combo and this action will automatically empty the value control as well.

Tipp: On the State transitions tab, "After/On" (equivalent to ">=") or "Before/On" (equivalent to "<=") operators are used by default for all date fields. In order to keep a simple user interface, these operators are read only and cannot be changed on this tab. But, if you switch to the standard query editor and change the operator for any of these fields (to "=", ">", "<", etc.), we will honor it. When you switch back to QBE, the operator will be changed respectively.

Viewing Query Results

The Query Results tab of the TeamCompanion's Work Item Query Editor enhances the standard TFS preview of work item query results. The top part of the tab contains the grid with Query Results together with an enhanced Query Results Toolbar. This is the same grid and toolbar embedded as the bottom part of other tabs Query by Example, Query Editor and Column Options in this window.

The bottom part of the tab contains the TeamCompanion's Embedded Work Item Form showing the currently selected item from the grid.

Enhanced TFS Query Results viewer embedded TeamCompanion
Supported work item management related actions in Query Results Viewer

The Query Results grid contains the work item query result list and supports many standard work item management related actions:
- opening work items;
- adding new linked work item(s);
- creating work item copies;

If you are viewing results of a hierarchical work item query, then you can perform all standard actions related to editing work item hierarchies, like indenting/outdenting items or changing the item's hierarchy using drag and drop.
Additionally, you can export your work items to Microsoft Office Excel and Project.

All described actions are available on the query result toolbar and in the context menu of each item in the list.

The embedded work item form shows the currently selected item from the grid and comes with the full feature set as in other parts of TeamCompanion.