Creating and Editing Work Items

This section provides a quick overview on how to create a new Work Item and how to edit an existing Work Item.

(See Duplicate to copy an existing Work Item from the Work Item tracker or a document.)

You can only create new Work Items if the relevant permissions are granted to your user profile. In particular, note that:

If you find you cannot create a new Work Item, contact the administrator of your project or system and review your permissions.

Creating New Work Items

Work Items can be created in the system in two ways:

  • Manually in the tracker

  • Mark content in a Live Document

This section discusses manual creation in the tracker. For information about creating Work Items from content in Live Documents, see the User Guide topic Working with Documents: Work Items in Documents.

To create a new Work Item in the tracker:

  1. Open the project where you want to create a new Work Item. (See User Guide: Accessing Projects.)

  2. In the Navigation pane, click the Work Items topic.

  3. In the Work Items page, select the Table view. A table of the currently existing Work Items in the project appears in the upper half of the page.

  4. Click the icon menu button, and select the type of Work Item you want to create from the drop-down menu. (Alternatively, you might use one of the Quick Work Item icons.) A new Work Item form appears in the Work Item viewer/editor, ready to edit.

  5. Fill in the fields that are relevant for the new Work Item. Be sure to fill all required fields (marked with an asterisk). Keep in mind that some fields may be hidden if the button is clicked.

  6. When all required fields have been filled, the Create button is enabled. When you have filled all fields and added any watchers, attachments, etc. click the Create button to create the new Work Item. Note that the new item does not automatically appear in the Work Items table. Assuming the current search query would retrieve it, you need to click the Search button in the table toolbar to refresh the listing and show the new Work Item.

Using the Quick Work Item Icons

One or more "Quick Work Item" icons appear to the left of the Create () icon. These represent the first Work Item types defined in your system configuration - the same order that appears under the Work Items topic. Click one of the icons to create a new Work Item of the respective type.


It is also possible to create a new Work Item using the Actions menu button (Gear icon) in the Work Item Viewer/Editor pane. Its menu contains special items for creating a new Work Item and linking it to some other existing one at the same time. For more information see Work Item Basics: Actions.

Creating New Work Items in Excel

New Work Items can be created in Microsoft Excel in an Excel document that has been exported from Polarion (see User Guide: Exporting Work Items: Using Excel Round-trip).

Create a Work Item in the Browser Address Bar

You can also create a new Work Item by adding workitem?form_mode=create to your URL address. The Work Item type and any string field can also be added to the address and their values will be autofilled when the new Work Item appears. All other fields must be entered manually.


Editing Work Items

In order to edit Work Items, you must be granted permission to modify Work Items by the project administrator in the project's permissions configuration. Even if you have this permission, you still may not be able to edit some Work Item fields if the permissions configuration denies you the permission to modify some specific field(s). Such fields appear in the Work Item editor, but are read-only. For more information, see the Administrator's Guide topic Configuring User Permissions.

You can edit existing Work Items either singly or several at a time using (Bulk Edit). The latter is useful for such tasks as assigning multiple Work Items to the same person, or setting the same status, priority, or start/end date for several items.

To edit a single Work Item, select it in Table, Road Map or Live Plan view, wait for the detail to load, and then click the Edit button in the Work Item Viewer/Editor toolbar. Note that this button appears only if you have edit permissions.

Work Item Detail Level

A Work Item can contain a lot of data fields. You can minimize the level of details displayed using the button on the Work Item toolbar.

When the button is clicked, the detail level is mimimized in the Work Item Viewer/Editor.

(Which fields are displayed or hidden can be defined by an administrator in the "Form Filters" section of "Form Configuration".)

Click the button again to deactivate it and view all the available details.

Polarion will remember your preference and display all other Work Items with the same detail level.

Filtering Lists and Menus

The Work Item Editor contains various fields with drop-down menus or lists from which users can select a value for the field. In come cases, the list of items can be quite long, even to the point of slowing page response while the list of items is populated. Long lists can also be difficult to browse. You can alleviate both these cases by filtering the list or combo box.

List filtering occurs as you type. After clicking the drop-down control, simply start typing the first few characters of the value you are looking for. The first character typed focuses the first item that begins with that character. The second typed character begins filtering the list incrementally as you type, eliminating from the list the items that do not match at all.


List filtering works not only in the Work Item Editor, but for all drop-down list/combo boxes everywhere in Polarion including dialogs. The default number of items loaded to lists is configurable by an administrator.

Using Bulk Edit for Multiple Work Items

The Bulk Edit feature enables you to select multiple Work Items and edit, move, or delete them as a unit. When you save editing changes, values of modified fields are applied to all selected Work Items.

