Work Items

This section provides reference information related to Work Items and the Work Items index and index fields. There is also information for those using Polarion's implementation of the Apache Lucene query language for embedded queries in configuration files, Wiki pages, API calls, etc.

Prioritization Panel

This panel can be used to assign a Priority field value to multiple selected Work Items in the Table or Tree views of the Work Item Tracker (Navigation > Work Items). For conceptual and procedural information, see the User Guide topic Prioritizing Work Items. This topic provides information about the components of the panel. Please refer to the following figure:

Figure 2.20. Prioritization Panel Components

Prioritization Panel Components

Reposition Buttons

These buttons move a selected Work Item or a selected group of Work Items upward or downward in the table. On move, selected items are rescaled according to the new position in the table. The buttons, left to right:

  • Move selected item(s) to the top of the table

  • Move selected item(s) up one row in the table.

  • Move selected item(s) down one row in the table.

  • Move selected item(s) to the bottom of the table

Rank Selector

Displays a drop-down menu showing the priority ranks currently configured for the project. The priority rank of all selected Work Items is set to the selected rank on Save.

Priority Field

Accepts a float value. The numeric priority value of all selected Work Items is set to the specified value on Save, overriding any value previously set in the Rank Selector.

Change Prioritization Field

Enables you to prioritize the items in the table on a custom field rather than the standard Priority field. The pick list displays all fields that are valid to use for prioritization in the current context. For more information, see the User Guide topic Prioritizing on a Custom Field.

Dialog: Rescale Selected

Rescales the numeric priority value of all Work Items currently selected in the table, limiting the maximum value to that specified in the Top field, and/or the minimum value to that specified in the Bottom field (if that field is present in the dialog... it is only present when relevant).

If Keep Rank is checked, none of the selected items will have their value set above the maximum value for their current rank. For example, if a selected item currently has rank "Medium", and rescaling would set the value higher than the maximum for that rank (thereby giving it a rank of "High"), that item will not be rescaled to any value not within the "Medium" range.

Dialog: Rescale All

Rescales the numeric priority value of all Work Items in the prioritization table. Items will be rescaled within the range specified in the Top and Bottom fields.

Keep Rank functions in the same way as in Rescale Selected, except that it operates on all items in the prioritization table.

Tip

If you are prioritizing a set of Work Items that all have the same priority, as is usually the case when the items were created by import from a Microsoft Office document, it is advisable to run Rescale All before beginning to manually prioritize the items.

Work Item Field Permission Restrictions

Administrators can configure restrictions on permission to read and/or modify Work Item fields. In particular, the permission to MODIFY a Work Item field can impact users' ability to perform some operations. The following sections describe this impact.

New Work Items

If a user is denied permission to MODIFY any Work Item fields, the ability to create new Work Items is limited as follows:

Table 2.22. Restriction on Creating Work Items

Required Field?Default Value Configured?Result for User

YES

YES

Create is allowed. Default value is used, and user cannot modify it.

YES

NO

Create is disallowed. Message is displayed to user.

NO

YES

Create is allowed. Default value is used, and user cannot modify it.

NO

NO

Create is allowed. No value is set. User cannot modify field.

Imported or Re-imported Work Items

If a user is denied permission to MODIFY some Work Item field(s), and the user imports new Work Items or re-imports round-trip Work Items which hold values for the restricted fields, those fields are ignored by the importer, the field values are not imported, and the user sees a message about the restriction.

Work Item and Index Fields

This topic documents the standard Work Item data fields. The field names are typically shown in Work Item form and in the column labels of the Work Items table. They also appear in the helper panel of the visual query builder.

When constructing textual queries using the Lucene query language, you will need to reference Work Item field IDs (rather than field names). IDs are needed for some configurations, macro parameters, API calls, etc. The table below lists all available fields and their ID values. Due to the way Polarion indexes Work Item data, there are some Work Item fields whose field IDs must not be referenced in queries. Such fields have one or more searchable Index IDs, which should be used in queries. These are noted in the Index IDs column of the reference table. For example:

