Common Operations with Work Items

This section covers several common things that people need to do with Work Items.

Assigning a Work Item

You assign a Work Item to a person using the Assignee field in the Work Item detail. This field presents a drop-down list of Polarion users (filtered according to permissions). You assign the selected Work Item (or Items, if performing a Bulk Edit) by selecting the user's name from the list. Note that the assignee must have an account on your Polarion system, and must be assigned the assignable role in order to appear in the Assignee list. (It can be easy to omit setting up accounts, or assigning roles for e.g. a domain expert who is not on the engineering team but who needs to be assigned a Requirement, for example.) For more information on roles, see Administrator's Guide: Configuring User Roles.

Assigning to Multiple Assignees

It is possible to assign the same Work Item to multiple people. For example, you might have a Work Item type "Meeting" which is scheduled, and for which you want to track time spent by all participants. You can accomplish this by assigning the item to multiple assignees.

The procedure is essentially the same as for assigning a single person. After you assign the first assignee, click the icon in the Assigneefield, and select another user name from the drop-down list.

When there are multiple assignees, each additional assignee has a icon beside the user name. If you need to remove an assignee, click this icon. The Assignee field cannot be left empty. To unassign the item completely, select the not selected value in the drop-down list of users in the Assignee field.

Any of the assignees who spend time on a Work Item with multiple assignees can create a Work Record to report time spent on it.

Changing a Work Item's Status

You can initiate a change of status for a selected Work Item directly in the Work Item editor (Table and other views) without entering Edit mode. The Status field has a drop-down list that displays a choice of actions as configured in the project workflow.

Selecting an action value in the Status field enables the Save and Cancel buttons in the Work Item editor toolbar. Depending on the workflow configuration, you may be able to view and/or edit other fields such as Resolution.

The Status drop-down shows only transitions permitted by the workflow configuration, based on the item's current status. For example, the workflow configuration might require an item with status "Open" to transition to a status "Verified" before the "Close" action appears in the Status field's drop-down allowing the item to transition to the "Closed" status.

Tip

Your project leader or administration should familiarize the team with the workflow configuration so that every understands the different Work Item statuses and the actions available in each status. In general, the workflow configuration maps the team's process and prevents steps from being skipped or bypassed.

