Linking Work Items

Linking Work Items is the key to being able to take advantage of the Traceability and Impact Analysis features. Even though these may not be available to everyone on your team (depending on licensing), you 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.

Although it is quite possible to employ completely different semantics and processes, this topic will talk in terms of Work Items like requirements, test cases, tasks, change requests, and defects to illustrate how linking works to create traceability.

Generally speaking, you want to create links from items like requirements to the test cases that verify them, and tasks and/or change requests that implement them, and also links from tasks/change requests to the repository revision containing the implementation source code. By doing this, your team will have several key advantages with Polarion:

This section describes the basic techniques for creating Links. The focus is on linking Work Items while working with items in the Tracker. It is also possible to link Work Items while working in a Document. This is covered along with topics on working with Documents. See Editing a Document: Linking a Document's Work Items.

Topics covered here include:

  1. Link a Resource ,like a section of source code, to a Work Item.

  2. Create links while editing an individual Work Item.

  3. Create links for multiple Work Items at once using the Bulk Edit feature.

  4. Create links using the Matrix View.

Link a Resource - Resource Traceability

Once administrators have "Configured Resource Traceability" all developers have to do is add a comment in the source code they are creating and a reference will appear in the Work Item(s) they reference.

Search strings can also be defined that only search for Work Items with or without Linked Resources.

Linking Individual Work Items

In the Work Item Editor you can click the Links button to auto-scroll the page to the link sections of the Work Item Form: Linked Revisions and Linked Work Items. Use the small Edit button in the header of either of these sections to open the link editor in which you can select the repository revision or Work Item you want to link to the current Work Item.

Figure 6.30. Work Item Linking

Work Item Linking

Work Item Linking in Edit Mode.

