2. User Reference

The User Reference provides information you may need to refer to when using various Polarion features - Documents, dialogs, Work Items, etc.

The user reference has the following main sections:

Dialogs, User Interface, Features

This section provides reference information on major dialogs, user interface and interactions, and miscellaneous features.

Activity Stream

This section documents the sources and types of Activities in the Activity Stream. You can filter the Activity Stream for activity source, or activity source and type by specifying a query with the following structure:

  • Activity source only: sourceId:[ID]

  • Activity source and type: sourceId:[ID] AND type:[TYPE-ID]

  • Activity source, multiple types: sourceId:[ID] AND (type:[TYPE-ID] OR type:[TYPE-ID])"

Table 2.1. Activity Source and Source Type IDs

Source IDType ID(s)Activity Source and Type



sourceId:administration, sourceId:administration AND type:changed


started, finished, finished_with_failures, failed, canceled

sourceId:builds, sourceId:builds AND type:finished, sourceId:builds AND type:failed



sourceId:commits, sourceId:commits AND type:changed


started, finished, failed, canceled, aborted

sourceId:jobs, sourceId:jobs AND type:started, sourceId:jobs AND type:failed


created, updated, status-changed, deleted

sourceId:testruns, sourceId:testruns AND type: created, sourceId:testruns AND type:updated AND type:status-changed


created, updated, deleted

sourceId:workitems, sourceId:workitems AND type:created, sourceId:workitems AND type:updated

Attachment File Types

This topic lists the supported attachment types searchable by their content and/or metadata. Generally every attachment is indexed by its file name, file extension, author ID, author name, update date and file size. The ones listed here are searchable by their content also unless otherwise noted. Attachments are only indexed (and therefor searchable) if the system property to enable indexing of attachments is enabled in the system configuration.

Archive/Package Formats

The contents of archive files is also parsed.

  • ar

  • bzip2

  • cpio

  • gzip

  • jar

  • pack200

  • tar

  • UNIX dump

  • xz

  • zip

Audio Formats

Only metadata is indexed.

  • Audio Interchange File (aiff, aif, aifc)

  • Basic Audio (au, snd)

  • MIDI (mid, midi)

  • Wave audio (wav)

eBook Formats

  • IBook (ibook)

  • Epub (epub)

Image Formats

Metadata is indexed.

  • Bitmap (bmp, dib)

  • Portable Network Graphics (png)

  • Graphics Interchange Format (gif)

  • JPEG (jpg, jpeg)

  • Windows Icon (ico)

  • Wireless Application Protocol Bitmap (wbmp)

Microsoft Formats

  • Microsoft Office:

    • Excel (xls, xlsx, xlsm, xltx, xltm)

    • Outlook (msg)

    • Powerpoint (ppt, pptx, pptm, ppsm, ppsx, ppam, potx)

    • Project (mpp)

    • Publisher (pub)

    • Visio (vsd)

    • Word (doc, docx, docm, dotx, dotm)

  • OLE Objects (only if Polarion is hosted on Windows Server platform)

OpenDocument File Formats

  • Documents:

    • Open-Document Chart (odc)

    • Open-Document Formula (odf)

    • Open-Document Graphic (odg)

    • Open-Document Image (odi)

    • Open-Document Master (odm)

    • Open-Document Presentation (odp)

    • Open-Document Spreadsheet (ods)

    • Open-Document Text (odt)

  • Templates:

    • Open-Document Chart Template (otc)

    • Open-Document Formula Template (otf)

    • Open-Document Graphic Template (otg)

    • Open-Document Web page Template(oth)

    • Open-Document Image Template (oti)

    • Open-Document Presentation Template (otp)

    • Open-Document Spreadsheet Template (ots)

    • Open-Document Text Template (ott)


You can add a caption to the following types of content in Polarion:

  • Images (in Documents, Work Items, table cells)

  • Tables (in Documents, Work Items)

  • Diagrams (in Documents, Work Items, table cells)

To add a caption, click on the item and click Add Caption on the pop-up menu. In the Add Caption dialog, you can:

  • Enter your caption text in the Caption field.

  • Select whether the caption should appear above or below the item by clicking the appropriate icon in Show At.

  • Select a label that describes the item type, or add a new label. The value set in this field is prefixed to the value in the Caption field.

Captions and "On-demand Work Item Loading"

  • With On-demand Work Item Loading turned ON, if the document "Work Item Presentation configuration" is set for Test Steps or Rich Text Custom Fields to be visible, all caption numbers appear as “#. They will be replaced with the correct numbers when exported.

  • If the document Work Item Presentation configuration does not contain Test Steps or Custom Fields as outlined above, then caption numbers will display, even with On-demand Work Item Loading turned ON.

    (Visible caption numbers will display correctly even if previous captions from the same sequence have not finished loading.)

  • With On-demand Work Item Loading turned OFF, all caption numbers will appear in the document but may take a while to load in very large documents.