{workitems: timePoint.time:[20120101 TO 20120212] AND assignee.id:$me | fields=id, title, severity, assignee, timePoint 
| sortby=timePoint created}                    
            

Notice that the field IDs of the Time Point and Assignee fields are not referenced in the query portion of the macro. Rather, the index IDs timePoint.time and assignee.id are used.

There are also some IDs that can be used in queries, but which are not fields of the Work Item itself. Rather, they are fields in the Work Item index. Consequently there is no Field ID, name, or description. These are noted in the Index ID column of the reference table.

When a field is tokenized, it means that is it possible to search objects by sub-strings contained in the field. This is most useful for querying for values in text fields such as Title and Description.

Sortable index fields can be used for ordering of the query results or searching by range. These index fields contain special converted values (e.g. lowercase) of the fields, which are computed by special index functions.

Table 2.23. Table of Work Item Fields

Field NameDescriptionField IDIndex IDsOn Form

Approvals

Field that stores record(s) of approval(s) of the Work Item.

approvals

approvals (tokenized)
approvalState

Uses a special index function and therefore special syntax. See Querying for Approvals.

yes

Assignee

This field defines the person responsible for a Work Item. The specified person will receive automatic notification(s) about the assignment and any changes to the Work Item.

A Work Item can be automatically assigned to a user specified in the auto-assignment configuration by selecting the value automatic in this field's combo box. This is the default for all new Work Items.

For information about the auto-assignment configuration, see Administrator's Guide: Configuring Auto-assignment.

assignee

assignee.id
assignee.name (sortable, lowercase)

yes

Attachments

Field that stores table of attachments, including link to attached file(s)

attachments

attachments (tokenized)
attachments.author.id (sortable)
attachments.author.name (sortable)
attachments.content (tokenized)
attachments.fileName (tokenized)
attachments.length
attachments.length.1 (sortable)
attachments.title (tokenized)
attachments.updated (sortable)

yes

Author

This field contains the name of the Work Item creator, derived from his/her user account. The value is filled in automatically by Polarion and cannot be changed by users or administrators.

author

author.id
author.name (sortable, lowercase)

yes

Backlinked Work Items

Derived field containing links pointing from other Work Items to the referenced one (e.g. WI-1). These links are not stored in the WI-1 item, but are displayed in the Linked Work Items section of WI-1.

backlinkedWorkItems

backlinkedWorkItems

via linkedWorkItems

Categories

This field enables you to flexibly categorize Work Items according to subsystem, customer, or whatever criteria you need. Category values provide an additional parameter that can be used in search queries. You can assign one or multiple Category values to any Work Item. For information on configuring Categories, see Administrator's Guide: Configuring Categories.

categories

categories.id
categories.name (sortable, lowercase)

yes

Comments

This multiple entry field stores free-form text comments. Users can create multiple comments and comment threads in this field throughout the life of a Work Item.

comments

comments.author.id
comments.text (tokenized)
comments.title (tokenized)

yes

Created

The date a Work Item was created. The non-editable date value of this field is automatically assigned by Polarion and appears in the footer of the Work Item Viewer/Editor.

created

created (date only)
created.1 (datetime)
created.2 (sortable)

permanent

Custom Field (general)

Custom Fields can be defined by administrators in Administration > Custom Fields. There are different types of custom fields such as string, text, enumerations, etc. All custom fields use three different index fields, where the first one is tokenized, the second one is sortable and the third one is a keyword (that is to say, not tokenized).

customFieldId

customField (tokenized)
customField.1 (sortable)
customField.KEY

yes

Description

Field that stores free-form text that describes what assignee(s) must do to resolve the Work Item.

description

description (tokenized)

yes

Document

The Document in which the Work Item is contained.

_document
_space

Each must be configured on the Work Item form separately.

document.id (sortable)

Uses special index function. See Querying for Documents.

yes

Due Date

Date when the Work Item should be competed. It overrides any completion date calculated by the LivePlan planning engine.

dueDate

dueDate (sortable)

yes

Externally Linked Work Items

Field that stores links to Work Items on another Polarion instance (if the system is so configured).

externallyLinkedWorkItems