Link a Work Item to a Specific Revision

  1. Select a work item in Tree view or click on it in a document and click the Open Item menu option.

  2. Scroll down to the Linked Revisons section and click on the icon on the right.

  3. Click on the icon.

    Figure 6.31. Revision Picker Dialog

    Revision Picker Dialog
  4. Narrow or expand the scope of the listed revisions by selecting a user in the drop-down list. (It lists only the current user's revisions by default.)

  5. Click on the name of the target revision.

  6. Click the sign to the right of the newly added revision.

  7. Click Save at the top then Save in the confirmation dialog box.

    The Work Item is now linked to the selected revision.

Linking Work Items Across Projects

To create Work Items with links to Work Items from another Polarion Project, add the Project ID from the other Polarion Project to the front of each Work Item in their respective Excel cells. (ProjectId/WorkitemId).

Using Quick-link

You can quickly link a selected item in the table to one or more other items in the table using the Quick-link feature. You can invoke it from the Quick-link icon on the row of the Work Item you want to link. The target item or items must also appear in the table. You might need to modify the search query to retrieve all the items to be linked.

To link a Work Item using Quick-link:

  1. Select the item in the table and click the (Create Link) icon on the item's row. The link detail panel appears.

  2. In the link detail panel, select the link role for the link you are creating. This describes the relationship of the source item to the target item(s)... "Relates to" or "Depends on", for example.

  3. If you want to link to multiple other Work Items, down Ctrl (Windows) or Command (Mac and others).

  4. In the table, locate the first Work Item you are linking to, and click the Link icon to the left of it. If you are linking to multiple items, scroll the table as necessary to locate each target item and click on it, continuing to hold down Ctrl or Command during the operation. The link detail panel updates with each link added.

  5. Save a single link by clicking the green Save button in the link detail panel. If linking to multiple items, when you are done linking click the Confirm button in the link detail panel to finish the linking operation, and then click the Save button to save the links. (Links are not saved in the repository or the Work Item history until you save.)

Figure 6.32. Quick-link

Quick-link

Quickly link any item in the table to one or more others using the Quick-link icons

TIPS

After initiating a link, if you then create a new Work Item, the new item will be linked to the first with the role selected in the link detail panel when you save the new Work Item.

If you make a mistake selecting a target item, you can click X in the link detail panel, confirm the cancel changes, and begin the linking process again.

You can open source Work Items in one browser tab/window and target Work Items in a different tab/window. Start the link with an item in the first, and finish by clicking link icons of one or more items in the second tab/window. The tabs/windows can contain either a Document or the Work Items Table.

The Quick Link icon for initiating a link is also available in the Work Item detail, to the left of the title.

Repository Revision Links

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.

Linking Multiple Work Items at Once

The technique using the Bulk Edit feature is the same as for single Work Items (see previous screenshot). The same sections exist in the editor.

Here are a few Bulk Edit specific features:

  • Bulk-edit only modifies selected Work Items.

  • When you select multiple Work Items, you can create the same link(s) to all the selected Work Items at once.

  • Direct links can be created since they are stored in the selected items.

  • Backlinks, using the Opposite Name, are stored in the backlinked Work Items. (So you cannot create backlinks using Bulk Edit.)

Linking Work Items in Documents

Work Items may be defined and contained in a Document. Your can create links while working in a Document, and you can view, and manage links in the Work Item Properties pane of the Document Sidebar. For information, see User Guide: Working with Documents: Editing a Document: Work Items in Documents: Linking a Document's Work Items.

Linking to Remote Work Items

If your installation has multiple Polarion servers in a clustered environment, and if any of those servers hosts its own Polarion repository, it is possible to link any Work Item in the repository of one server to another Work Item hosted on a different Polarion server ("remote" Work Item). To do this, you must know the URL of the item you want to link to on the other server. If you don't already know it, you will need to log in to the other server, search for the target Work Item, select it, note its URL, then log back into the first server and proceed to link your Work Item to the one on the other instance. You can link items across any two remote servers.

Once you know the URL of the remote Work Item, the procedure to link to the remote item is straightforward:

  • Navigate to and select the Work Item from which you want to link to a remote Work Item.

  • Scroll to the Linked Work Items section of the form. The last line in this section is ready for you to specify a new link.

  • In the Title column, click the (Select Work Item from Remote Server) icon. A browser prompt box appears.

    Figure 6.33. Linking to Remote Repository

    Linking to Remote Repository

    Linking a Work Item to another one hosted on a different Polarion server and repository

  • Enter the URL of the target Work Item on the remote host and click OK.

TIP

Remote Work Items appear in the same Linked Work Items table as locally hosted items, but they display the remote server icon in the Project column.

Add Linked Data Items to Work Items

Polarion supports externally Linked Data that lets users link to objects from other tools, like SIEMENS' Teamcenter.

The Linked Data can be used to:

  • Create links for or LiveDocs from objects that reside on external Linked Data enabled tools. (Act as a Linked Data consumer.)

  • Link Polarion Work Items to objects that reside on external Linked Data enabled tools. (Act as a Linked Data provider.)

(This is generally done by creating or selecting a remote object in a "delegated UI" provided by the Linked Data provider.)

Once "Linked Data Friends" are configured by an administrator, they appear as an icon in the Linked Work Items section of a Work Item.

Add an External Linked Data Item to a Work Item

  1. Select the target Project.

  2. Click on Work Items in the navigation bar.

  3. Select an existing Work Item or create a new one.

  4. Scroll down to the Linked Work Items section.

  5. Click on the blue Linked Work Items masthead or to edit the section.

  6. If you have associated a Linked Data artifact container with the current project, you will see a icon.

  7. Click on the icon.

  8. The "Link External Linked Data Item" dialog appears.

  9. Select the External Linked Data location from the "Location" drop-down box.

  10. Click Select an Existing Item.... (Or Create New Item.. to create a new item within the external application.)

    Note

    Create New Item.. will launch the external Linked Data application in a pop-up window.

    (The workflow to create a new item will vary depending on the application.)

  11. Example: Existing Item from Teamcenter:

    1. Select Teamcenter from the "Location" drop-down box and click Select an Existing Item....

      (Teamcenter appears in a pop-up window.)

    2. Select an item from the list on the left. (An overview of its details appears on the right.)

    3. Click OK.

    4. The item is linked to the Polarion Work Item.

    5. Hover over the link to get a preview of the linked object.

    A New Work Item from an External Polarion Server:

    1. Select a Polarion Server from the "Location" drop-down box and click Create New Item...

    2. Select an item type from the drop-down menu.

    3. The "Link New Task" dialog appears with the external Polarion embedded within the pop-up.

    4. Enter the required fields and click Create.

    5. The Work Item is created and linked to the local Work Item.

    6. Hover over the link to get a preview of the linked Work Item.

  12. Click Save. (Links are created on both the local and external applications.)

If Post-processing Operations Fail

If there is a connectivity issue while adding or removing Linked Data links, the following error appears.

  • Click Retry to resubmit the link addition or deletion.

  • Click Revert cancel the link addition or deletion.

Linking Work Items in the Matrix View

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 Query Builder. 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.

Figure 6.34. Matrix Search

Matrix Search

Matrix view showing dual Search queries and popup link details

Refer to the screenshot below when following the procedure to create a link using the Matrix view:

Figure 6.35. Matrix Toolbar

Matrix Toolbar

Matrix toolbar in link creation mode

To create a link in the Matrix view:

  1. 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.

    TIP: If you filter Work Items for one type in Navigation you may not get the query results you expect in the Matrix. You should generally select the top-level Work Items node in Navigation rather than one of the Work Item types listed in the sub-nodes.

  2. Toggle Link mode by clicking the Link Mode button in the toolbar (see screenshot).

  3. In the Role combo box, select a role for the link.

  4. 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).

  5. 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.

  6. Click the Save to create the link. The green arrow in the cell changes to black.

