Issue Tracker Query

How to query with the IssueTracker

This page contains extended information about how to make queries with the IssueTracker and work with them.

About querying the issue database

The Issue Tracker query form allows you to call up a subset of issues from a project's issue database. If you do not select an option, the designated default values are included in the query. Submitting a query without setting any options at all, for example, returns all project issues with a status of NEW, STARTED, or REOPENED. You can narrow query results by selecting options and/or entering information in the query form fields. You can save your results list in your bookmark file. You can also save your query configuration to reuse later.

Issue query selection fields

The following fields are available for narrowing the query results.

Issue type

the classification of issues as either tasks, defects, features, or enhancements.

Component

the part of the project associated with the issue you are querying to find. If you don't choose a component or subcomponent, the query addresses all issues for the project.

Subcomponent

a subset of the component you selected in the previous field. If you don't choose a sub component, the query includes all issues for the component.

Status

default values for this fields are NEW, STARTED and REOPENED. When searching for issues that are UNCONFIRMED, RESOLVED, VERIFIED, or CLOSED, remember to change this status field appropriately.

Resolution

the qualification of issues with a status of RESOLVED, VERIFIED, OR CLOSED. All resolved issues must be assigned one of these values.

Priority

queries for issues by their rank of importance using the following scale: P1 is highest priority, given to issues that should be addressed as soon as possible; P5 is the lowest priority.

Platform

is the type of computer the issues is associated with. This field is most critical when searching for defects. When querying for other types of issues, it may not be necessary to make a selection in this field.

OS

is the type of operating system the issue is associated with. Again, when querying for other types of issues, it may not be necessary to make a selection in this field.

Version

The release of the software associated with this issue. Leaving this field unselected queries all versions of the selected project or component.

Target milestone

queries for issues associated with different project milestones, if your project has these. Milestones typically are dates when certain features or overall versions are expected to be completed.

Username

lets you query for issues by the username of assignee, reporter, QA contact, cc list, or added comments. A duplicate field lets you further refine queries based on this criteria. To search for issues associated with a username:

• Type a portion of a username into the text field.
• Select fields to query for association with that username.

The second field enables you to look for two different usernames. If you specify both, then only issues matching both are returned in your query results. For example, this is useful to find issues "created by Ralph" and "assigned to Fred."

You can also use the drop down menus to specify whether you want to match username by doing a substring match or exact match of a fully specified username.

Miscellaneous query fields

Additional input fields let you further qualify queries by issue number(s), date changes, number of votes, and changes in field values.

Summary

allows you to query on the one-line abbreviated description of the issue used by default in reports and query results.

Description

allows you to query by text string from the longer, detailed issue description.

URL

allows you to query by the web page location associated with issues, when applicable.

Status Whiteboard

allows you to query on the field defined by the project owner (or users with Issue Tracker administrative permissions). Input values to query by this field thus depend upon how it is being used in a particular project.

Keywords

allows you to query on the keywords defined for the project. If the project administrator has not defined any keywords, this field will not appear on the Query page. To view a list of the keywords defined for this project, click the Keyword link next to this field.

Those who prefer to devise their own query schemes beyond options provided in these from fields provided can set up Boolean chart queries.

Sorting and customizing query results

Before submitting a query, you can select to sort by issue number, importance, or assignee. After you submitted a query during an Issue Tracker login session, you have the option to "Reuse the same sort as last time."

Once you view the query results, clicking on any of the column headings will sort the displayed results within that column.

Using the links at the bottom of the query results page, you can also:

• Switch to "long format" view of results to display complete contents of issues.
• Load a new query form.
• Enter a new issue.
• Change which columns appear in query results.
• Change several issues at once. (This option displays a page that lets you select issues from your query results list and modify specific fields in all of these simultaneously.)
• Send e-mail to owners of issues listed.
• Edit the configuration of the last query.
• View XML representations of all issues returned
• Download the query results in different formats (Excel, CSV, tab-delimited)

To add the target milestone for each issue to your query results -- and you should do so when a particular issue is slated for release --

1. Do a query (or click "view assigned issues").
2. Click the "change columns" link at the bottom.
3. Click the "target milestone" check box.
4. Submit.

The target milestone column will now included for all your subsequent queries because login sessions are cookie-based. You can unmark this checkbox or mark others at any time to change your customized query results.

Customizing and remembering queries

Once you've set up a fairly complex query to ferret out certain issues, you can tell the Issue Tracker to "remember" your custom queries as a time saver. Using the options just above the Submit query button, you can save your most recent query under a unique name and reuse it anytime you are logged in to the Issue Tracker. You can also change and reset the default query that the query page loads during your login sessions.

To include your custom, named queries in the footer of the query page, click on the "Edit prefs" link on any of the Issue Tracker pages and select the "Page footer link". All of your named queries have the option to be included on every page or only on the query page.

Tracking your own issues (or by assignee)

To view a list of project issues assigned to you, click the My Issues link in the Issue Tracking page.

Once you have invoked the Issue Tracker, you can also click the My issues link in the secondary Issue Tracking tool bar.

You have two options for viewing other project members' assigned issues:

• Create an Issue Tracker query using the "search the issue database" link and search by the "assigned to" field with the person's name entered. (The default setting for the "status" in the query screen includes NEW, STARTED, and REOPENED.)
• Select the "Members" link in the left navigation bar to view a list of project members by name, each with a link to their assigned project issues.

You can copy the URL of a query's result and paste it into an HTML file to help you create quick access tools for the project. For example, you could create a page listing project members by name with links to their specific list of issues by querying on the assigned to field for each user and pasting the resultant URL into an HTML page listing the project members. This page could then be added to the Documents and files section of the project to give members a quick and easy way of viewing the lists of issues assigned to themselves and other project members.

Running queries not supported by the query fields

You can perform some searches that are not supported by the query form by using the issue list script to build queries based on the URL. You can add other criteria to these queries.

For example, if you wanted to see all issues reported against the X platform and assigned to user "jwz," you could ask for all issues assign to jwz, then edit the URL in the "Location" box, adding the clause "&rep_platform=X-Windows" to the URL.

Here is a list of some of the field names you could use for additional unsupported searches ...

• version
• rep_platform
• op_sys
• reporter area
• issue_file_loc
• short_desc

Managing query results

After running an Issue Tracker query, you can view or download the query results in several different formats by clicking one of the buttons below the query results table.

• Long format: Query results are presented in the browser window in detail. This format includes all data fields containing values in the issue and field name labels.
• Format as XML: Query results are saved to a file on your local drive in XML format. Clicking this button takes you to the Format as XML page where you can define your export parameters before saving the file.
• Excel format: Query results are saved to your local drive in an Excel (.xls) file.
• Comma-delimited: Query results are presented in a comma-delimited (.csv) file. You can open this file or save it to your local drive.
• Tab-delimited: Query results are presented in a tab-delimited test (.txt) file. You can view the results in your browser or save them to your local drive.

Format results as XML

The Format as XML page allows you to define the file containing the XML representation of your query results. You can choose whether to include issue attachments or the DTD in your export file as well as whether to display the file in the browser or download it to your local drive. You can also define the file name.

Including the DTD in the export file is provided as a convenience for those who may be unable to reference the DTD across a network. Under most circumstances, doing so is unnecessary.