externallyLinkedWorkItems (URL)
externallyLinkedWorkItems.host (hostname)

via linkedWorkItems

Hyperlinks

Field that stores hyperlinks to other resources inside the Polarion portal, or remote (internet URLs, for example)

hyperlinks

Not searchable

yes

ID

Identifier string that uniquely identifies a Work Item in the Polarion repository.

No field label in the Work Item detail. May be displayed as "ID" in table columns, dialogs etc. elsewhere in the user interface.

id

id
id.1 (tokenized)
id.2 (sortable)

permanent

Initial Estimate

This field is used in Polarion's project and time planning and planning accuracy metrics features. Here users specify an estimate of the amount of time that will be needed to resolve and close the Work Item.

Time unit is specified with shorthand these characters: d for day(s), and h for hour(s).

Time duration is specified by an integer value, or the literal 1/2 (or any other fraction). Examples:

  • 3d - 3 days

  • 7h - 7 hours

  • 1/2d - 1/2 day

initialEstimate

initialEstimate
initialEstimate.1 (sortable)

yes

Linked Revisions

Field that stores links to repository revisions that are stored with the Work Item.

linkedRevisions

linkedRevisions

yes

Linked Revisions Derived

Field that stores links to repository revisions that are derived from recognized IDs in commit messages.

linkedRevisionsDerived

linkedRevisionsDerived

via linkedRevisions

Linked Work Items

Field that stores links to other Work Items, either in the same repository or another repository hosted on another Polarion instance (if the system is so configured).

linkedWorkItems

linkedWorkItems

Uses special syntax. See Querying for Linked Work Items.

yes

Location

Field that stores repository ID and path where the Work Item is stored in the repository. Can be used e.g. to filter only items that are contained in Documents from certain space.

location

location
location.tokenized (tokenized)
location.tree

no

Outline Number

A derived field that stores the outline number of a Work Item, if the item is contained in a Document. Users can search Work Items by outline numbers (also works for partial searches, e.g. 1-2*).

outlineNumber

outlineNumber

Uses special syntax. See Querying for Documents

yes

Parent Work Item

A derived field that stores the IDs of parent items to the current Work Item.

parentWorkItem

parentWorkItem

Must be specified is form parentWorkItem:ProjectId/WorkItemId

no

Planned In

Field of type 'plans', stores the names of all Plans to which the Work Item has been added.

plannedIn

plannedIn (not sortable)

yes

Planned End

Field that stores a date when work on the Work Item is planned to end. Value is normally supplied by the LivePlan project planning engine.

plannedEnd

plannedEnd (sortable)

via plannedTo

Planned Start

Field that stores a date when work on the Work Item is planned to start. Value is normally supplied by the LivePlan project planning engine.

plannedStart

plannedStart (sortable)

via plannedTo

Planning Constraints

Field that stores a constraint on date when work on the Work Item is planned to start or end. Value forces the LivePlan project planning engine to plan the item according to the value set..

planningConstraints

Not searchable

yes

Priority

The Priority field indicates the relative importance and the order in which a Work Item should be processed. This field is used by programmers/engineers to prioritize their work. Work Item with the highest priority should be processed first.

The default values for the Priority field are configured in enumerations. In the system, the value is actually a float number. In the configuration you can define names for certain numerical values. For example: Highest - 90, High - 70, Medium - 50, Low -30 and Lowest - 10. Define values and names in the relevant enumeration configuration. For information, see Administrator's Guide: Configuring Enumerations.

When editing a Work Item, you can specify your own numeric value in the Priority field - just enter a float value in the field.

priority

priority
priority.1 (sortable)

yes

Project

This field is derived and stores the Project where the Work Item is stored.

project

project.id (sortable)

yes

Remaining Estimate

This field is used in Polarion's project and time planning and planning accuracy metrics features. Here users specify the time remaining before the Work Item will be resolved. When a value is initially specified in the Initial Estimate field, the value of this field is automatically synchronized with it. Later, as the item is in progress, the assignee can modify the value here to that the progress on the item is reflected in the reports, metrics, and audits.

