Creating Variants and Variant Specifications

Before undertaking operations described in this section, you should have completed the Feature Model and Master Specification(s) for your product line.

What is a Variant?

Variant is a special Work Item type that collects specification items for the feature set of a single product in a product line. This type is pre-defined in Polarion project templates with variant management support.

Creating a Variant

It is possible to create Variant items in a Document configured to contain that type, or in the Work Item Tracker. The latter approach is recommended.

To create a Variant in the Work Item Tracker:

  1. Open the project that contains the Variant work item type.

  2. In Navigation, expand the Work Items topic and select Variant. The Work Item Tracker opens with only Variant type items displayed. dog

  3. On the page toolbar, click the Create button and select Variant. A new Variant item opens in the Work Item Editor.

  4. Enter a title for the new Variant. The title should identify the product to which it pertains. For example "Useful Widget Professional Model".

  5. Optionally enter a description for the Variant.

  6. Click the Create button to save the new Variant (important!)

After creating a new Variant item, the next step is to select the features of the product it represents.

Selecting Features

To select features you must be using a Polarion VARIANTS license, and you must have the necessary permissions: MODIFY permission for the Work Item, and READ and MODIFY permissions for the Feature Selection field.

The Work Item Editor (lower pane of the page) contains a section named Feature Selection. If you have the required license and permissions, the Select Features button appears in this section. Clicking this button opens a new browser tab or window with a new instance of the Tracker, which displays a tree-table of all the Feature items in the project Feature Model. The tree is automatically sorted by "Variation Type" but administratos can set it to sort by "Outline Number" by default instead with a simple addition to the polarion.properties file. (See the following paragraph.) The tree is constructed on the parent-child hierarchy of Feature items. The order for variation type is Mandatory, Optional, Alternative and finally OR.

In this instance of the table, you cannot change the sorting via the user interface. But you can enter a query, and you can add/remove columns. It is, however, possible to have the table sorted by "Outline Number" so that features are presented as they appear in most Feature Model Documents. A Polarion administrator can add the following line to the system configuration file, polarion.properties:

com.polarion.variants.featureSelection.sortByOutlineNumber=true

The Polarion server must be restarted for the change to take effect.

Figure 21.5. Variant Feature Selection

Variant Feature Selection

Explicitly include/exclude features in a Variant

Note that some items can be already shown as selected. This is because the validation process on the back-end server has implicitly selected them according to Variation Types and Restrictions.

Figure 21.6. Explicit and Implicit Feature Selection

Explicit and Implicit Feature Selection

The user interface indicates when features are added by the back end server.

The back end adds all required items up to root, and Mandatory items below a selected item are added if they are not otherwise selected.

To select Features for a Variant:

  1. Open Variants in the Work Item Tracker (Navigation > Work Items > Variant).

  2. Select the desired Variant item in the tree-table listing of Variant type Work Items.

  3. In the Feature Selection section of the Work Item Editor, click the Select Features button.

    A new browser tab or window opens with a new instance of the tracker, containing a tree-table of all Feature items in the project Feature Model, and a sidebar labeled with the name of the Variant item.

  4. Explicitly include Features in the Variant by clicking the green check mark icon on the Feature's row in the tree-table. Explicitly exclude Features by clicking the red X icon. If you change your mind, click again to deselect.

    Note that when you include some Features, other Features may be implicitly selected, denoted by a pale green color in the check mark icon on the respective Feature rows. This happens because of the Variation Type set on the different Features.

  5. Save the Variant by clicking the Save Variant button in the sidebar. If there are many Feature to be selected, it is advisable to save periodically during the selection process.

Validating Features

The Polarion VARIANTS Server Add-on provides back-end validation of the feature selection of the Variant each time you save it (or open it). If there are any errors or warnings, then the sidebar displays a count, and provides links to the details.

Figure 21.7. Variant Validation

Variant Validation

The Polarion VARIANTS back-end server checks the validity of a Variant and issues errors, warnings, and information.

Clicking on the respective Errors or Warnings link in the sidebar displays a dialog listing the problems. The dialog is modeless, so you can keep it open as you work on the feature selection to correct problems. The dialog is updated each time you save the Variant. Errors result from Variation Type and link roles set on Feature items in the Feature model. For example, a Feature may have sub-features that have Variation Type "Or feature", which require that at least one must be selected, but none is selected. Selecting one and saving will resolve the error.

Important

All errors must be resolved before any specification Documents can be generated from the Variant.

Setting Variant Status

Like all Work Item types, the Variant type has a default workflow, with defined statuses, and actions that transition to another status. And like all types, the workflow is customizable to conform to any process you use. Among other possibilities, you can integrate a review and approval process for Variant items to ensure accuracy and completeness before generating specification Documents from a Variant.

Generating Variant Documents

The final step in the process is to generate one or more specification Documents based on your Variant. These Variant Specifications (sometimes referred to as "100% specifications"), contain all the specifications for one product in a product line. How many Variant Specification Documents you generate depends on how many Master Specification Documents you include when you launch the Document generation process. Generally, you would include all your Master Specifications. For example, if you have one Master Specification for Requirements and another for Test Cases, you would most likely want to include both when you generate Documents from a Variant, resulting in a Requirements Specification and Test Case Specification for a single product in your product line.