Creating Links in Multi Edit View

The Multi Edit view provides the possibility to create, browse, and edit flat or hierarchical groups of linked Work Items. When editing a Work Item in the Multi Edit view, the toolbar contains the (Insert Link) icon which you can use to link the edited Work Item to another Work Item, a repository revision, or a URL.

How Links are handled in Live Plan

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).

Dependencies

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.

Parents

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.

Suspect Links

Work Items have a Suspect attribute that affects links, and there is a configuration option Auto-Suspect that, when enabled, sets the Suspect attribute to true on links between Work Items, indicating a potential inconsistency should any of the linked items be modified. 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 section of the Work Item Editor. You can toggle the Auto-Suspect option using the Auto suspect control in the Document Properties panel of the Document Sidebar (for Document-based Work Items). The default state of the check-box can be configured in Administration. See Administrator's Guide:Configuring Linking.

Not Applied to Parents or Structural Document Links

The Suspect attribute is only applied to links to Child Work Items. (Not to Parents or Structural links within a document.)

Figure 6.36. Stable project with linked Work Items

Stable project with linked Work Items

Linked Work Item with the Suspect attribute set

Structural Document Links are not Suspect

In the example below, a Requirement (DOCU-473) was added to the document, positioned as a child (using “Tab”), and linked to DOCU-461 using the is refined by option. The document was then Saved.

Structural links and their relationships are visible directly within the document and should be updated along with the parent.

Figure 6.37. A Child Structural Document that Will NOT be subject to Suspect Warnings

A Child Structural Document that Will NOT be subject to Suspect Warnings

The “Description” in the A Child Structural Document that Will NOT be subject to Suspect Warnings DOCU-461 Requirement Work Item was changed, and then saved using A Child Structural Document that Will NOT be subject to Suspect WarningsSave and Suspect. All the external child links for A Child Structural Document that Will NOT be subject to Suspect Warnings DOCU-461 are marked as A Child Structural Document that Will NOT be subject to Suspect Warnings Suspect, but the newly created structural child link A Child Structural Document that Will NOT be subject to Suspect Warnings(DOCU-473) IS NOT.

Figure 6.38. How Suspects Work

How Suspects Work

Work Item Hyperlinks

The Hyperlinks section of Work Items provides a means to link a Work Item to any kind of online resource via a URL. For example, you might link to relevant Wiki pages or Documents, or to repository folders and files in your Polarion portal, or to pertinent information on the web or your organization's intranet. When creating a hyperlink to any resource, you can specify whether it is an "internal" or "external" resource.

Hyperlinks are supplemental to the traceability links you create between Work Items. For traceability, you should always link Work Items to each other with an appropriate link role, and not use the Hyperlinks feature. Hyperlinks are disregarded by 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.

Usage Examples

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.

Example 3: Link to some resource in your Polarion repository and open it in the Repository Browser, e.g. http://polarionhost.company.com/polarion/repo/someFolder leads to the Repository Browser's info view of the specified folder. Any hyperlink URL that appears to be a repository URL (starting with values specified in the system configuration property "repo" or "repo.ui") is rendered as a repository URL and the link opens in the Repository Browser tool.

Hyperlink Roles

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 interface (Enumerations > hyperlink-roles-enum). The intent behind the default configuration is that refers internally is for links to the Subversion repository, while refers externally is for linking to the Internet or systems outside Polarion/SVN. Hyperlink Role is really just a label.

Hyperlink Types

There are 2 types of hyperlinks:

  • URL: this is for linking to an online resource that is not in the Subversion repository.

  • Repository URL: this is for linking to a resource in the Subversion repository.

Creating a Hyperlink

You can create a hyperlink in the Work Item Editor when the Work Item is in edit mode, or by clicking the Edit button in the Hyperlinks section when the item is in View mode.

There are 3 things you must specify:

  • The hyperlink role (see Hyperlink Roles above).

  • The hyperlink URL 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 URL 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 Repository URL in the Type field. The (Select Repository URL) icon appears at 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.