Time duration is specified by an integer value, or the literal 1/2 (or any other fraction). Examples:

  • 3d - 3 days

  • 7h - 7 hours

  • 1/2d - 1/2 day

remainingEstimate

remainingEstimate
remainingEstimate.1 (sortable)

yes

Resolution

Indicates the final outcome of a Work Item. The default values are defined in the global and/or project configuration. Keep in mind that values in projects may be from the Project Template from which the project was derived. Also keep in mind that the visibility of the field and/or the ability to change the value may be controlled by the workflow configuration and bound to change of the Status field.

You can customize the values in the relevant enumerations configuration file. See Administrator's Guide: Configuring Enumerations.

resolution

resolution
resolution.1 (sortable)

yes

Resolved On

This is a date field which is updated automatically when a Work Item is resolved. The value is the date the item was resolved. Not usually shown in the user interface but ID may be referenced in reports, queries, etc.

resolvedOn

resolvedOn (sortable)

no

Severity

The Severity field describes the impact (on the end user or customer) of the issue that triggered creation of the Work Item. Values in your configuration(s) should be descriptive in your context: Critical, or Must Have, for example.

In the default configuration for this field, the IDs of Work Items with high severity appear in Red font in the user interface.

The Severity values and respective font colors can be configured in the severity-enum.xml enumeration configuration file. See Administrator's Guide: Configuring Enumerations.

severity

severity
severity.1 (sortable)

yes

Status

