Common Operations

This section covers the things you will most commonly need to do when using Polarion to develop and manage requirements.

Locating Requirements

Requirements are defined in the context of a project, so generally the first step in locating requirements is to open the project that contains the requirements you want to work with. For information, see User Guide: Accessing Projects.

In projects, requirements may be defined in the context of Documents, or they may be defined directly in the integrated tracker (Navigation > Work Items > Table), or a combination of the two approaches may be used. The simplest way to locate the requirements in a project is as follows.

To locate requirement type Work Items in a project:

  1. In navigation, expand the Work Items topic. The Work Item types currently configured for the current project appear as child nodes.

  2. Click on Requirement. The Table views becomes current in the Work Items page and the table contains all the Requirement type Work Items in the project whether they are defined in a Document or directly in the tracker.

It's important to note that Work Item types are configurable to support the semantics of any process. In the above steps, if you don't see "Requirement" it is because your project has been customized with different types. You would click on whatever type corresponds to requirements in your organization. For example, if your process is some variant of the Scrum methodology, you might see "User Story" in Step 2 above rather than "Requirement".

If a requirement you have located is defined in a Document and you want to edit or view it there, you can easily open the containing document. When selected in the top section of the page, the Edit in Document button appears in the Viewer/Editor toolbar in the lower part of the page. Click this button to open the associated Document and go directly the selected requirement in it.

Creating Requirements

Your approach to creating a new requirement depends on the approach to requirements you have decided to use with Polarion.

If you have opted to define requirements using Documents, see User Guide: Documents and Pages Topic: Working with Documents: Work Items in Documents. You can automatically create requirement artifacts in Polarion when you import a Microsoft Word document. See Importing Word Documents in the same chapter.

You can optionally create requirement artifacts directly in the project's integrated tracker. Remember that the Work Item type "Requirement" is a default type for some project templates, and that some other type corresponding to "requirement" may be configured for your project.

To create a new requirement artifact in the tracker:

  1. Open the project (see User Guide: Accessing Projects). Be sure you have the permissions necessary to create new Work Items.

  2. In Navigation, click Work Items and select the Table view.

  3. In the Table view's toolbar, click Create and choose Requirement (or the custom type that corresponds to a requirement in your project). A new Work Item is created.

  4. In the Work Item Editor (lower half of the Table view), edit the data fields as needed and click the Create button when finished.

Accessing Requirements

