Create Variant Work Items

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.

3. On the page toolbar, click Create 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. (Optional) Enter a description for the Variant.

6. Click Create to save the new Variant.

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

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 part 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 administrators 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.

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.

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 Select Features.

   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.

   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 Save Variant in the sidebar. If there are many Feature to be selected, it is advisable to save periodically during the selection process.

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.

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 box listing the problems. The dialog box is modeless, so you can keep it open as you work on the feature selection to correct problems. The dialog box 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 subfeatures with Variation Type Or feature, which require that at least one must be selected, but none is selected. Selecting one and saving resolves the error.

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.

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

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 Generate Documents.

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

   Repeat this step to include any additional Master Specification Documents, adding new rows to the table in the dialog box, 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 box, 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. (Optional) Specify a different title for each Document, if you prefer it to the default suggested title.

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

The dialog box 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.

Regenerate Variant Specifications:

1. Select Variant to regenerate.

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

3. Notice that the previously generated documents are automatically preselected in the Select Master Documents dialog box, 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 box appears and provides a link to the Monitor to check the progress of the generation. Click OK to close the dialog box.