The set of Work Items available for editing varies according to the current Search query. You can use Shortcuts, or saved or custom Search queries to isolate or narrow the subset of Work Items you want to edit all at once.

Bulk Edit is available in the following views in the Work Items topic:

To select and edit multiple Work Items:

  1. Make sure you are working in the correct Project, and in the Work Items topic in that project.

  2. Select any Work Item view in which Bulk Edit is available, as mentioned above. A listing of Work Items appears in the upper pane. The Work Items that appear listed are retrieved by the current Search query.

  3. Use the Query Builder to run a query the result of which contains all the Work Items you want to edit. This is not absolutely necessary, as you can select individual items in the listing, but having only the items you want to edit listed can speed up the selection process because you can select all the items in the table with a single click on the check box in the Select column header.

  4. A check box appears to the left of the ID of all the Work Items listed. Check this box for each Work Item you want to edit. If you have run a Search that fetched all the items you want to edit, you can quickly select all items listed by checking the box the appears in the header of the check box column.

  5. Go to the Work Item Viewer/Editor (lower half of the Content Pane in the Work Items topic) to edit and change field values as desired. (Some fields cannot be edited using Bulk Edit and will be disabled. They will have to be changed individually.)

  6. Click Save and Suspect or Save to save your changes and apply them to all the selected Work Items.

Bulk Editing a Large Number of Work Items

The maximum number of Work Items that can be edited using normal Bulk Edit is set in the system configuration. If more than the number set by the limit are selected, "Restricted" Bulk Edit is activated, a panel of options appears, and the word "Restricted" appears on the Bulk Edit button, which leads to a limited view in which you can edit field values, but the current values are not loaded in order to optimize server performance for all users. .

Figure 6.17. Restricted Bulk Edit

Restricted Bulk Edit
Bulk Edit: Disabled Fields

The following fields cannot be editing while using Bulk Edit:

  • Rich text fields, for example the "Description" field.

  • All fields that contain multiple lines.


The number of Work Items you can modify via Bulk Edit is practically unlimited. Keep in mind that changing a large number of Work Items places an unusual processing load on the server and also will result in large numbers of email notifications, with the resulting load on the SMTP server and the network.

Editing the Description Field

The Description field is a special field type that supports basic text formatting, images, tables, and hyperlinks. When you edit the field, a toolbar displays above the text field and provides access to the formatting and other features. The Description field is editable when the Work Item is in Edit mode. If the Work Item is not in Edit mode, you can edit just theDescription by clicking the Edit button.

Figure 6.18. Editing Description Field

Editing Description Field

Features of the Description field

Formatting Text

The following text formatting features are available in the Description field:

  • Bold font

  • Italic font

  • Underlined font

  • Strike-thru font

  • Superscript font

  • Subscript font

  • Text Color

  • Background Color

  • Font family

  • Font size

  • Remove formatting

  • Convert to Plain Text

  • Numbered list (ordered list)

  • Bullet list (unordered list)

  • Outdent text

  • Indent text

  • Left-aligned text

  • Centered text

  • Right-aligned text

Text formatting features work in that same way as most word processors. For example, you can select some text and apply some formatting to just the selected text. Or you can position the caret and select formatting, and everything that comes after has the specified formatting until you change it. The toolbar also provides the Remove Formatting of Selected Text button, which removes all formatting from selected text.

Notes on Text Formatting:

  • It is possible to configure Custom Fields with the same rich-text features as the Description field. For information, see Administrator's Guide: Customizing Work Items: Configuring Custom Fields: Implementing Rich-text Custom Fields

  • Available fonts can be configured by an administrator.

  • Background color is only available for text. Background color of table cells cannot currently be formatted. Most browsers do not print text background color by default. If such printing is desired, it will probably be necessary to change the browser's print options or settings.

Using Keyboard Shortcuts

Keyboard shortcuts in the Description field (and other rich-text type fields) are similar to those of applications such as Microsoft Word and Google Documents. 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 6.19. Keyboard Shortcuts - Work Items

Keyboard Shortcuts - Work Items

How to access Keyboard Shortcuts reference dialog in Work Items

Inserting Images or Attachment Previews

You can display images or attachment previews in the Description field of Work Items. (Or any other field of the Rich Text type). When you are focused on this field, the text formatting toolbar appears in the Work Item Editor toolbar. It contains a button that enables you to select an image or attachment file and insert it in the Work Item description. See here for details.

After inserting an image or attachment preview, you can add a Caption above or below it, or Resize it, or launch a full screen Preview of it.

