This section provides and introduction to the basics of handling Work Items in Polarion.
A Work Item is the Polarion term for an artifact of the development process that is waiting to be implemented, is in progress, or has been implemented. The default types of Work Items are:
Requirement
Task
Change Request
Defect
Work Item types can be customized. The default types can be modified and/or new types can be defined by an Administrator both globally, and for each project. For more information, see Configuring Enumerations in the Administrator's Guide.
Using the respective data fields for the purpose, a Work Item can be assigned to someone, and incorporated into Project planning and tracking..
Every Work Item is part of a Project, and is planned and tracked with the Project. If a Work Item has dependencies with another project, it is possible to show this using the Work Item Linking feature.
You can browse the Work Items in the current project in different Views (tabs) in the Work Zone: Table, Tree, Live Plan, Matrix, etc. Some Views are mainly just listings while others show relationships to time (Live Plan) or other Work Items (Tree, Matrix).
To browse Work Items, select the Project in the PROJECTS portlet (in the Projects perspective), the Work Items topic in the Topics portlet, then select the tab for the desired view in the Work Zone.
When you select a Work Item, its detail data appears in the lower half of the Work Zone, and various portlets in that pane display information about the Work Item such as priority, status, who it's assigned to, when it is (or was) started, when it will be (or was) completed, etc.
When browsing, you can sort the Work Items displayed in the Table view of the Work Zone by clicking on the column header of the data column you want to sort by. For example, click the header of the Status column to sort the items in the table according to the current status of the Work Items. By default, Work Items are sorted on ID.
You can customize the table of Work Items that appears in the Table, Tree, Live Plan, and Road Map views when working in the Projects perspective. To quickly show or hide columns for the current session, right-click on any column name. A pop-up menu appears listing all currently configured columns. Columns currently visible show a check mark. Click on a column name in this menu to change its visibility for the current session.
You can create a more robust column customization for Work Item views and save it so that in future sessions the table appears with the columns you want. The Table Configuration dialog enables you to specify the columns that appear in views, the order in which they appear, the width of each column, which column should be used to sort the view, and the type of sort (ascending or descending).
To access the Table Configuration dialog:
Right-click on any column name in one of the views that have columns of Work Item fields.
On the pop-up menu, choose . The Table Configuration dialog appears.
By default, the Table Configuration dialog displays the current table configuration as defined in the system configuration. The Title column displays Work Item fields. (For information on the default Work Item fields, see Polarion Reference, Administration Reference, Standard Work Item Fields). You can show or hide columns, specify their default width (in pixels), and how the Work Items table in Work Item views should be sorted - on which column(s), and whether ascending or descending order for each specified column.
To save changes, click the button. This saves the changes to your user profile - other users will not be affected. If you have administration rights for the current project the button appears. If you click it, your changes to the table configuration will appear for all project users.
Reconfiguring the table globally for all users of the Polarion ALM system is possible in the Administration perspective. For information, see Administrators Guide : Configuring Work Items : Configuring Table View.
In the Table Configuration dialog:
Visibility: To show a column in Work Item views, check the box beside its name in the Title column of the dialog. To hide it, clear the check box. Hidden (unchecked) columns appear listed alphabetically by Title below the last shown column.
Display order:Columns are displayed top-to-bottom in the order they appear left-to-right in Work Item views. use the and buttons to change the display order of the columns.
Custom Columns: You can add a custom-named column to the views. This column will not represent any field, but can be included in sorting. Enter an ID in the Custom ID field and click the button beside it. This adds the field to the list. You can then select it there and set its column width, sorting, etc.
Column widths: To specify the default column width, select the column's row in the list of columns, and enter an integer number in the Width field. The number represents pixels.
Sorting Type: You can set the sort type of any column by selecting it in the list of columns ad setting the value in the Sort Direction field. Sorting can be either Ascending or Descending.
If the column is not yet included in the sort order, changing the value in this field adds the column to the sort order.
Sort Order: You can have Work Item views sorted on one or more columns. To include a column in the sort, set the Sort Direction field to
AscendingorDescending. Once a column is included in the sort, it's position in the sort order appears as an integer in the Sort Order field. You can use this field to select a different position in the sort order, or set no sorting on the column.
In many development teams, the same person will "wear a different hat" at different times. He/she may sometimes wear a "manager hat", and other times a "developer hat" or a "tester hat". In these different work contexts, it can be useful to have ready access to the most needed information and functions, and having the rest out of the way temporarily. That is exactly where the "My Hats" feature comes in. You can "put on" different "hats" at different times, and the user interface adjusts itself to better support the work context for the current "Hat".
The My Hats combo box appears in the portal header beside your user name when you are logged in. When you first log in the "Default" hat is active and you have access to all topics and Work Item fields. The Work Items combo box provides 3 other "Hats" that you can "wear" at different times as needed:
Developer
Manager
Requirement Engineer
Each "Hat" presents a different set of topics in the Topics portlet. In addition, Work Item form layout and workflow may be different. This is controlled by the My Hats configuration which can be customized by an administrator to change the name and/or topics, form layouts, and workflow for any existing "Hat", and define new "Hats". For information, see Administrator's Guide: Configuring My Hats.
Another feature of "My Hats" is the possibility to toggle "lite" user interface (UI) on and off. Currently, Lite UI affects only the Work Item form. When engaged, the form shows only a subset of all possible Work Item fields- i.e, you work with a "Lite" (lightweight) version of the form which contains only the most needed fields. The actual fields on the Lite form are defined in the My Hats configuration and are customizable by an administrator.
To enable Lite UI:
Click the drop-down control of the "My Hats" combo box in the portal header.
Click on . When the item shows a check mark, Lite UI is enabled.
Once Lite UI is enabled, you can engage and disengage it for the Work Item form.
To engage or disengage Lite UI for the Work Item form:
Click the Lite UI toggle bar of the Work Item form.
When Lite UI is engaged, the toggle bar indicates that the lite Work Item form is now being used and that some fields are hidden. To restore the normal Work Item form for access to all fields, click the toggle bar again.
Polarion ALM provides robust query-based searching. Every View and every data display is actually the result of some underlying query. There are a number of predefined queries that you can use to quickly locate and isolate a subset of all the Work Items in a Project or the entire repository (depending on the scope selected in the PROJECTS portlet. These are saved as Shortcuts, which appear in the Shortcuts portlet (main Navigation panel). Shortcuts are unique in that they are a combination of a View and a query. For example, a Shortcut might access a set of Work Items and show them in the Tree view. You can create your own Search queries and save them as Shortcuts.
Each View tab in the Working displays a Search bar that you can use to create Search queries to locate the Work Items you want to see. An example is shown in the following figure:
Search queries can range from simple to complex depending on what subset of Work Items you want to find. If you need something that is not provided by the default Views and Shortcuts, you can create a custom Search query using the Query Builder feature which enables you to build complex queries visually.
You can access the Query Builder from the and field of the Search bar. Drop down the list and select the item in the list.
Polarion's query language is the same as that of Apache Lucene (http://lucene.apache.org/java/docs/queryparsersyntax.html, which has some unexpected properties:
Operators must be typed in upper case:
AND,OR,NOT.Terms cannot start with an asterisk (*). For example,
something*is a valid query, but*somethingis not.Expressions cannot begin with
NOT. For example,NOT somethingis invalid, butsomething AND NOT something elseis valid. Something inside brackets is also an expression, sosomething AND (NOT something)is also invalid.When querying with NOT, it is possible to specify
ALL:ALL_VALUE in something. For example, if you wanted to query for Work Items to be auto-assigned, you can formulate the query this way:ALL:ALL_VALUE AND NOT categories.id:######NULL AND assignee.id:######NULL AND NOT author.id:######NULL
In the Work Items table, you can edit the query that appears in the and parameter field of the search expression. Click the drop-down button in the field and choose . You can then manually modify the current query, or enter a new query.
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.
The Polarion ALM 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,14drepresents a time frame of 14 daysNw" N weeksNm: N monthsNy: 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.
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:
linkedWorkItemsbacklinkedWorkItems
Consider the following figure:
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.
Queries are what fetches the Work Items that display in the Work Item tables and other views. Useful queries can be saved and reused in several ways. As mentioned in Shortcuts, your most commonly reused queries can be saved as Shortcuts to make them accessible from the Shortcuts portlet. But you can store and share other queries which are accessible from the Search bar's and field. Queries can be global in scope or limited to the scope of one Project or even just yourself as a user.
This section provides a quick overview on how to create a new Work Item and how to edit an existing Work Item.
Work Items can be created in the system in two ways:
Manually
Using Live Documents
This section discusses manual creation. For information about Live Documents see Working with Live Documents.
To create a new Work Item
Make sure you are working in the Projects perspective, and have selected the Project the new Work Item should belong to in the Projects portlet.
In the Topics portlet, click the
Work Itemsnode.In the Work Zone, select the Table view. A table of the currently existing Work Items in this Project appears in the upper half of the Work Zone.
In the Work Zone, click the Create action 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 Editor, ready to edit.
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 Work Item filter is toggled on.
When all required fields have been filled, the button is enabled. When you have filled all fields and added any watchers, attachments, etc. click the 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 button in the table toolbar to refresh the listing and show the new work item.
Three "Quick Work Item" icons appear to the left of the button in views where you can create new Work Items. These represent the first thee Work Item types defined in your system configuration - the same order that appears under the Work Items topic. Click one of the items to initiate creation of a new Work Item of the respective Type.
Tip
It is also possible to create a new Work Item using the button in the Work Item Viewer/Editor. Its menu contains special items for creating a new Work Item and linking it to an existing Work Item at the same time. For more information see Work Item Basics: Actions.
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, Tree, or Live Plan view, wait for the detail to load, and then click the button in the Work Item Viewer/Editor toolbar. Note that this button appears only if you have edit permissions.
A Work Item generally has quite a few data fields. If you don't always need to see all of them all of the time, you can activate the field filtering feature. To activate or deactivate field filtering, go to the "My Hats" list which appears to the right of your user name, and click on item. A check mark appears by this item which the feature is activated.
When field filtering activated, a minimal number of fields appear in the Work Item Viewer/Editor when you select a Work Item, and the Toggle Filter icon appears in the Viewer/editor header bar. The icon indicates the current state of field filtering for the current Work Item. When field filtering is activated, each time you select a work item the icon will show the "ON" state and minimal fields appear in the pane. Any missing fields can be shown by clicking the icon to toggle filtering "OFF" for the current item. All fields will then appear.
The Bulk Edit feature enables you to select multiple Work Items and edit them as a unit. When you save the changes, the field values 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 on Work Items:
To selected and edit multiple Work Items:
Make sure you are working in the correct Project, and in the Work Items topic in that project.
Select any view tab 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.
Use shortcuts or the Search feature (including the Query Builder if needed) so that the results contain 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.
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 at the header of the check box column.
Go to the Work Item Viewer/Editor (lower half of the Work Zone in the Work Items topic) to edit and change field values as desired. If the field is not available for Bulk Edit, the field is disabled and you will not be able to change the field value.
Click the button to save your changes and apply them to all the selected Work Items.
This feature may not be available in some Polarion ALM products.
The Multi Edit view also enable 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 Work Zone. 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.
This view has 2 display modes: flat, or table mode, and hierarchical (treeview) mode. You can toggle the display mode using the button, which appears highlighted when the treeview mode is active. In the treeview mode, you can use a special set of controls appearing in a selected Work Item to create new child or sibling Work Items, and to visually create links with a specified role to existing Work Items. You can quickly and easily create hierarchical Work Item structures, which is especially useful when developing requirements.
This section covers several common things that people need to do with Work Items.
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 ALM system and, in the default configuration, must be assigned a "developer" or "project_developer" role in order to appear in the Assignee list. (It can be easy to omit setting up accounts for e.g. a domain expert who is not on the engineering team but who needs to be assigned a Requirement.) For more information on roles, see Administrator's Guide: Configuring User Roles.
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 + (plus) icon in the Assigneefield, and select another user name from the drop-down list.
When there are multiple assignees, each additional assignee has a - (minus) icon beside the user name. If you need to remove an assignee, click this icon. You cannot remove all assignees... one will always remain. To unassign the item completely, select the 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.
You can initiate a change of status for a selected Work Item directly in the viewer/editor pane without entering Edit mode. The Status field has a drop-down list that displays a choice of Workflow Actions. These are configured by the Polarion administrator and are what actually changes the status value of the item according to the configured status and status transition definitions. (See Administrator's Guide: Workflow) for more information.
Selecting a new status (, for example), enables the and buttons in the toolbar of the Work Item form. You can edit other fields such as Resolution, or click the button to trigger Edit mode for the entire form.
Note that the button has a drop-down menu which enables you to set a new status for the current Work Item. (This is the default configuration for the menu.)
To add comments to a Work Item:
Select the item in some view (Table, etc.)
In the Work Item Editor, click the button to jump to the Comments section of the detail.
In the Comments portlet, click the button in the lower left-hand corner.
Type your comments in the Add new comment field and click the button.
To attach a file to a Work Item:
Select the item in some view (Table, etc.)
In the Work Item Editor, click the button to jump to the Attachments section of the detail.
In the attachments portlet, click the button in the lower left-hand corner.
Type your comments in the Add new comment field and click the button.
Enter a meaningful title in the Title field- one that will help you and others understand what the nature of the attachment.
Click the button to the right of the File field. The file selection dialog for your operating system appears.
Select the file in the file selection dialog. Its path appears in the edit box in the field.
If the file you are uploading is an updated version of an existing attachment, check the Update existing attachment check box.
Click the button to upload the file to the repository and attach it to the Work Item.
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 item appears in the drop-down menu of the in the Work Item Viewer/Editor toolbar. To vote, just click the menu item.
You can view the complete change history of the currently selected Work Item using the tab in the Work Item Viewer/Editor.
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.
You can add or remove yourself as a Watcher of any Work Item quickly and easily:
To add yourself as a Watcher:
Navigate to the Work Item you want to watch and select it in the Table view.
In the Work Item's detail pane toolbar, click the button and select in the drop-down menu.
To remove yourself as a Watcher:
Navigate to a Work Item you are currently watching and select it in the Work Items table.
In the Work Item's detail pane toolbar, click the button and choose .
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:
Navigate to the Work Item you want someone to watch and select it in the Table view.
In the Work Item's detail pane, scroll downward so you can see the Watchers portlet.
Click the button in the lower left corner of the Watchers portlet.
Select a user name in the User list and click the button.
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 it's value set during the project planning phase. For additional information, see Polarion for Project Managers: Setting up Work Items for Live Plan: Planning Constraint.
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, Tree, 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.
To print Work Items:
Select the Work Item(s) you want to print in the appropriate view, or formulate a query to retrieve just the item(s) you want to print.
Locate the action button labeled and click it to drop down a menu of actions.
Choose in the list.
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.
Linking Work Items is the key to being able to take advantage of the Traceability and Impact Analysis features. Even though that feature may not be available to everyone on your team (depending on licensing), your team should plan and follow a process of linking Work Items from the outset, as it will be important for those users who do have access to traceability and impact analysis.
Generally speaking, you want to create links from Requirements to the Tasks and/or Change Requests that fulfill them, and also links from Tasks/Change Requests to the repository revision in which they are implemented. By doing this, your team will have several key advantages with Polarion:
Possibility to trace from Requirements to the Work Items and code that fulfill them
Possibility to backtrace from e.g. defective code (in a repository revision) to the Tasks/Change Requests that implemented the defective code, and from those to the Requirement that called for the functionality.
Possibility to assess the impact (and by extension, the cost) of a changed Requirement by seeing all the artifacts that would be affected by the change.
Possibility to view and analyze various relationships between Work Items such as dependency, relatedness, parent-child, duplication, and follow-up.
This section describes the basic techniques for creating Links. There are basically 3 ways to do it:
Create links while editing an individual Work Item.
Create links for multiple Work Items at once using the Bulk Edit feature.
Create links using the Matrix View.
In the Work Item Editor you can click the button to auto-scroll the view to the link portlets: Linked Repository Revisions and Linked Work Items. Use the small button in either or these portlets to open the link editor in which you can select the revision or Work Item you want to link to the current Work Item.
For information on linking Work Items to repository revisions, please see Polarion for Developers: Linking a Resolved Item to a Repository Revision.
Tip
You can use Work Item Actions to create individual linked Work Items.
The technique using the Bulk Edit feature is the same as for single Work Items (see previous screenshot). The same portlets exist in the editor. The difference is that you have selected multiple Work Items in the view, so you can create the same link(s) to all the selected Work Items in a single operation.
This feature may not be available in some Polarion ALM products.
The Matrix view provides a robust way to both create and browse links. The matrix is populated with 2 subsets of Work Items, one for matrix rows, and one for columns. Each subset is built with a query in the special dual version of the Search bar. Each query can access either Work Items or repository revisions, so the matrix can show links between Work Items only, or between Work Items and repository revisions. Work Item queries can also filter for link Role- "depends on" or "related to", for example.
When the matrix has been populated, the intersection of each row and column shows if there is an existing link between the items in that row/column, and provides the possibility to create one if none currently exists. Existing links show and arrow in the intersection indicating the direction of the link. Clicking on the intersection pops up details about the link.
Refer to the screenshot below when following the procedure to create a link using the Matrix view:
To create a link in the Matrix view:
Populate the rows and columns of the matrix by building queries that will display the source and target Work Items (or Work Items and repository revisions) in the matrix rows and columns.
Toggle Link mode by clicking the Link Mode button in the toolbar (see screenshot).
In the Role combo box, select a role for the link.
Select the directionality of the link using the Direction buttons.
Tip
You can do this step either before or after creating the link in the matrix (see next step).
Locate the intersection of the Work Items you want to link (or the Work Item and the repository revision you want to link, and click on that cell. A green arrow appears in the cell showing the directionality of the link. The actual link is not yet created.
Click the to create the link. The green arrow in the cell changes to black.
Multi Edit view (not available in some products) provides the possibility to create, browse, and edit flat or hierarchical groups of linked Work Items. For a discussion of this capability, see Defining Requirements with Multi Edit.
There are 2 kinds of links recognized by the Live Plan feature: depends and parent. The planning.xml file in Administration assigns existing Work Item link roles to these two categories. (Links with roles which are of neither the depends nor the parent kind are ignored by Live Plan).
The dependent Work Item always links to the one it depends on. For example, if A depends on B, then A holds the link: B <-- A. This kind of link ensures that A does not start before B ends. However, this does not influence the planning of B. Consider the situation when High priority task A depends on Low priority task B. Task A will be planned after task B.
Children always link to the parent. Therefore the 'contains' link role should not be used; the 'parent' role with the opposite direction should be used instead. The Live Plan always shows only the leaf nodes of the containment hierarchy. for example, if Requirement has child Tasks, then just the Tasks are shown, not the Requirement. The parent's planned start/end are calculated as the minimum/maximum of its children's planned starts/ends values. The Remaining/Initial Estimate value of the parent are not taken into account in this case.
Beginning with version 2.0, Polarion adds the Suspect attribute to Work Item links, and an option Auto-suspect that, when enabled, automatically sets the suspect attribute to true for new links between Work Items. You can toggle the suspect attribute on and off using the Suspect check box available for each linked Work Item in the Linked Work Items portlet of the Work Item detail area. You can toggle the Auto-suspect option using the Auto suspect check-box in the Work Item editor control bar (beside the . The default state of the check-box can be configured in the Administration perspective. See Administrator's Guide: Configuring Linking.
Suspect links are useful for Change Impact Analysis. For example, consider the following figure.
This project is stable at the moment. Now suppose someone makes a change to the Work Item WI-4 as shown below.
When a Work Item is changed at this level, the links to Work Items that WI-4 impacts become suspect, and the owners of the impacted Work Items (WI-1, WI-2, WI-3) are notified. These owners can assess whether the changes to WI-4 impact their Work Item. Notice that the owner of WI-5 is not notified because changes to WI-4 don't impact WI-5. If Work Item WI-5 were to be changed, then the change would impact WI-4 and the owner of that item would be notified (see figure below).
Figure 2.28. Suspect Link
Notification propagation when a Work Item changes at a different impact level
The owner of WI-4 can then determine whether or not changes are needed to that Work Item. If s/he changes WI-4 as a result of the change to WI-5, then the owners of WI-1/2/3 are notified as shown previously.
Work Item hyperlinks provide a means to link a Work Item to any arbitrary URL. Hyperlinks are a sort of "fall-back" mechanism you can use if other linking features such as Work Item inter-linking, linking to repository revisions, or attachments don't meet your needs. To link Work Items in the same system, the aforementioned linking features are preferable. You can use hyperlinks to express a relation to a resource accessible by URL, but not fitting into another category like linked Work Item or links Revision. One possible application is to link a Work Item directly to a Subversion resource such as a document or source file.
Example 1: For a Work Item which is a Task requiring the delivery of some document and storing it in the Subversion repository (i.e. not keeping it just as an attachment to this work item, but let it live in some other location), you can create a hyperlink to the actual storage of the document once it is created. For example: http://myserver.company.com/repos/documents/text.doc.
Example 2: Link to any resource on the Internet. For example, link to Internet pages that are relevant to topics discussed in comments, so that everybody can easily refer to them. So a comment might say something like "this feature should be essentially like Their Product's Foo Bar functionality". Then a hyperlink can be added to linking to, e.g. http://acompetitor.com/their_product/features/foobar.html.
Unlike other types available of linking (Work Item links, for example) Hyperlinks are disregarded by Polarion's analysis features such as Traceability and Impact Analysis. If you want Work Items and Revisions to be available for analysis processes, do not use hyperlinks to link them as generic URLs.
Hyperlink Roles are meant to help categorize hyperlinks, something like the Title for attachments. Currently Polarion does not rely on them in any way. Roles are completely configurable in the Administration perspective (Enumerations > hyperlink-roles-enum). The intent behind the default configuration is that is for links to the Subversion repository or the local system, while is for linking to the Internet or systems outside Polarion/SVN. Hyperlink Role is really just a label.
There are 3 types of hyperlinks:
URL: this is for linking to an online resource that is not on the local file system or in the Subversion repository,
Repository URL: this is for linking to a resource in the Subversion repository.
File URL: this is for linking to a resource on the local file system.
You can create a hyperlink in the Work Item Editor when the Work Item is in edit mode, or by clicking the button in the Hyperlinks portlet when the item is in View mode.
There are 3 things you must specify:
The hyperlink role (see Hyperlink Roles above).
The hyperlink type (see Hyperlink Types above).
The actual URL of the hyperlink (see next paragraphs).
The user interface presents combo box controls for setting the role and the type.
When hyperlinking to an online/external resource, select in the Type field and enter the URL in the text box to the right of the combo box.
When hyperlinking to a Subversion URL, select in the Type field. An icon Select Subversion URL appears a the right side of the URL text box. Clicking this icon to display a picker dialog in which you can browse the repository and select the URL you want as the hyperlink target. The selected URL appears in the URL text box.
There is a similar interaction for hyperlinks to a local file system resource. In this case, you select in the Type field. A button appears next to the URL edit box. Clicking this button launches your operating system's file chooser dialog which you can use to navigate to and select the local resource you want as the target for the hyperlink. The path appears in the URL text box.
It should be noted that links to file URLs (e.g. file:///... are not clickable when your are accessing Polarion ALM using Firefox. It is also possible that such hyperlinks also may not be clickable in Internet Explorer, depending on your local internet and security settings.
A workaround is of course to copy the URL to the clipboard and paste it into a new browser window or tab.
You can export a set of Work Items to various document formats:
Microsoft Word (regular or Polarion "Live Document")
Microsoft Excel (regular or Polarion "Live Document")
Comma-separated Values (CSV)
Microsoft Project document
You can select a subset of all existing items for export using a search query in the Table, Live Plan, or Road Map views.
To export Work Items to a document:
Retrieve the Work Item(s) you want to export in the appropriate view using an appropriate search query.
Locate the action button labeled and click it to drop down a menu.
Choose in the list.
Specify the document format and character encoding.
In the Exported Fields list, check the boxes next to the fields you want to include in the exported document. Note that you can optionally change the order of the fields using the and buttons.
If you want to preserve the field selection, check Remember this selection.
Click Ok to begin exporting the document. You will be prompted for the location for the exported document.
Note about exported documents
Exported documents are not added to or tracked in the Polarion ALM repository. If you want to have them under version control, you will need to explicitly add them to the repository, and update the repository with any subsequent exports that you want to update the managed documents.
When you export Work Items to CSV or Excel Table format, any Work Items linked to the exported items with incoming links (i.e. backlinked Work Items) will be included in the exported document. Items linked via derived revision links, from Subversion commit messages for example, are also included in the export to CSV or Excel Table.
When you export Work Items to MS Word or Excel template format, inclusion of backlinked and derived revision linked items is optional via the Export back work item links and Export derived revision links check boxes, respectively.
When the button is selected in the Table view, then when exporting to MS Word the tree structure appears in the exported Word document. Hierarchy is indicated in the document using heading level paragraph styles HeadingN for paragraphs containing the titles of the Work Items. After export, you can generate a Table of Contents in MS Word, and it will display the same hierarchy as the table in the Tree display mode.
Before exporting items when the Tree mode is current, you should specify the sorting of the Work Items, including child levels. Remember that you can customize the fields that appear in the table using the Customize Table icon to the right of the Search bar in the view. If the existing fields are not sufficient for the sort order you want, you can add one or more Custom Fields and include them in the sort.
Availability Note
The Matrix view is not available in some Polarion ALM products.
There are 2 report options for exporting data from the Matrix view:
The following sections describe each option
You can export data from the Matrix view as a table to MS Excel. The export format is XML for MS Excel 2003. Exported are rows and columns visible in the view, and only links with roles visible in the view are exported. A maximum of 256 columns (255 column Work Items or Revisions) can be exported due to limitations of Excel. If the number of columns in the view is greater, you will see a massage and you should formulate a query to return a smaller column count.
When the Matrix view is selected, the item appears on the Operations menu. Once you have used the search controls to obtain the data you want to export, use this menu command to launch the Export process. In the Export dialog, choose in the Format field. You have the following additional options:
Export link roles - whether or not to display the link role in the Excel cells.
yesmakes sense only if links of all roles are displayed. When links of all roles are exported, but role names are not exported, then only one link from all links between two Work Items in the same direction is displayed.Export Work Item titles - If checked, Work Item titles are exported. Otherwise,only Work Item IDs are exported.
Export Revision messages (Revision matrix only) - If checked, both revision names and messages are exported. Otherwise, only revision names are exported.
The following notes apply to the exported data in Excel:
The exported document contains the export date, the queries used to obtain row and column Work Items or Revisions, and in the cases when one particular link role is selected, the role of the link.
Headers of rows and columns are hyperlinks to the Work Item or revision details in the Polarion ALM portal.
Links are indicated by an arrow like character (possibly with a role name next to it).
Suspect links are marked by the
?character next to the link-indicator character.Direction of a link between a Work Item and a Revision is always from the Revision to the Work Item, regardless of whether the link is created via a revision message or directly in a Work Item.
You can export tracebility data from the Matrix view to MS Excel. The export format is XML for MS Excel 2003. Traceability report has two columns: the first represents rows of the matrix, the second contains list of all linked Work Items or Revisions that are present in a column of the matrix in the view. Only links with the role selected in the view are exported.
Export is possible even when portal does not display the matrix due to a very large number of items retrieved by the search query in the view. A message in the portal informs you if this is the case, and the Link Role combo box is filled with link roles defined for current project or for the global level.
When the Matrix view is selected, the item appears on the Operations menu. Once you have used the search controls to obtain the data you want to export, use this menu command to launch the Export process. In the Export dialog, choose the in the Format field. The following additional options are presented:
Export link roles (Work Item matrix only): - If checked, link role is displayed in the report cells. Checking this option makes sense only if links of all roles are displayed. When links of all roles are exported, but role names are not exported, then only one link from all links between two Work Items in the same direction is displayed.
Export Work Item titles - If checked, Work Item titles are exported. Otherwise,only Work Item IDs are exported.
Export Revision messages (Revision matrix only) - If checked, revision commit messages are exported, otherwise only the revision names are exported. If the matrix does not retrieve revisions, this option is ignored.)
Include direct links (Work Item matrix only) - If checked, items linked by direct link are exported when the search parameters retrieve only Work Items. The option has no effect if the matrix retrieves revisions.
Include backlinks (Work Item matrix only) - If checked, backlinked items will also be exported when the search parameters retrieve only Work Items. The option has no effect if the matrix retrieves revisions.
(Note: If your product license does not support Live documents, this option will not be available.)
To export to a Polarion Live Document, run a query to retrieve the items you want to export, and open the Export Work Items dialog as previously described. In the dialog, choose either or in the Formatfield. The Template field will appear. Select the template you want to use to format the exported document.
The button in the Work Item Viewer/Editor toolbar provides access to several useful Work Item operations. You can duplicate the current Work Item in the current project or a different project in your repository. You can create new Work Item that is linked from the current one, or a new Work Item that links to the current one.
To duplicate a Work Item in the same project:
Select the item you want to duplicate in the Work Items table.
In the Work Item Viewer/Editor toolbar, click the button to drop down the Actions menu.
In the Actions menu, choose . A sub-menu appears.
In the submenu, choose the type for the new work item to be created (it need not be the same type as the item being duplicated).
A new Work Item of the selected type is created with all the properties of the item being duplicated, and opened for editing.
Edit any Work Item fields as necessary (attach a file or change the assignee, for example) and click the button to create the new Work Item in the system.
You can quickly change a Work Item type to another type. For example, if the Work Item is currently a Task, you might change it to the Defect or Change Request type.
To change a Work Item to a different Work Item type:
In the Table view (or other view) select the item you want to change to a different Work Item type.
On the Work Item viewer/editor toolbar, click the button.
On the drop-down menu, choose , and on the submenu, choose the type to which you want to convert the selected Work Item.
To duplicate a Work Item in another project:
Select the item you want to duplicate in the Work Items table.
In the Work Item Viewer/Editor toolbar, click the button to drop down the Actions menu.
In the Actions menu, choose .
Select the project in which you want to create a duplicate item from the Project list which now appears, and then click the button.
Select the type of the new Work Item (it need not be the same as the item being duplicated)in the Type list which now appears, and then click the button.
A new Work Item of the selected type is created with all the properties of the item being duplicated, and opened for editing in the detail pane. The Project selection does not change.
Edit any Work Item fields as necessary (attach a file or change the assignee, for example) and click the button to create the new Work Item in the system.
While focused on any Work Item, you can quickly create a new Work Item which has linking with the selected item, all in a single operation. There are 2 classification of links, each classification having several possible link relationships.
A new Work Item can be a Linking item which can have any one of these relationships to the selected item:
relates to the selected item
depends on the selected item
duplicates the selected item
is the parent of the selected item
has follow-up for the selected item.
A new Work Item can be a Linked item which can have any one of these relationships to the selected item:
is related to the selected item
is depended upon by the selected item
is duplicated by the selected item
contains the selected item
is follow-up for the selected item
To create a new Linking item:
Select the Work Item in the Work Items table which you want to have a Linking relationship to a new Work Item you will create.
In the Work Item Viewer/Editor toolbar, click the button to drop down the Actions menu.
In the Actions menu, choose . A sub-menu appears.
In the Actions sub-menu, choose the relationship for the new Work Item you want to create.
Select the Work Item type for the new item and click the button.
A new empty Work Item of the selected type is created and opened for editing in the detail pane.
Fill in the Work Item data as needed and click the button to create the new Work Item in the system.
To create a new Linked item:
Select the Work Item in the Work Items table which you want to have a Linked relationship to a new Work Item you will create.
In the Work Item Viewer/Editor toolbar, click the button to drop down the Actions menu.
In the Actions menu, choose . A sub-menu appears.
In the Actions sub-menu, choose the relationship for the new Work Item you want to create.
Select the Work Item type for the new item and click the button.
A new empty Work Item of the selected type is created and opened for editing in the detail pane.
Fill in the Work Item data as needed and click the button to create the new Work Item in the system.
This feature may not be available in some Polarion ALM products.
Polarion supports the creation of Baselines. Typically, baselines are used to mark the current state of Work Items in a tracker (usually a Requirements tracker), so that later team members can go and check the differences between different baselines, or between a baseline and the current state of Work Items. If there are less than 2 baselines selected for comparison, Polarion asks you to specify one or more repository revisions to compare against a single baseline.
To create a new baseline:
Navigate to the Project for which you want to create a new baseline. (You need to have write access to the Project.)
In the Topics portlet, select the topic.
Two portlets appear in the Work Zone: Baselines and Comparison Reports. If no baselines have been created yet, the Baselines portlet contains a row representing the head revision of the repository.
Click the button in the Work Zone toolbar. Controls appear enabling you to specify some properties for the new baseline.
Enter a name for the baseline in the Name field. This name will uniquely identify the baseline.
In the Revision field, select a repository revision to associate with the baseline you are creating. The head revision is the default, or you can select another.
In the Description field enter some descriptive text so that others can understand the nature of this baseline later to see if they want to use it in a baseline comparison.
Click the button to create the new baseline. It now appears as a row in the Baselines table.
It is possible to modify the name and/or description of an existing baseline. It is not possible to alter the actual contents in terms of Work Items.
To edit an existing baseline:
In the Projects portlet, navigate to the Project in which you want to edit a baseline.
In the Topics portlet, click the topic.
Locate the baseline you want to edit in the Baselines portlet and click edit in the Actions column.
Edit information as desired and click the button.
Your can generate an on-screen report that compares two or more baselines to each other and/or to the head/current repository revision.
To generate a baseline comparison report:
In the Projects portlet, navigate to the Project in which you want to compare baselines.
In the Topics portlet, click the topic.
In the Baselines portlet (Work Zone), select the baselines you want to compare by checking the box on the relevant baseline's row in the table. If you want to compare against the head revision, be sure to check that box as well.
Click the to generate the comparison report.
A job is schedules and launched. You can check the status of the job in the topic. When the report generation job is finished, a row is added to the table of reports in the Comparison Reports portlet. The Actions column provides 2 actions for the generated report: remove and view which enable the actions on the report that the names suggest.
The generated baselines comparison report is viewable after clicking the view action in the table of generated reports. The output is divided into 3 categories each displayed in a separate portlet in the Work Zone:
Timepoints compares activity in Timepoints between the revision(s) and/or baseline(s).
Categories compares activity in Categories between the revision(s) and/or baseline(s).
Work Items compares activity in Work Items between the revision(s) and/or baseline(s).
Tip
You can expand and collapse each portlet using the icon at the right-hand edge of it's title bar.