Figure 2.1. Inserting a Caption

Inserting a Caption

Captions are available on these elements in Documents and Work Item rich-text fields

There are two default caption label values: Table and Figure. These values determine if a caption is included in a Table of Figures or a Table of Tables, if these are inserted into a Document.

User-defined Caption Labels

You can optionally add a new label and apply it when captioning images, diagrams or tables. For example, you might create a label "Citation" and specify it when adding a caption to some items. You could then insert a "Table of Citations" in your Document. Note that tables of figures, tables, and custom-labeled items appear only in documents generated by export to PDF and Round-trip for Microsoft Word. A placeholder appears in your Polarion Document.

A custom caption label appears in the Label list when the Document contains a caption that uses it. To remove a custom label, remove all captions that use it and refresh your browser.


This section provides reference information about several commonly used dialogs.

Create New Project Dialog

The Create New Project dialog presents several screens where you specify properties, template, and other details about a new project. These screens also appear when the dialog is invoked to mark and existing repository folder as a project.

See also: User Guide Creating a New Project From a Template.

Basics screen
  • ID: Specify a unique identifier for your new project. Characters are restricted to: a-z, A-Z, 0-8, underscore, dash, and period. No spaces.

  • Location: Specify the Repository folder to be the root of the new project. If this will be child of an existing folder, specify that folder. For example, to specify a new project folder under the existing Sandbox folder, you would enter Sandbox/MyNewProject/.

  • Icon: SVN Picker: Click to launch the SVN Picker dialog to pick an existing repository folder as parent of your new project's folder. Folder name selected will be appended in the Location field.

  • URL: Read-only field showing the full repository path to your new project's root folder. Field changes as you type in the Location field.

  • Tracker Prefix: Specify a short string to be used as a prefix to the IDs of new Work Items created in the project.

    Important Note

    This prefix should be unique to your Polarion system. If it is duplicated, then references to Work Item IDs in commit comments may cause the revision to be linked to the wrong item in the wrong project. For example, if two projects use the default prefix WI, there could be two Work Items in the system with WI-3 as the ID. Then if a developer references e.g. "WI-3" in a commit message in an external SVN client, the revision will be linked to the first Work Item found by the system having that ID, which may or may not be the right one.

Templates Screen

This screen enables you to choose a project template on which to base the new project. Project templates may provide any or all of various system configurations, workflow, repository folder structure, wiki content, Documents, Work Items, shortcuts, etc. all customized to support a particular type of project.

Only templates enabled by your system configuration and supported by your license appear in the Create New Project dialog. For a listing of the default project templates, see User Reference: Default Project Templates.

Summary Screen

This screen displays a read-only summary the details you have specified for the new project up to this point. You have the opportunity to make changes before the project is created in the system. Click the Previous button to go back and make any changes. When you are satisfied with the details, click the Next button to begin creating the new project.

Creation Screen

This screen displays a progress indicator while the project is being created, and an alert which the operation is finished. If any error occurred, it is reported here. When the screen reports Project created., click the Next button.

Details Screen
  • Name: The name of the project that appears to all users in the Open Project or Project Group dialog.

  • ID: The project's ID. Read-only.

  • Lead: Name of the project leader. Default value for a new project is the current user. You can select from a list of current users. If the user is not listed, you can safely skip this and specify it later in the project administration interface after the project leader's user account has been created in the system.

  • Active: Flags that this project is actively under development. Default for a new project is checked state. If the new project will be active later on, you can clear this option and check it later in the project's administration interface.

  • Start: The date on which work will begin (or began, if you have marked an existing code base as a Polarion project). Default value for a new project is the current date. Click the calendar icon to pick a date. If not known, it is safe to skip and specify a date later on in the project administration interface.

  • Finish: The date on which the project is scheduled to finish. Click the calendar icon to pick a date. If not known, it is safe to skip and specify a date later on in the project administration interface.

  • URL: The URL of the project's root in the repository. Read-only.

  • Description: Enter free-form text describing the project. This can be helpful to future new team members, managers, and other stakeholders.

Open Project or Project Group Dialog

Invoked from: Open Project or Project Group item on the project menu (click the name of the current project in Navigation).

This dialog enables you to access an information scope in which you want to do some work. From this dialog you can:

  • Access the current Repository to view dashboards, wiki and other information, or perform configurations in this scope.

  • Access any project group (in the current repository) to see dashboards, wiki and other information, or perform configurations in this scope.

  • Access a project to process Work Items, see dashboards, wiki and other information, or perform configurations in this scope.