Figure 21.8. Generating Variant Documents

Generating Variant Documents

Select Master Specification Documents as sources for Variant Specification Documents

Note that it is possible to generate from a branched Master Specification Document. For example, some revision of the Master Specification may be approved for production of version 1.0, but work needs to continue on it for version 2.0, while version 1.0 is in production. By creating a branched Document from the approved version 1.0 revision, Variant Specifications for version 1.0 can be generated from the version 1.0 Master Specification, i.e. the branched Document.

To generate Variant Specification Documents:

  1. Open Variants in the Work Item Tracker (Navigation > Work Items > Variant).

  2. Select the desired Variant item in the tree-table listing of Variant type Work Items.

  3. In the Variant Documents section of the Work Item Editor, click the Generate Documents button.

  4. In the Generate Documents dialog, select one or more Master Specification documents. First select the space where the Document is stored, then select the specific Document.

    Repeat this step to include any additional Master Specification Documents, adding new rows to the table in the dialog if necessary, until you have listed all the relevant Master Specification Documents.

    When you have added all relevant Documents, click Next.

  5. In the next frame of the dialog, specify the space where the generated Variant Specification Document(s) should be stored. If there are multiple Master Documents, do this for each one. The space suggested by default is that of each Master Document. It is generally good practice to keep Variant Documents in a different space.

  6. Optionally specify a different title for each Document, if you prefer it to the default suggested title.

  7. Click the Generate button to launch the system job that generates the Variant Documents.

The dialog provides a link to the Monitor topic, where you can check the status of the job and access the job log. The Monitor opens in a new browser tab or window. If the job should fail, the log contains detailed information that can help you, your project administrator, or a technical support engineer diagnose and resolve the problem.

Regenerating Variant Specifications

You can regenerate Variant Specifications at any time.

  1. Select the Variant to regenerate.

  2. Click the Generate Documents button as you did when you generated them the first time.

  3. You will notice that the previously generated documents are automatically pre-selected in the Select Master Documents dialog and all you have to do is click Next.

  4. The Target Space and New Title fields are read-only and if you hover over the New Title field, a tooltip appears showing the revision date of the Master Document that the previous version was generated from, and the Master document's Head revision date.

  5. Click Generate

  6. A 'Generating Documents' dialog appears and provides a link to the Monitor to check the progress of the generation. Click OK to close the dialog.

Comparing Variants

Polarion VARIANTS provides a quick easy way to compare your Variants. A special matrix view shows which Features are used in which Variants.

To compare Variants:

  1. Open Variants in the Work Item Tracker (Navigation > Work Items > Variant).

  2. Select any Variant item in the table of Variant type Work Items.

  3. In the Feature Selection section of the Work Item Editor, click the Compare Variants button.

The Variants Matrix opens in a new browser tab or window. The structured Feature Model is rendered as rows, and Variant items as columns. You can filter the display using the special instance of the visual Query Builder at the top of the page. For example, you might query for Features with "Obsolete" status and Variants with "Active" status. This would reveal obsolete features in currently active Variants.

Sorting the Matrix

By default the matrix is sorted by "Variation Type". Administrators can change this to "Outline Number", (the way it usually appears in Feature Model documents), by adding the line below to the polarion.properties file.

com.polarion.variants.featureSelection.sortByOutlineNumber=true

There are two properties in the polarion.properties file that define the maximum number of cells in a Traceability matrix or a Variants comparison matrix.

Figure 21.9. Variant Matrix

Variant Matrix

Compare Variants shows which Features are included in which Variants. Content can be filtered by queries.

Reviewing Variant History

Variants are Work Items, and like all Work Items a change history is automatically recorded and maintained. Access the History just as you would for any Work Item (the History button in the Work Item Editor, for example.)

One particular feature of Variant history is that Feature selection is included. For any revision of a Variant item, you can see if Features were added or removed, and if so, how many, when and by whom.

In History and Baselines, the View Features button replaces the Select Features button. This is also the case if feature selection is read-only (the user does not have permissions needed to select Variant features, for example).

Working with Variant Documents

This section contains information that may be useful when viewing a generated Variant Document.

Identifying the Variant Work Item

When viewing a generated Variant Document, you may want to know the Work Item from which it was generated, and access that item. You can find this by opening the Document Properties sidebar when viewing the Variant Document. The Variant label displays the title of the source Work Item. The title is a link that opens the Variant Work Item in a new browser tab or window.

Identifying the Master Specification(s)

When viewing a generated Variant Document, you may want to know the Master Specification Document from which it was generated, and access that Document. You can find this by opening the Document Properties sidebar when viewing the Variant Document. The Branched from label displays the title and revision number of each Master Document used to generate the current Variant Document. The title is a link that opens the indicated revision of the Master Document in a new browser tab or window.

Searching for Generated Variant Documents

You can query on "variant.id" or "variant.title" to search for all Documents that were generated from a specific Variant item.