(See also: Administrator's Guide: Configuring Work Item Workflow)

Prioritizing Work Items

The Priority field sets the priority of a Work Item for project planning purposes. Work Item priority is a float type numeric value. In products that have the LivePlan feature, the item's numeric value is used in conjunction with other factors by the LivePlan engine when calculating and rendering the project plan. In every case, it is possible to query for Work Items based on the Priority value, and to show the results of such queries in Wiki pages.

There is also a set of priority "ranks". These are simply named ranges of priority values. The names of the ranks and the range of numeric priority values is specified in the global and/or project configuration, and are customizable by an administrator. For example, you might have ranks named "High" and "Low" with numeric value ranges of 51-100 and 1-50, respectively. (For a listing of the default rank names and range values, see the Administrator's Guide topic Priority Ranks.) The Priority field displays the current Work Item's priority rank and numeric priority value.

The project workflow can be configured with an action that sets a default rank/value for new Work Items. This is useful when new items are created via import from Microsoft Office documents. For example, Priority of each new item might be set to "Medium", and that rank might be configured to have a minimum value of "50.0".

Setting Priority Value

At some point, the project team and/or leader needs to prioritize their work, which means reviewing Work Items and setting their Priority value. Priority can be set for a single item, or for many items at once. For a single item, simply change the value of the Priority field and save the change. Note that you can select one of the configured ranks, or set a numeric priority value. The latter is useful if you want to give some item a higher priority while keeping the same general rank. For example, if an item currently has priority set to "High", which is configured with a minimum numeric value of "70", you might assign the numeric value of "80". The item will then be given higher priority in the project plan by the LivePlan engine (and presumably by people processing their assigned items), but will still appear in results of queries for items with "High" priority.

For setting Priority for multiple items at once (in a Scrum planning meeting, for example), Polarion provides the Prioritization panel in the Table and Tree views of the Work Item Tracker (Navigation > Work Items).

Figure 6.29. Prioritization Panel

Prioritization Panel

The Prioritization panel in the Table view of Work Items

When you invoke the panel, the table enters a special "prioritization mode" in which the items in the table can be dragged and dropped to prioritize them. You can drag a single selected item, or a group of selected items (table rows in prioritization mode display drag "handles"). The table reflects priority with highest priority at the top. By reordering the position of items in the table top-to-bottom, you reorder the relative priority of all items in the table.

Tip

The set of items in the prioritization table is determined by the current query. Before invoking Prioritization, build and run a query to retrieve just the items you will be prioritizing.

Before reordering the items in the prioritization table it is advisable to run the Rescale All operation from the Pane Settings menu of the Prioritization panel (see User Reference: Prioritization Panel). This enables you to define the numeric range within which priority values will be assigned to the items in the table based on their position in the displayed set of Work Items.

Launching Prioritization Mode

To open the Prioritization panel and launch prioritization mode in the Work Items table:

  1. Open the Table view in the Work Item Tracker (Navigation > Work Items).

  2. Open the Prioritization panel using the icon on the Table view toolbar (see the figure above).

Note that you cannot open the Prioritization panel from a Document. You must use the Work Item Tracker. If you want to prioritize all the items contained in some Document, you will need to build and run a query that retrieves all the items in the Document.

Techniques for Setting Priority

You can use one or more of several techniques to set priority value for items in the prioritization table:

The following sections will discuss each of these techniques. The User Reference topic Prioritization Panel can help you understand the interface for each of the above techniques.

Assigning a Rank

You can assign one of the configured priority Ranks to items in the table using the Prioritization panel.

  1. Select the items you want to rank by checking the box on the respective rows of the table in prioritization mode.

  2. In the Prioritization panel, click the Rank selector and choose the desired rank from the drop-down menu.

  3. Click the Save button to apply the rank to the selected items.

If all selected items had the same priority value before you assign rank, the Priority field of all selected items will be set to the minimum value of the chosen rank. For example, if all items had a value of "50" and you assign a rank whose minimum value is "70", all the selected items will be set to "70". If the selected items had different priority values before you assign rank, they will all be set to the same value.

Setting a Numeric Value

You can set the same numeric value in the Priority field of multiple Work Items in a single operation. On save, the items will be repositioned in the table if the setting changes their priority relative to other items in the table.

  1. Select the items you want to set by checking the box on the respective rows of the table in prioritization mode.

  2. In the Prioritization panel, enter the desired numeric value in the Priority field and click OK.

    You can optionally select a different set of items and assign a number value to them in the same way.

  3. Click the Save button to apply all settings to all changed Work Items.

Reordering Priority With Buttons

The button set in the Prioritization table enables you to shift the position of one or more selected Work Items up or down one row in the table, or to the top or bottom position. (Keep in mind that in prioritization mode, top-to-bottom position in the table reflects highest-to-lowest priority.)

The button actions are as follows:

  • Up - acts as if you have dragged the selected items between the item preceding the topmost selected item and the item preceding that one.

  • Down - acts as if you have dragged the selected items between the item succeeding the bottommost selected item and the item following that one.

  • Top and Bottom - use the configured Priority Increment so that all the selected items are at the top or bottom (depending on which button is pressed), and there are increment-sized gaps between them.

Important

No operation (Up, Down, Top or Bottom) touches any other item unless the target point is between items with the same priority. In that case, the priority values of items above the target point are rescaled.

To change an item's priority using buttons in the Prioritization panel:

  1. Select the items for the operation in the table.

  2. Click the button for the desired operation (Top, Up, Down, or Bottom).

  3. Click the Save to apply the change.

Reordering Items Visually

In prioritization mode, Work Items in the table are listed by priority from top (highest priority) to bottom (lowest priority), unless all items have the same priority value, which is often the case with a set of newly created Work Items or items imported from Microsoft Word or Excel. You can re-prioritize the set of items by visually moving one or more selected items to a different position in the table using drag-and-drop.

It is important to understand that when you shift the position of some item(s), the relative priority of other items above or below the new position may be changed, and this will be reflected visually in the table (more items will become selected, and/or the rank colors of some items may change) and in the Range Selector of the Prioritization panel (the label may change).

If you shift the position of a selected group of items, the items in the group will keep the same priority relative to each other if they had different values to begin with. If they all had the same value, they will be rescaled within the scope of all items in the set being prioritized.

To prioritize items visually:

  1. Select the items you want to reorder in the table.

  2. Hover your pointer over the drag handle of any selected item, drag the selected item(s) to the desired position in the table, and drop the selection.

    You can optionally repeat this operation, selecting other items and moving them in the same way.

  3. Click the Save button to apply all changes.

Rescaling Selected Items

You can optionally rescale the relative priority of several selected Work Items to each other so that the priority values are more evenly distributed. You can optionally limit the rescale operation to one of the configured priority Ranks ("High", for example).

To rescale selected items:

  1. Select the items you want to rescale in the table.

  2. In the Prioritization panel, click the (Pane Settings) icon and choose Rescale Selected. The Rescale Selected dialog appears.

  3. Depending on the current priority of the items in the selection, the Top field or the Bottom field may appear. Top lets you specify the maximum priority value for items in the selection. Bottom lets you specify the minimum.

    Review the field value, if present, and change if desired.

  4. If you want all items in the selection to keep their current priority Rank, check the Keep Rank box. This will prevent, for example, items having a rank "Medium" from being rescaled to fall into a rank "High", or items having a rank "Low" from being rescaled into a rank "Lowest".

  5. Click the Rescale Selected button to close the dialog.

  6. In the Prioritization panel, click the Save button to apply the changes to all affected Work Items.

Rescaling All Items

You can optionally rescale the priority of all items in the Work Items table (when it is in prioritization mode). The set of items rescaled is determined by the current query. Be sure that your current query retrieves all the items you want to rescale. For example, suppose you want to scale all the Work Items contained in a requirements specification document. You would want to query for all Requirement type items contained by the Document before invoking the Rescale All operation.

The Rescale All operation is designed to result in a reasonably even distribution of priority values among all Work Items in a given set. You can specify the range of numeric priority values to be used. Scaling will result in an even distribution of values within the specified range.

It is highly recommended to run Rescale All on sets of new Work Items before beginning to prioritize them manually using any of the techniques previously described. For example, when a specification document is imported from Microsoft Word, all the Work Items in the resulting Polarion LiveDoc will often have the same priority value. (Import rules that set different priorities based on content in the original document could be defined for the import operation, but this is not always done by the person importing a document.) Having an even distribution of values to begin with can facilitate the re-prioritizing process.

To rescale all Work Items in the prioritization table:

  1. Be sure the current query has retrieved all the Work Items you want to rescale.

  2. In the Prioritization panel, click the (Pane Settings) icon and choose Rescale All. The Rescale All dialog appears.

  3. Optionally change the default values in the Top and Bottom fields to specify the scaling range.

  4. Click the Rescale All button to start the rescaling operation and close the dialog.

  5. In the Prioritization panel, click the Save button to apply the changed priority values to all Work Items.

Prioritizing on a Custom Field

By default, the prioritization feature uses the standard "Priority" field of Work Items (field ID priority), writing a value to that field. However, it is not necessary to prioritize items on that field. You can prioritize items on any existing custom field, subject to the following limitations:

  • The custom field must be of the same type as the default Priority field, i.e. float.

  • The custom field must be configured for all the types of Work Items listed in the prioritization table.

    For example, suppose the table contains both Requirements and Test Cases, and that Test Cases have been configured with a custom field "Test Priority", of float type. This field will not be available to select as the prioritization field because the Requirement type items do not have it. The table would have to contain only Test Cases in order to prioritize them on the custom field. This is easily done by building and running a query that retrieves only Test Cases.

To prioritize Work Items on a custom field:

  1. Open the Prioritization pane as described earlier.

  2. Run a query that retrieves only Work Items having the desired custom field.

  3. Optionally select a subset of the items in the table.

  4. In the Prioritization panel, click the Options (gear) icon and select Change Prioritization Field on the menu.

  5. In the Change Prioritization Field dialog, select the field on which to prioritize the items.

    Note that the dialog lists only those fields valid for all the items, and that the standard Priority field is always present in the list.

See also: Administrator's Guide: Configuring Custom Fields.

Adding Comments to a Work Item

Comments are an important tool for collaborating on Work Items. Comments can have multiple threads that discuss different topics related to the Work Item. When stakeholders reach consensus, individual comments and/or entire comment threads can be marked "Resolved" which hides them from view unless individual users opt to view them. In order to add comments and replies, or resolve comments, you must be assigned a role that grants these permissions.

To add comments to a Work Item:

  1. Select the Work Item in the Work Item browser pane.

  2. In the Work Item editor, click the Comments button to quickly scroll to the Comments section of the work item form.

  3. In the Comments section, click the Create Comment button.

  4. Enter a title for the comment thread and then type your comments in the multi-line text field and click the Save button.

Viewing Comments

The Comments section has several controls for adjusting the display of comments:

  • Collapse All button: Collapses the comments hiding the comment text so that only the header of each comment is visible.

  • Expand All button: Expands any collapsed comments so that the text of all comments is visible.

  • View list: Controls the way comments are indented. The Flat option indents all comments at the same level. In this mode, comment threads are not readily apparent. The Tree option indents comments according to comment threads, making it easier to follow any particular thread. You can individually collapse the top level of any threads you don't want to read.

Replying to a Specific Comment

Every comment has its own Reply control (), which creates a new child comment. Note that if a comment thread is collapsed, you see only the Reply control for the top-level comment, which may or may not be what you want to reply to. Expand any comment thread to see all comments and replies and to be able to access the Reply control for any comment in the thread.

Querying Comments by Author

A frequent user need it to find comments written by a particular user. This is possible by querying for the user ID of a comment author. The basic syntax of such a query is:

comments.author.id:USER_ID where USER_ID is the ID of the user whose comments you want to find.

By itself, such a query will probably return many results, so you would most likely use it as an element in a more detailed query. For example:

type:defect AND updated:[20120527 TO 20120528] AND comments.author.id:jSmith

The above query looks for Defect type Work Items, updated "today" (i.e. within the 24-hour period defined by the 2 date values), and having comments by user "jSmith".

Resolving Work Item Comments

When stakeholders reach consensus through comments and comment threads, it can be useful to mark the comments and/or comment threads as Resolved. This hides them, after which individual users can opt to view them. It is also possible to reopen resolved comments if a stakeholder decides that further discussion is needed.

Note

Work Item comments are distinct from Document comments. The latter are stored with Document data and can only be viewed in the Document Editor. Work Item comments are stored in the Comments field of Work Items. Approval Comments are Work Item comments, stored in the Comments field, but which pertain to, and constitute part of the audit trail for formal approvals.

See also: Resolving Approval Comments, Resolving Document Comments and Threads.

To mark comments or threads as Resolved:

  • In a Document, select the Work Item having the comment(s), open the Comments panel of the Document sidebar (Show Sidebar button on the Document Editor toolbar), locate the comment to mark, hover your pointer over it, and click Resolve.

    To mark an entire thread as resolved, hover over the first comment in the thread and mark is as above. (You cannot resolve individual child comments within a comment thread.)

  • In the Table or Tree view, select the Work Item having the comments. Then in the Comments section, locate the comment you wish to resolve and click the icon (Resolve this comment thread) on the comment header.

    To mark an entire thread as resolved, you must mark first comment in the thread. (You cannot resolve individual child comments within a comment thread.)

To view resolved comments:

  • In a Document, select the Work item having the comment(s), open the Comments panel of the Document sidebar, click the (Pane Settings) icon in the header, and choose Show Resolved Comments on the menu.

  • In the Tracker, select the Work item having the comment(s), scroll to the Comments section of the detail form, and check the box labeled Show resolved comments.

The header of resolved comments is light gray (as opposed to unresolved comments, the headers of which are light blue).

To reopen previously resolve comments:

  • In a Document, select the Work item having the comment(s), and open the Comments panel of the Document sidebar. Show resolved comments as described above. Locate the resolved comment you want to reopen, hover over it and click Reopen.

  • In the Tracker, select the Work item having the comment(s), scroll to the Comments section of the detail form, and check the option to show resolved comments. Locate the comment you want to reopen and click the (Reopen this comment thread) icon on the comment header.

TIP

Replying to any comment in a resolved thread reopens the entire thread.

Attaching Files to a Work Item

You can attach any type of file to a Work Item that will facilitate collaboration and/or implementation of the Work Item. For example, for a defect, you might attach a screen capture image showing the problem you encountered.

To attach a file to a Work Item:

  1. Select the item in some page Work Items view (Table, Road Map, etc.)

  2. In the Work Item editor, click the Attachments button to jump to the Attachments section of the detail.

  3. In the Attachments section, click the (Edit) icon in the section header.

  4. Optionally enter a meaningful title in the Title column... one that will help you and others understand what the nature of the attachment.

  5. Click the Choose File button in the File Name field. The file selection dialog for your operating system appears.

  6. Select the file in the file selection dialog. Its path appears in the File Name column the field.

  7. Click the Save button in the Work Item Editor toolbar to upload the file to the repository and attach it to the Work Item.

Note

You can update an existing attachment with a new file version by clicking Update Existing File in the Actions column, clicking Choose File, and selecting the new file on your local file system.

Your system or project administrator can optionally limit the file size of attachments. Contact your administrator if you are unable to upload an attachment due to such restriction.

Voting

If voting is enabled by the Polarion administrator you can cast a vote for a Work Item. When many people vote for an item, project managers may decide to increase the priority.

When voting is enabled, the Vote item appears in the drop-down menu of the Actions in the Work Item Viewer/Editor toolbar. To vote, just click the menu item.

Removing your vote

If you vote for a Work Item by mistake, or change your mind later, you can remove your vote. After you have voted for a Work Item, the Vote item no longer appears in the Actions menu. It is replaced by the Remove Vote item. Just click it to remove your vote.

Viewing Work Item History

You can see the complete change history of the currently selected Work Item using the History toggle button in the Work Item Viewer/Editor toolbar.

Setting and Removing Watches

A Watch is a background process that monitors changes to a Work Item and notifies any users who have been specified as Watchers when a change occurs. The Author (creator) of a Work Item and the assignee are always notified of changes without the need to explicitly set a Watch. The author and assignee of linked Work Items are also notified of changes.

Toggling a Personal Watch

You can add or remove yourself as a Watcher of any Work Item quickly and easily:

To add yourself as a Watcher:

  1. Navigate to the Work Item you want to watch and select it in the Table view.

  2. In the Work Item editor toolbar, click the Actions button and select Watch in the drop-down menu.

To remove yourself as a Watcher:

  1. Navigate to a Work Item you are currently watching and select it in the Work Items table.

  2. In the Work Item editor toolbar, click theActions button and choose Stop Watching.

Viewing Your Watches

You can see a summary of all items to which you are assigned as a watcher. For server performance reasons, this information is only provided on demand.

To review your Watches:

  1. Open your user profile (link on the My Polarion page or the tool view of Navigation).

  2. In your user profile page, click the Watches button.

A listing of items to which you are assigned as Watcher is displayed in the Table view of the Work Items topic.

Adding and Removing Watchers

For any Work Item to which you have write access, you can add other users as Watchers of the item.

To add another user as a Watcher:

  1. Navigate to the Work Item you want someone to watch and select it in the Table view.

  2. In the Work Item's detail pane, scroll downward so you can see the Watchers section.

  3. Click the Edit button in the lower left corner of the Watchers section.

  4. Select a user name in the User list and click the Save button.

Setting Planning Constraints

The Planning constraint field enables you to specify when work on the item should start or end. The date you specify is calculated in the Live Plan.

The following constraints can be set in the Planning Constraints list:

  • Start no earlier than: When selected, the Live Plan engine will not plan the item to being before the specified date.

    Start: When selected, the Live Plan engine will plan the item to being on the specified date.

    End: When selected, the Live Plan engine will plan the item to finish on the specified date. Start date will be calculated taking into consideration various factors including values set in Initial Estimate and Remaining Estimate fields, and planning data for linked items with dependencies.

This field, if used, usually has its value set during the project planning phase. For additional information, see Polarion for Project Managers: Project Planning.

Printing Work Items

You can print a listing of one or multiple selected Work Items to any printer to which your computer has access. You can select a single Work Item for printing in the Table, Live Plan, or Road Map views. You can also select multiple Work Items for print in the Table view. Alternatively, you can formulate a query to retrieve exactly the item(s) you want to print. You can print multiple items and their structure in the Multi Edit view.

To print Work Items:

  1. Select the Work Item(s) you want to print in the appropriate Work Item view, or formulate a query to retrieve just the item(s) you want to print.

  2. Locate the Operations button in the toolbar and click it to drop down a menu.

  3. Choose Print in the menu.

  4. Your system print dialog appears. Choose the target printer in this dialog, set desired print job properties if your print dialog provides this functionality, and launch the print job.

Multi Edit View

When the Links column is shown in the table of items, it is not printed at the position it occurs in the table, but rather last so that it can be higher to have more space to show the links.

Important

When printing the Multi Edit view in outline mode, the browser option print background must be enabled in order for the outline structure to show in the printed output.

Clipboard Operations

You can quickly copy the following Work Item data to your computer's Clipboard:

  • Work Item ID (Copy ID)

  • Work Item ID + Title (Copy ID + Title)

  • Work Item URL (Copy Link)

When you hover your pointer over a Work Item title in the Work Item viewer/editor, an icon and a drop-down control appear to the right of the Work Item title. When you click the drop-down control, a menu displaying the above options appears.

Browser Settings for Clipboard Access

Network and/or browser security configuration may disallow Clipboard access by applications such as the Polarion portal and prevent you from using this feature. The following sections provide some information about settings you can change in different browsers to make clipboard operations smoother with Polarion.

Microsoft Internet Explorer

The relevant option can be found in Internet Options > Security > Custom level, in section labeled Scripting. The specific option is Allow programmatic clipboard access.

  • If set to Prompt, Internet Explorer will ask whether to allow clipboard access. This will occur only once per session.

  • If set to Enable, clipboard access will always be allowed without any prompt.

Mozilla Firefox

By default, the security settings do not allow web applications and scripts to write data to the clipboard directly - the user must explicitly invoke copying to the clipboard. Therefore, when you invoke Cut or Copy actions when using Polarion in Firefox, Polarion presents a dialog containing your selected data and information on how to complete the operation and write the data to your clipboard.

TIP

The AllowClipboardHelper extension was recommended for clipboard support in some Polarion versions. It it is no longer needed by Polarion and if you have installed it to Firefox, you can remove it if you do not need it for other applications.

Google Chrome

The Chrome browser currently does not allow direct clipboard access by applications, and there is currently no option to change its configuration to allow it. The user must explicitly invoke copying to the clipboard. Therefore, when you invoke Cut or Copy actions when using Polarion in Chrome, Polarion presents a dialog containing your selected data and information on how to complete the operation and write the data to your clipboard.

Note that the same dialog may be presented for Internet Explorer and Firefox users if permissions settings block direct clipboard access by Polarion.