Figure 2.2. Screenshot


Open Project or Project Group dialog (All Projects)

The left side of the dialog is a tabbed content browser comprised of the following items:

  • All Projects tab: Displays all the content in the current repository allowing selection of any project group or project to open.

    When a project is selected the Add to Favorites icon appears in the highlighted group or project name. Click it to add the selected project to the Favorites tab.

  • My Projects tab: Displays only those project groups and projects for which you have some role. Select any available content to open it.

    When a project is selected the Add to Favorites icon appears in the highlighted group or project name. Click it to add the selected project to the Favorites tab.

  • Switch Flat/Tree button: Appears to the right of the tab set and switches between hierarchical and flat presentation in the currently selected tab.

The right side of the dialog contains the following:

  • Information box: green box explains the icons used in the dialog

  • Actions: displays a list of available actions you can invoke. For example, if you have permissions to create a new project, the Create New Project link appears. If there are no actions available given your user permissions, the section does not appear in the dialog.

  • Switch Polarion Server: Appears only if your Polarion system has been configured to work with multiple repositories. Displays a list of links for the currently configured repositories. Click the name of the repository you want to access.

See also: User Guide: Accessing Projects.

Linked Work Items Dialog

Invoked from: Navigation > Documents and Pages >, selected Document, sidebar, Work Item Properties, Edit Links.

Figure 2.3. Linked Work Items Dialog

Linked Work Items Dialog