Figure 6.20. Image or Attachment Preview in a Work Item Description

Image or Attachment Preview in a Work Item Description

You can insert an image or an attachment preview a Work Item's Description or Rich Text fields.

Pasting Images from Clipboard

With some limitations (see Note below) you can paste an image from your clipboard into a rich text field. If there is a mixture of images and text in the clipboard, then only the name of the image file is pasted, and not the image itself. When you past an image, an attachment is automatically created with file name screenshot-[timestamp].png, where [timestamp] is the date-time when the image was pasted. Supported image formats are: BMP, JPG, PNG, and GIF.

To paste an image from your clipboard, simply locate the insert point where you want to image to appear in the rich text field and use your browser's Paste keyboard shortcut or menu command.


Quality of the pasted image can vary depending on whether you copy the image from your file system, a web browser, a photo viewer, or image management program, as well as which supported browser you are using.

Inserting and Formatting Tables

When the Description field is in Edit mode, the Table button in provides a menu with options for inserting and managing a table in the field. If the caret is not currently placed in a table only the Insert > Table command is available. All other commands are available when the caret is inside a table. When a table exists, you can:

  • Insert columns and rows

  • Move columns and rows

  • Merge and unmerge cells

  • Delete columns, rows, or the entire table

  • Access table properties

  • Add a caption above or below it. For more information, see User Reference topic Captions.

To insert a table:

  1. Make sure the field is in Edit mode and place the caret on a new line.

  2. Click the Table button and choose Insert > Table on the menu. The Insert Table dialog appears.

    Figure 6.21. Insert Table

    Insert Table

    This dialog is also accessible from Table Properties menu

  3. In the dialog, set the properties for the new table as desired. (You can modify them later using the Table Properties command on the menu.) Most of the properties are self-explanatory.

    The Bold Columns property enables you to reformat one or more columns to use bold font. For example, if you want bold text in the first column, enter 1 in this property.

    The No Page Break property, when checked, prevents a page break from occurring in the table when the Work Item is exported to PDF or for Word Round-trip.

After inserting a table, click inside any cell to enter text. All of the Description field's text formatting options are available for text in table cells. You can also insert images in cells in the same way as described in Inserting Images.

Table columns are self-sizing. You will notice some variation as you enter content in cells. Just enter your content in the cells, and the end result should look OK. If necessary you can increase or decrease the width of the table in the Table Properties.

Once inserted the following actions are supported:

  • Copy Rows or Cut Rows

  • Paste Rows to the same or another table. Pasted rows insert above the current row. If pasted rows contain more columns than the target table, columns are added to the target table on the right.

  • Merge or Unmerge cells.

    (Hold CTRL, select the cells that you want to merge, right click and select Merge.)

    To unmerge previously merged cells, click on a merged cell, right-click and select Unmerge.

    Merge / Unmerge in 'Description' based Test Cases

    Description field based Test Cases that use a table in the Description field as the source for the test execution extension are affected by the merge command. If you Merge the cells of a test execution table, the test execution extension will not work. Avoid merging cells in description based Test Cases.

    Compare Historical Changes after using Merge

    See Comparing table changes when cells have been merged for details on comparing historical changes and how merging tables affects it.

Inserting Hyperlinks

You can insert hyperlinks in the Description field of Work Items using the Insert Link button on the Work Item editor toolbar when the Work Item is in Edit mode. Links are local to the Work Item. That is, you can only create links to things that are linked to the Work Item:

  • Work Items appearing in the Linked Work Items section

  • Revisions appearing in the Linked Revisions section

Depending on the configuration of, and current selection in the interface list (in the Tool view of Navigation), these resources may not appear in the Work Item form for some users. Placing a hyperlink in the description provides exposure in the Work Item Description (always visible) of potentially hidden linked resources.

Figure 6.22. Insert Hyperlinks in Work Item

Insert Hyperlinks in Work Item

Inserting hyperlinks in the Work Item description to resource linked to the Work Item

Inserting a Diagram

Polarion provides the Diagram Editor tool for creating and editing diagrams. You can use it to create and edit diagrams in the Description field of Work Items in the Table view of the Work Items Tracker, or any Rich Text custom field.

For information on using this feature, please see the User Reference topic Diagram Editor.

Using Multi Edit

The Multi Edit view of the Work Items topic also enables you to edit multiple Work Items, but the functionality differs from Bulk Edit. With Bulk Edit, you have a single editor pane and changes are applied to multiple Work Items. With Multi Edit, all Work Items accessed by the current system query are editable in a single editor space in the Content Pane. You edit a single Work Item at a time, but all items are editable and changes to multiple items can be saved all at once.