To access requirements you need, at a minimum, read permission for the project containing requirements. If you need additional permissions contact the project leader (usually listed on the project's Home page), or the project administrator.

The foregoing section Locating Requirements explains the basics of accessing requirements. This section additionally covers:

  • Accessing requirements in a Document

  • Accessing requirements in Polarion legacy tools:

    • Modules

    • LiveDoc documents

Filtering for Type

In a Document that contains Requirement type Work Items, you can filter the document to show just the requirements. See User Guide: Documents and Pages Topic: Working with Documents: Filtering Work Items in a Document. You can isolate Requirement type Work Items with the following query:


Where "requirement" is the ID of the Work Item type corresponding to a requirement in your specific project.

Legacy tool: Module

Special containers for requirements called "Modules" were provided in Polarion versions prior to version 2011. Modules appear in that and subsequent versions if they existed prior to the upgrade. It is recommended that users convert any existing Modules to the current LiveDoc Document format. Contact Polarion Technical Support if you need to convert legacy Modules to LiveDoc Documents.

Legacy tool: 2010 Documents

Polarion version prior to version 2011 provided templates for creating Microsoft Office Word and Excel documents that could store Polarion Work Item data in them. That technology had limitations imposed by the document format, and it is now deprecated in favor of LiveDoc Documents.

If you have legacy "live" documents created with Polarion versions 2010 and earlier, in Word or Excel format, these documents still exist in the repository but they are no longer indexed, and consequently will not appear in query results. If you still need the legacy documents in that format, and you want them indexed, please consult Polarion technical support.

Modifying Requirements

How you go about modifying existing requirements depends on how they are stored: in a Document, or in the integrated tracker. Modifying requirements defined in a Document is very straightforward: simply open the document and edit it as you would any document. For more information, see User Guide: Documents and Pages Topic: Working with Documents: Editing a Document.

Requirements created directly in the integrated tracker must be edited using that tool. Generally the Table view is best for changing text content or data. The tracker useful if you want to edit the same field for multiple requirements - to set the same status or assignee value for multiple requirements, for example. The Bulk Edit feature is available for that.

To modify requirements using the tracker:

  1. Locate the item as described in the foregoing section on Locating Requirements. Select the desired requirement in the Table view of the Work Items topic.

  2. Edit the requirement in the Work Item Editor (bottom portion of the Table view). Some fields can be edited "in-place". To edit the entire requirement, click the Edit button in the Work Item Editor toolbar.

Linking Requirements

Traceability from requirements to implementation tasks and source code, to tests, to defects and fixes - it's an important issue for many organizations, especially those in industries where rigorous regulatory mandates must be not only met, but compliance must be verifiable. Polarion makes this kind of deep and broad traceability both easy to achieve, and very visible. It all starts with requirements.

The key to success is timely linking of requirement Work Items to others of the same type, and to other types representing such artifacts as engineering tasks and change requests, QA test cases and defect reports. As a requirements engineer, you will be most concerned with linking requirements to other requirements, and possibly to test cases. Other teams may possibly link their artifacts to your requirements as well, depending on your organization's traceability needs. As with other common operations, you approach to linking depends on your basic approach to requirements: Documents or tools. This section points you to the features you need to link requirements for both approaches.

Linking in Documents

You can link the Work Items defined in a Document to other items in the same Document, in a different Document, or stored directly in the Tracker. The User Guide chapter on Documents provides complete information about Linking a Document's Work Items.

Linking in the Work Item Editor

The table view of the Work Items navigation topic, and the same view of a Document, provide an editor for Work Item data which you can use to link a requirement to any Work Item of any type, either in your project, or in another project. (Linking to Work Items in a different repository is also possible, but this is an advanced issue and not needed for most requirements engineering projects).

The Linked Work Items section of the Work Item Editor provides a graphical interface for linking a selected requirement Work Item with another Work Item. A picker dialog is available with integrated querying, including graphical Query Builder, that you can use to locate the target Work Item for the link.

To familiarize yourself with linking this way, see User Guide: Work Items Topic: Managing Polarion Work Items: Linking Work Items.

See also: Advanced Topics: Linking via the Matrix View.

Exporting Requirements

In Polarion, requirements are Work Items, so any of the Work Item export features can be used. For information, see these topics:

Exchanging Requirements

Polarion supports the exchange / interchange of requirements specifications with external customers or suppliers via ReqIF/RIF. You can import ReqIF or RIF files to new or existing Polarion LiveDoc Documents, and export LiveDocs to new or existing ReqIF or RIF files.

For information, please see the User Guide topic: Using ReqIF Import/Export.

Reviewing and Approving Requirements

If your job is to review and approve requirements developed and managed with Polarion, you need to know how to locate the requirements you need to review and how to mark them as approved or rejected. There is no cut-and-dried way to do this. It really depends on your organization's process and how that process has been mapped to Polarion's workflow. Assuming that has been done, then you should receive email notifications about requirements that need your attention. This will most likely happen in response to a status change in a requirement type Work Item: from "Draft" to "Awaiting Approval", for example.

Polarion provides extensive support for any formal review and approval process. Workflow can be customized with the necessary statuses and transitions, as well as auto-assignment of items to those responsible for review and approval. Any type of Work Item, including Requirements, can be have an approval process built into its workflow.

For information on how to review and approve/disapprove Work Items, see the User Guide topic: Approving or Disapproving Work Items.