Searching Work Items

Polarion has extremely powerful Work Item query capabilities, thanks to its integration of the Apache Lucene query engine. Lucene is mainly a command-line tool. Users who already know Lucene query syntax and Polarion's Work Item fields and variables can execute command line queries Work Item Query Builder. However, if you don't have this knowledge at your fingertips, you can user the Query Builder's graphical assists to easily build simple and complex queries to search for and retrieve the Work Items you want in any view of the Work Items topic, as well as in dialogs such as the Work Item Picker where you query for Work Items.

TIP

You can also use the Query Builder to search for Documents, Pages, Plans and Test Runs.

Constructing Queries Graphically

Every view in the Work Items topic provides the Query Builder in the toolbar or header. You construct queries by visually adding query elements to the Visual Query Builder. Query elements visually represent parameters of the underlying command-line syntax.

When you enter the Work Items topic, one default query element is shown in the Visual Query Builder: Unresolved. This element, alone, retrieves all unresolved Work Items. To get the results you want, you can either keep this element and add more to refine the results, or remove it and start adding different elements.

  • Click the X inside a query element to remove it.

  • Click the in the query builder to add a query element.

When you click to add an element, a pop-up bubble shows you 3 lists: often-queried fields (Favorites), recently queried fields (recent), and all fields, including custom fields. Fields are listed by Name, so you do not need to remember or use field IDs as you must for command-line queries.

Figure 6.15. Work Item Visual Query Builder

Work Item Visual Query Builder

Visual query elements and actions in the Visual Query Builder tool for Work Items

Tips and Tricks

  • You can clear all visual query elements or command-line text from the Visual Query Builder by clicking the X icon near the right-hand end of the tool.

  • Close element pop-up "bubbles" by clicking anywhere outside them.

  • If there are many visual query elements and some are scrolled out of view and/or condensed, you can see the condensed names and/or access and edit them using the list of all current elements. To display it, click the drop-down arrow on the left side of the query builder. You can also use the list to remove any query element from the Query Builder.

  • The Recent section in the query element pop-up displays a list of the fields and field values you selected most recently. The items in this list can help you create often-needed queries eliminate the need to save them.

  • You can convert any graphically constructed query to command-line text by clicking the drop-down arrow at the right-hand end of the query builder and selecting the Convert To Text option. This lets you build queries visually and copy the syntax to use it elsewhere... in the Query parameter of a LiveReport Widget, for example.

  • You can use the Query Builder in command-line mode by removing all graphical query elements and typing in valid command-line query syntax.

  • You can use both visual query elements and command-line text in the query builder. See User Reference: Work Items: Advanced Work Item Querying: Combining Text with Visual Queries.

  • The URL displayed in your browser contains a parameter query, which contains the full command-line syntax of the current query in the Query Builder. You can copy this parameter and use it in the query parameter of LiveReport Widgets or other places where Lucene query syntax is required.

  • The Visual Query Builder contains an element SQL, which can be used alone to filter the Work Items table by a SQL query only, or in conjunction with other visual query elements. For more information, see Using SQL Queries to Retrieve Work Items.

See also: User Reference: Advanced Work Item Querying.

Saving and Sharing Queries

Commonly needed queries can be saved and reused. Saved queries can be global in scope (i.e. accessible to all portal users), limited to one Project (accessible only to users who have a project role assigned), or limited to access by you only.

To save the current query in the Visual Query Builder:

  1. Click the drop-down arrow at the right-hand end of the Visual Query Builder and click Save Current Query.

  2. In the Save Query dialog, enter a descriptive name, and select whether the saved query should be accessible globally by all portal users (Global), project locally by users having a project role (Project), or only by you (User).

Running a Saved Query

You can re-run any saved query to which you have access.

  1. Click the drop-down arrow at the right-hand end of the Visual Query Builder.

  2. In the pop-up bubble listing available saved queries, click on the name of the query you want to run.

TIP

You can copy the command-line syntax of a saved query to your clipboard by depressing your Ctrl or Cmd key and then clicking on the saved query name.

Personal Default Query

By default, Polarion runs a system default query specified in the system configuration whenever you access the Work Items table. You can override that default and set any query as your personal default query, to be run whenever you access the Work Items table. Your personal default query will also be used wherever the system default query is normally run.

You can create different personal default queries for different scopes. For example, you can create one default query that runs when you are working in the scope of a project, and a different one when you are working in the scope of a project group or the Repository. If you switch to a project or project group for which you have not defined a personal default query, the system default query will be applied.

To create a personal default query:

  1. Use the Visual Query Builder tool to construct the query you want.

  2. Click the drop-down control on the right-hand side of the query builder, and in the pop-up panel click Save as Default (see screenshot in the previous section above). Confirm the action in the dialog that appears.

You can change your personal default query any time by repeating these steps with a different query.

Preference When Switching Contexts

Suppose you expand the Work Items topic in Navigation, and then select one of the types - Requirement, for example. Then, suppose you specify a query like Status: Draft, which filters the table to show only Requirements items with Draft status. If you now select a different type in Navigation - Test Case, for example, by default your query Status: Draft is preserved and the table is filtered to show Test Case items with Draft status. This may or may not be what you want when you switch the context.

The same is true in a larger context switch. For example, you might be looking at the table showing Requirements with Draft status, and then switch to a different project. Or you might be looking at the Table view of a Document, and switch to a different Document. In all cases, your current query is preserved and the table in the new context is still filtered to show Requirements with Draft status. In the new context, the query results might not be what you need.

Whenever you switch to a context in which the current query's result may no longer be valid, a warning icon appears in the Visual Query builder. Clicking the icon displays a dialog in which you can specify the behavior you prefer when switching contexts.

Figure 6.16. Set Preference for Context Switching

Set Preference for Context Switching

The dialog title and text vary depending upon the context switch (switching between Work Item types as opposed to switching to a different Document, for example), but the options are the same.

  • Always Use Default Query - When you switch to a different context, the default system query for the context will always be executed. For example, when switching to a different Work Item type, the Work Items table always shows only Work Items of the selected type in the table. Any user-defined query present in the Visual Query Builder before the switch is deleted.

  • Always Keep Current Query - the system preserves any user-defined query present in the Visual Query Builder before the switch. Be sure you are aware of the effect of the preserved query. You may want to modify or remove it after the context switch.