Manage the links of Work Items defined in online Documents


  • Suspect: Toggles the Suspect property of the link. For information, see User Guide, Linking Work Items: Suspect Links.

  • Role: The link role defining the relationship between the linked Work Items. (For information, see Administrator's Guide: Link Roles and Rules.) List contains the link roles currently configured for the project and which are applicable to the Work Item type as defined in link role rules in the project configuration.

  • Title: Displays the ID and Title of the linked Work Item. The string is a link that leads to the linked Work Item in the Table view of the Work Items topic. When adding a new link the edit field accepts the ID or outline number of the target Work Item. Use ID to link to Work Items that are not defined in the current Document. Outline number works only with Work Items defined in the current Document. The icon in this column leads to a picker dialog in which you can browse or use querying to locate the target Work Item for the link.

  • Project: Read-only. Displays the name of the project to which a linked Work Item belongs.

  • Revision: The repository revision of the target Work Item to which the source Work Item links. Normally, links will point to the Head revision of the item, but you have the option to link them to a specific revision number, either the current revision, or a specific revision which you explicitly select in the picker dialog.

  • Assignee: Read-only. Displays the name of the person(s) to which the linked Work Item is assigned. If no name appears, the linked item is currently unassigned.

  • Actions: Provides icons enabling you to remove existing links or add new links to the Work Item currently selected in a Document. The Remove icon is disabled when a link is structural in nature, derived from the element structure of the Document. For example, if a Work Item is a Heading 3 which is under a Heading 2 which is also marked as a Work Item, the two sections have a parent-child relationship which is tracked with a link using the appropriate link role. As this is inherent structure, the system maintains these structural links and does not allow users to explicitly remove them via link editing. If the two sections were merged into a single section, the link would be automatically removed.

Revision Picker Dialog

Invoked from the Table view of Work Items (Navigation > Work Items), Linked Revisions section, (Select Revision) icon .

Use this dialog to find and select a repository revision to link to the current Work Item, and enter the revision number in the current line of the item's Linked Revisions section. Please refer to the following figure:

Figure 2.4. Revision Picker and Revision Table Configuration Dialogs

Revision Picker and Revision Table Configuration Dialogs

Dialogs used to select a repository revision to link to a Work Item

The dialog presents a query bar and a table of revisions found by the current query. Click on the revision number in the table to select that revision as the link target and close the dialog.

Query Segments

The query bar has 3 controls that enable you to formulate 2 query segments:

Table 2.2. Query Segments and Values


Query scope

Pick List

  • All - All revisions, regardless of how created

  • Not by Polarion - Revisions not created by users using Polarion

Revisions may be created externally using a Subversion client.

Search target

Text box

Enter any text, or a field ID:value

You can use AND, OR and NOT operators to query for multiple things. For example, query for revisions containing some text in the commit message, and committed on a specified date.

User filter

Pick List

  • All - Revisions by all users

  • Created by me - Limit results to revisions created by you.

  • List of all user names - Select a user name to limit results to revisions created by that user

You can also query on the author field of the revision

Revision Fields

Polarion indexes several fields for repository revisions, enabling you to query for values in those fields. The following table lists these fields.

Table 2.3. Revision Fields and Descriptions

Field IDDescriptionNotes


This is actually the revision identifier, which is a number

Example: name:5874 or NOT name:87512


Text of the revision commit message

If all you want to find is some word or phrase in the commit message, you can skip entering this field name and just enter the text you want to find. You can combine search on this field with search on some other field. Example: Read only AND created:20090628

If you want to eliminate some word or words, then you need to reference the field. Example: message:Read AND NOT message:only


User ID (not name) of the Polarion user who created a revision

In many cases you would not need query on this field. Rather, you could select the user in the user filter segment.

In cases where you want to eliminate some user, or you want results from several users, then you would need to query on this field, selecting All in the user filter segment.

Examples: NOT author:jonesL, author:jonesL: OR author:smithM


The date when a revision was created

Specify date as: yyyymmdd. For example, for July 22, 2009 enter created:20090722


Flags whether or not a revision was committed internally using Polarion, or externally using a Subversion client.

This is a Boolean field, values true, false. Example: internalCommit:false


Identifier of the repository to which a commit was made.

Only viable if Polarion is configured to use external repositories. Example: repositoryName:myGitRepo

Table Configuration

You can configure which revision fields appear in the Revision Picker dialog, in what order, and their sorting order and direction. To invoke the Table Configuration dialog, right-click on the header bar of the revisions table (in the Revision Picker dialog), and on the menu choose More.

Import from Excel

This topic provides reference information that may be useful when importing Work Items defined in Microsoft Excel.

Supported Work Item Fields

Columns and data in Excel can be mapped to the following Work Item fields during import to Polarion. Please see following notes on mapping multivalued data to multivalued fields.

  • Assignee *

  • Author

  • Categories *

  • Comments

  • Custom fields *

  • Description

  • Due Date

  • Hyperlinks *

  • Initial Estimate

  • Linked Work Items *

  • Priority

  • Remaining Estimate

  • Resolution

  • Resolved On

  • Severity

  • Status

  • Time Spent

  • Title

NOTE: * character in the above list means the field supports import of multivalued data. Note that import of multivalued custom fields is supported for enumeration types only, not for primitive types, which can still be imported as single values.

Multivalued Data and Fields

It is possible to define multivalued data in Excel so that it can be mapped to multivalued fields in Polarion Work Items, and multiple values written to such fields during import. See User Guide topic: Importing Multivalued Data.

The following fields must be written in a special format using a specific pattern:

  • Linked Work Items: pattern: "[role:][project/]id". External linked items pattern is: "[role:]URL".

  • Hyperlinks: pattern: "[role:]URL"

Keyboard Shortcuts

This topic documents the default keyboard shortcuts available in Polarion.

Table 2.4. Basic Shortcuts


Focus Work Item query


Edit button on all forms


Save button in data entry forms


Select previous or next Work Item in Multi Edit view of the Work Items topic.

Shortcuts that focus fields on the form in the Work Item Editor

To focus the following fields, press CTRL+ALT+

  • A - Assignee

  • C - Comments

  • D - Description

  • E - Initial estimate while creating a new item, Remaining estimate otherwise

  • G - Categories

  • K,L - Linked Work Items

  • N - Time Spent

  • P - Time Point

  • R - Resolution

  • T - Title (edit mode only)

  • V - Severity

  • W - Status (workflow)

  • Y - Priority


It is possible to disable all keyboard shortcuts (also in Multi Edit) by setting the property disableKeyboardShortcuts=true in the system configuration file polarion.properties (follow link for location).

Document and Rich-text Editor Shortcuts

A comprehensive reference dialog, context-sensitive for your operating system, is available via the Keyboard Shortcuts item on the Help menu of the respective editors.

Figure 2.5. Keyboard Shortcuts - Document Editor

Keyboard Shortcuts - Document Editor

How to access Keyboard Shortcuts reference dialog in Documents and Rich-text fields.

Shortcuts for Tables

The following keyboard shortcuts are available in tables in the Work Item Editor (including a Test Steps table), and the Document Editor:

Table 2.5. Table Shortcuts


Move cursor to the next cell to the right, or if located in the last cell of a row, to the first cell of the next row. Content of the cell is selected.

If cursor is in the last cell of the last row, insert a new row locating the cursor in the first cell on the left.

Shift + TabTab

Move cursor to the previous cell to the right, of if located in the first cell of a row, to the last cell of the previous row. Content of the cell is selected.

Time Values

Values for time are always rendered in server's time zone, regardless of the time zone where the user is located. For example, if the server is located in the Eastern time zone of the United States, and a user who is located in the Central Europe time zone updates a Work Item, the time stamp of the update will be according to the server's time zone, not the user's time zone.