The Status field indicates the Work Item's process phase: "New", "Resolved", "Closed", etc. Status values can be configured in the relevant enumeration configuration. See Administrator's Guide: Configuring Enumerations. The status changes are driven by the workflow configuration (see Administrator's Guide: Configuring Work Item Workflow).

The field's combo box has an option Next workflow action which automatically sets the correct value for the field and triggers the next workflow actions including notifications, if any.

Changing the Work Item status resets the Work Item's workflow to the initial status. This affects the planning of the Work Item.

status

status
status.1 (sortable)

yes

Suspect

Field that stores a Boolean value indicating if the Work Item has an outgoing link to another Work Item with the Suspect attribute set on it or not.

suspect

suspect (sortable)

no

Time Point

Time Points are similar to milestones (versions) or development iterations. The list of Time Points can be customized to suit your situation. For information, see Administrator's Guide: Configuring Time Points.

timePoint

timePoint.id
timePoint.time (sortable)
timePoint.earliestPlannedStart (sortable)

yes

Time Spent

This field is used in Polarion's project and time planning and planning accuracy metrics features. Here users specify the actual time spent to resolve the Work Item.

Time unit is specified with shorthand these characters: d for day(s), and h for hour(s).

Time duration is specified by an integer value, or the literal 1/2 (or any other fraction). Examples:

  • 3d - 3 days

  • 7h - 7 hours

  • 1/2d - 1/2 day

timeSpent

timeSpent
timeSpent.1 (sortable)

yes

Title

Each Work Item receives a unique ID automatically so Title should contain a short description of the Work Item. The item can be described further in the Description field.

title

title (tokenized)
title.1 (sortable, lowercase)

permanent

Type

The Type of a Work Item is descriptive of its nature. For example: "Bug", "Task", "Change request". Depending on the Type of Work Item, some type-specific fields can be present or absent in the detail display. For more information, see Administrator's Guide: Configuring Custom Fields.

Changing the type of a Work Item resets the Work Item's workflow to the default Status value which can affect the automated planning of the item.

type

type
type.1 (sortable)

yes

Updated

The date when a Work Item was last changed. The non-editable date value is automatically assigned by Polarion.

updated

updated (date only)
updated.1 (datetime)
updated.2 (sortable)

permanent

WatchedBy

Lets you search for Work Items watched by a specific user.

(watchedBy:username)

watchedBy

yes

Work Records

Field that stores work records. Work records record blocks of time spent working on the Work Item.

workRecords

workRecords (stores dateonly-userId)
workRecords.user.id
workRecords.date (tokenized)
workRecords.comment (tokenized)

yes

Fields Not Imported from Excel

Some fields cannot be imported from an Excel workbook.

  1. Read-only, or only internally modified fields:

    • author

    • created

    • id

    • linkedWorkItemsDerived

    • linkedRevisionsDerived

    • location

    • module

    • outlineNumber

    • plannedEnd

    • plannedIn

    • plannedStart

    • previousStatus

    • project

    • updated

  2. Other fields for which import is not supported:

    • approvals

    • attachments

    • externallyLinkedWorkItems

    • linkedRevisions

    • planningConstraints

    • timePoint

    • workRecords

Advanced Work Item Querying

This section is for advanced users who use command-line queries in the Query Builder, wiki macros, or the API.

Polarion's query language is essentially the same as that of Apache Lucene. The syntax is documented in the Apache Lucene Syntax Documentation), available on the Apache web site.

The following tips are relevant to Lucene queries specified in Polarion:

  • Operators must be typed in upper case: AND, OR, NOT.

  • White space has the same function as the OR operator, so the following queries are equivalent: severity:(blocker OR critical) OR priority:(highest OR high) will return the same result as severity:(blocker critical) priority:(highest high). White space can be also used to separate different values for one term.

  • There is a special field HAS_VALUE, which can be used to determine whether or not an object has a value set in a field or not. For example, to query for items with no value in the resolution field, use NOT HAS_VALUE:resolution.

  • Search terms cannot start with an asterisk (*). For example, something* is a valid query, but *something is not.

  • Queries, including sub-queries, can begin with the NOT operator: NOT severity:blocker, and severity:blocker AND (NOT priority:low OR HAS_VALUE:assignee.id) are valid queries.

    However queries like QUERY1 OR NOT QUERY2 are problematic and must be written in the form QUERY1 OR (NOT QUERY2).

  • Operators have no defined priority, so complex queries should be surrounded by parentheses. For example, (type:userstory AND targetRelease.KEY:1.0) OR (type:defect AND priority:highest).

  • Using many parenthetical expressions in queries may negatively impact performance because more time is spent in query pre-processing. To optimize the performance of your queries, consult the Apache Lucene Syntax Documentation.

The same query language is applicable in a number of administrative tasks such as customization of configuration files that contain query expressions or elements or attributes that consist of a query expression.

Deprecated Query Elements:

Existing queries that use any of the constructs mentioned below still work, but are now considered deprecated and long-term support for them is not guaranteed. It is recommended that you update all such usages in saved queries, macro and page parameters in Wiki pages, API calls, etc. to the recommended form.

  • Work Item field CUSTOM_FIELDS - Querying the HAS_VALUE field is preferred to the CUSTOM_FIELDS field. For example, use: HAS_VALUE:targetRelease rather than CUSTOM_FIELDS:targetRelease.

    Also, custom fields of type enumeration now use the .KEY variant of the field. Example: targerRelease.KEY:2.1.0, and not targetRelease:2.1.0

  • Query constant ######NULL - For querying objects with empty field values, you should no longer use the ######NULL query constant. Use the HAS_VALUE field instead. For example, to query for items with no value in Severity use NOT HAS_VALUE:severity instead of severity:######NULL.

  • Activities field FIELDS - The HAS_VALUE field is also preferred to the FIELDS field for Activities. For example, use HAS_VALUE:field instead of FIELDS:field for Activities.

  • Query parameters ALL:ALL_VALUE and ALL:NO_VALUE - Replace ALL:ALL_VALUE with *.*, and replace ALL:NO_VALUE with NOT *.*.

Search Syntax Basics

Polarion's query engine is based on Apache Lucene. Consequently, query syntax in Polarion is essentially the same as that of Lucene. You may want to download the Lucene documentation. The following table lists some syntax constraints that are commonly needed when constructing queries in Polarion.

Table 2.24. Search Query Syntax Basics

Syntax ConstraintExample

Word or phrase " :


"Word", "Phrase with several words"

title:word
title:"Phrase with several words"                                    
                        

Wildcards: *, ?


? – replaces single character
* - several

title:ab* - finds Work Items having words 
starting with 'ab' in the title field
title:ab*c - finds Work Items having words 
in the title field starting with 'ab' and 
finishing with 'c'

The same with '?'
Lucene doesn't allow using wildcards as 
first character

Lucene expands all the wildcards to matching 
statements. Thus, if you type title:t*
it will be expanded by Lucene to: 
title:the OR title:test OR title:task OR... 

Polarion's default is 2048 clauses maximum 
in one Lucene query (Lucene's default is 1024).
Using too generic a wildcard may exceed this 
maximum number resulting in an error reported 
back to the user.
                            

Fuzzy/proximity search ~

Tilde (~) is used for a fuzzy/proximity search. You should seldom need to use it.

Range Searches { }, [ ]


[ ] – Specifies the range in dates or numbers, 
{ } – Will find all Documents whose titles 
      are between specified terms, exclusive.

Example:

created:[20120208 TO 20120222]

finds Work Items created between 
08 Feb 2012 and 22 Feb 2012

{ } Rarely needed, not recommended.
                            

Boosting a Term ^

^ is used for relevant searching. In most scenarios you don't need it with Polarion

Boolean Operations + - || && !

Lucene supports AND, "+", OR, NOT and "-" as Boolean operators(Note: Boolean operators must be ALL CAPS)

AND == &&
OR == ||
NOT == !
                                    

title:xxx AND severity:blocker finds Work Items where title contains 'xxx' and severity is set to 'blocker'. Similar syntax using OR.

title:xxx AND NOT severity:blocker finds elements with 'xxx' in title and with severity other than 'blocker'

+/- may be used for the explicit requirement of having the record found or excluded.

Grouping ()

Group statements using parentheses.

severity:(blocker OR critical) has the same result as severity:blocker OR severity:critical

Grouping also makes prioritization of constraints (as in mathematics):

severity:blocker AND (title:xxx OR title:yyy) will make the OR operation higher priority than comparing blocker severity with title:xxx.

Escaping with backslash (\)

When using any characters above in text search, use '\'. For example, title.1:\(1+1\)\:2 will search Work Items with the literal value '(1+1):2' in the "title" field.

Tokenization

Polarion supports two different tokenization algorithms. System property search.wordBoundaries can be used to select from them.

White Space Based

This is the default tokenization. However, it is not convenient for languages that do not use white space between words. The indexed text is split around white spaces, and from the remaining character sequences all leading and trailing non-alphanumeric characters (anything that is not a letter or number) are removed.

Note for Advanced Users

This splitting is done using a regular expression and java.lang.String.split(String). It is possible to configure a custom regular expression that should be used via the system property search.wordBoundaries.splitByPattern.

EXAMPLES

(Term for "title.1" field is always the same as the title itself.)

Table 2.25. White Space Tokenization Examples

Item TitleTerms for "title" fieldQueryResult (standard tokenization)

Mary had a little 'lamb'.

Mary, had, little, lamb

title:mary

found

title.1:mary

not found (title.1's term is "Mary had a little lamb")

title:mary*

found

title.1:mary*

found

SW_ngcb_simulation

SW_ngcb_simulation

title:SW

not found

title:ngcb

not found

title:SW_ngcb

not found

title:SW_ngcb*

found

title.1:SW_ngcb

not found (title.1's term is "SW_ngcb_simulation")

title.1:SW_ngcb*

found

WI-1234

WI-1234

title:WI

not found

title:1234

not found

title:WI-1234

found

Standard Tokenization

This method splits text into words according to the Unicode standard . To use this method of tokenization, use the system property search.wordBoundaries=standard.

EXAMPLES

(Term for "title.1" field is always the same as the title itself.)

Table 2.26. Standard Tokenization Examples

Item TitleTerms for "title" fieldQueryResult (standard tokenization)

Mary had a little lamb.

Mary, had, little, lamb

title:mary

found

title.1:mary

not found (not found (title.1's term is "Mary had a little lamb")

title:mary*

found

title.1:mary*

found

SW_ngcb_simulation

SW_ngcb_simulation

title:SW

not found

title:ngcb

not found

title:SW_ngcb

not found

title:SW_ngcb*

found

title.1:SW_ngcb

not found (title.1's term is "SW_ngcb_simulation")

title.1:SW_ngcb*

found

WI-1234

WI, 1234

title:WI

found

title:1234

found

title:WI-1234

found (matches titles containing "WI" or "1234")

Combining Text with Visual Queries

If you have used the visual elements of the Query Builder to create a query, you can optionally append free-form textual query syntax. When combining visual and textual query elements, there are a few points to keep in mind:

  • The free-form part of query is usually connected syntactically with the visual elements by the AND operator.

    For example, if you have 2 visual elements [Type:Requirement][Assignee:Me] (visual elements denoted here by square brackets), if you append text severity:must_have, your Query Builder line will look like [Type:Requirement][Assignee:Me] + severity:must_have, and will be treated by the query parser as: type:requirement AND assignee.id:$me AND severity:must_have.

  • Appending text to visual elements with the OR operator causes the leading visual elements to be treated syntactically as if they were surrounded by parentheses.

    For example, if you have 2 visual elements [aa:xx][bb:yy] (visual elements denoted here by square brackets), if you append text OR cc:zz, your Query Builder line will look like [aa:xx][bb:yy] + OR cc:zz, and will be treated by the query parser as: (aa:xx AND bb:yy) OR cc:zz.

  • If the Query Builder is cleared of all visual elements, you can start the free-form part of a query with an operator. However, AND and OR are ignored. Operator NOT at the beginning of a query is parsed as you would expect.

Editing an Opened Query

You may sometimes access the Work Items table via a link in an email or a shortcut containing a query, via a saved query. If the query you are opening was originally constructed with visual query elements, the visual elements appear in the Query Builder when you access the table via the link or shortcut, and you can subsequently edit the query by modifying the visual elements.

If the query you open contains any elements that cannot be parsed into visual elements, the elements which can be rendered visually are so rendered until an element that cannot be parsed into a visual element is encountered. The remaining elements are rendered as a text string. You can then modify the query any way you want, editing, adding or removing visual elements, and/or editing, removing, or modifying the text string.

Queries Using Special Index Functions

Polarion implements a number of special index functions and "query expander" variables, which can be referenced to simplify queries on complex objects... Documents or Test Records, for example. This section describes the main use cases and related special index functions.

Current-date Based Searching Using $today$

The Polarion query system provides a special $today$ constant that can be used in query strings to retrieve Work Items updated on the current date. This can be useful for creating shortcuts.

Allowed formats:

  • $today$: actual date

Modifiers can be used to shift the date to a specified time frame:

  • $today - SHIFT$: actual date minus time frame specified by SHIFT (see examples below)

  • $today + SHIFT$: actual date plus time frame specified by SHIFT

The SHIFT parameter can take the following form:

  • Nd: N days, where N is an integer value. For example, 14d represents a time frame of 14 days

  • Nw: N weeks

  • Nm: N months

  • Ny: N years

The following example searches for items created during the previous week:

created:[$today - 2w$ TO $today - 1w$]

Spaces between $today and SHIFT$ are ignored, so expressions like $today-3w$ will work.

Querying for Linked Work Items

There can sometimes be a need to query for Work Items that are linked by another Work Item according to the link role. You can formulate a query around the following elements:

  • linkedWorkItems

  • backlinkedWorkItems

Consider the following figure:

Figure 2.21. Linked Work Item Queries

Linked Work Item Queries

Linked Work Items Illustration

There are two Work Items having an ID of WI-10. These exist in different projects, and both have links to/from other Work Items (for the purposes of this example, it doesn't matter in which projects the linked items live). The following examples refer to the above figure.

Table 2.27. Queries for items that are linked BY a specified Work Item

QueryMatched Items

backlinkedWorkItems:WI-10

WI-1, WI-2, WI-5, WI-6

backlinkedWorkItems:ProjectA/WI-10

WI-1, WI-2

backlinkedWorkItems:depends_on=WI-10

WI-2, WI-6

backlinkedWorkItems:depends_on=ProjectA/WI-10

WI-2

Table 2.28. Queries for items that link TO a specified Work Item

QueryMatched Items

linkedWorkItems:WI-10

WI-3, WI-4, WI-7, WI-8

linkedWorkItems:ProjectA/WI-10

WI-3, WI-4

linkedWorkItems:depends_on=WI-10

WI-4, WI-8

linkedWorkItems:depends_on=ProjectA/WI-10

WI-4
Querying for Test Record Work Items

You can build queries to search for Work Items linked to a test record in a particular Test Run using the TEST_RECORDS element. This can be particularly useful when creating report pages. For example, a test manager might use it to query for what defects were part of some test results.

The element can take the following parameters:

Table 2.29. Parameters

ParameterDescriptionRequiredAttributes

test run

Identifier of the Test Run whose test records should be queried for linked Work Items. Format: project ID/Test Run ID

YES

N/A

test result

The kind of results to search for

NO

  • testResultId - identifier of a kind of result, e.g. "failed", "passed", "blocked"

  • @any - search for test records with any type of result

  • @null - search for test records with no result

  • * - search for all test records

executed by

Search for test records executed by some specified user(s)

NO

  • userId - the user ID of a user who executed the tests of the test record

  • * - search for all test records

when executed

Date or time interval when execution of the Test Run of a test record occurred

NO

  • yyyymmdd - search for test records executed on particular day

  • yyyymmdd TO yyyymmdd - search for test records executed in time interval

  • * - search for all test records

linked work item type

Type of Work Item linked to test records

NO

  • false (default value) - search for Test Cases linked to test records

  • true - search for Defects linked to test records

EXAMPLES:

Search for test cases executed in Initial System Verification Test: TEST_RECORDS:("drivepilot/Initial System Verification Test",@any)

Search for test cases planned for Initial System Verification Test, but not executed yet: TEST_RECORDS:("drivepilot/Initial System Verification Test",@null)

Search for test cases executed by mTest in last week in Full System Verification Test: TEST_RECORDS:("drivepilot/Full System Verification Test",@any,"mTest","$today-1w$ TO $today$")

Search for defects triggered by test failures in Initial System Verification Test: TEST_RECORDS:("drivepilot/Initial System Verification Test","failed",*,*,"true")

Querying for Documents

Use the document.id index field to query for a specific Document. You can use the outlineNumber index field to query for items contained in Documents according to their outline number.

Syntax: Syntax: document.id:"Space Name/Document Name"

Example: document.id:"Functional Requirements" searches for the named Document in the default space. Note that the _default space name should not be specified. You only need to specify it in the query parameter of wiki macros such as the {workitems} macro.

Example: document.id:"Requirements/Functional Specification" searches for a Document named Functional Specification in the Requirements space.

You can query for Outline numbers in Documents using the special index field outlineNumber. The Outline Number field can be sorted on this index field. Sort is by document.outlineNumber, and wildcards are supported. Examples:

All items in current scope with outline number on level 1.1: outlineNumber:1.1.*

Unresolved items with outline number on level 1.1 in Document named FunctionalSpec located in the Specification space: NOT HAS_VALUE:resolution AND document.id:Specification/Functional Specification AND outlineNumber:1.1*

When searching for content of a particular outline number, the document to search within can also be specified.

outlineNumber:("PROJECT/SPACE/ID", "2*")

When working within the "Document" scope (Using the filter in the document editor, the table or tree tabs), the document is automatically added to the query.

TIP

Specify a document whenever possible (in all places other than in the "Document" scope), otherwise the outline query will search through all the documents in the entire repository.

Note

"OutlineNumber" queries only work when the number of Work Items that contain matching outline numbers is not greater than the value of the "luceneMaxClauseCount" Polarion Property. (The default is set to 20 000.)

Querying for Approvals

Querying for items in a particular state with regard to approval has a special syntax - see the following examples.

Items awaiting approval by a specific user (user ID "rProject"): approvals:fullxxxapprovedxxxrProject

All items disapproved by anyone: approvals:fullxxxdisapprovedxxx*

All items awaiting approval by the current user: approvals:fullxxxwaitingxxx$[user.id]

TIP

In the Work Items table, create a query using the visual query builder, selecting the Approval field and setting the desired parameters. In the helper panel, click Copy to Clipboard to access the query including the special syntax.