Variant Management Advanced Topics

This section covers several topics of a more advanced nature, which may not be applicable for or needed by the average Polarion VARIANTS user.

Configure Variants for Existing Projects

This section describes how to configure existing projects, created with a Polarion version prior to 2015 or templates other than the Specification Project with Variant Management Template or the Weather Station demo project.

System Requirements:

  • You must have Polarion 15.0 (2015) or later,

  • A valid Polarion VARIANTS Add-on license installed on the Polarion server,

  • The Polarion VARIANTS Server Add-on must be obtained from the Polarion Software web site and installed according to the included instructions.  

1. Configure the "Variant" Work Item Type

To configure the "Variant" Work Item:

  1. Enter Administration in the target Project.

  2. Click Work ItemsTypes

  3. Enter variant as the ID and Name, click Select and choose or upload an icon.

    You can change variant as the required ID value by editing com.polarion.variants.variantType in the polarion.properties file.

  4. Enter a Description, and click then Save.

  5. Now you have to setup a workflow for the newly created type. (Project AdministrationWork ItemsWorkflow)

  6. Click Create to the right of the newly created Variant Work Item to get started.

    (See Configure a Workflow for more details on how to configure a Work Item workflow.)

  7. A recommended Status enumeration can be fairly simple. For example, something like: Draft, In Review, Defined and Rejected.

  8. Click then Save.

  9. Define the following custom fields for the new Type. (Project AdministrationWork ItemsCustom Fields)

    Add a Feature Selection as a Custom Field for the newly created Variant Work Item with featureSelection as the ID, Feature Selection as the Name and select Feature Selection as the Type from the drop-down menu.

    (See Configuring Custom Fields for more details on setting up a Work Item custom field.)

  10. Update the Work Item form layout. (Project AdministrationWork ItemsForm Configuration)

    Add Variant Documents and Feature Selection as separate sections. Exclude the Feature Selection field form the custom fields panel:

    ..                    
<field id="description"/>  
<field id="featureSelection"/>  
<field id="variantDocuments"/>   
<!-- Description of panel is mandatory. -->  
<panel description="Custom Fields">         
<field id="@allCustomFields,-featureSelection"/>  
</panel>

    (See Work Item form layout for more details if you are unsure about how to do this.)

TIP

You can also create a new project using the Specification Project with Variant Management template and reuse the configuration files by copying them to your existing projects:

  • .polarion/tracker/fields/variant-custom-fields.xml

  • .polarion/tracker/workflow/variant-workflow.xml

  • .polarion/tracker/fields/variant-status-enum.xml

  • .polarion/hats/_default/tracker/variant-form-layout.xml

2. Configure the "Feature" Work Item Type

To configure the "Feature" Work Item:

  1. Enter Administration in the target Project.

  2. Click Work ItemsTypes

  3. Enter feature as the ID and Name, click Select and choose or upload an icon.

    (Feature can be capitalized in the name but must be lowercase for the ID.)

    You can change feature as the required ID value by editing com.polarion.variants.featureType in the polarion.properties file.

  4. Click then Save.

  5. Now you have to setup a workflow for the newly created Feature type. (Project AdministrationWork ItemsWorkflow)

  6. Click Create to the right of the newly created Feature Work Item to get started.

    (See Configure a Workflow for more details on how to configure a Work Item workflow.)

  7. A recommended Status enumeration can be something like: Active and Obsolete.

  8. Click then Save.

  9. Define the following custom field for the new FeatureType. (Project AdministrationWork ItemsCustom Fields)

    (variationType as the ID, Variation Type as the Name, Enum as the Type and select Variation Type from the drop-down menu.)

    (See Configuring Custom Fields for more details on setting up a Work Item custom field.)

  10. Configure additional link roles between the Feature type Work Items. (Project AdministrationWork ItemsEnumerationsworkitem-link-role-enum.xml)

    (See Configuring Enumerations for more details.)

  11. Define a link rule for both requires and conflicts with roles, so that the links are only used between two Features.

    (Project AdministrationWork ItemsEnumerationsworkitem-link-role-enum.xml)

    (See Link Roles and Rules for more details.)

TIP

You can also create a new project using the Specification Project with Variant Management template and reuse the configuration files by copying them to your existing projects:

  • .polarion/tracker/fields/feature-custom-fields.xml

  • .polarion/tracker/workflow/feature-workflow.xml 

  • .polarion/tracker/fields/feature-status-enum.xml

3. Configure the Specification Work Item Types

Specification Work Item types can be any Work Item type that will be part of your Product Line and will be included in Master Specification Documents.

(For example, Requirement, Test Case or SW Requirement.)

To configure the specification Work Items:

  1. Add a custom field restriction to each Work Item type that will be used as a specification.

    (pvRestriction as the ID, Restriction as the Name and pvSCL as the Type).

Cross-project Variant Management

You can manage Variants across multiple projects, and select multiple Master Specification projects that are separate from the Feature Model.

Note

Generated Variant Specification documents must reside in the same project as the Variant Work Item.

There are two different methods for configuration cross-project variants. It depends on whether you want to use the same configuration for all Work Items within a Project (the default), or you want to us Work Item Custom Fields to use different configurations for all Variants.

(The legacy method of creating a definitionProject custom field is still supported, but not recommended.)

Use the Same Configuration for All Work Items within a Project

Configured via the Variants section in Administration on the project level.

All Configurations are Optional

All the configuration fields in Variants Administration are optional.

Leaving them as --not selected-- will simply default to the current Project

  1. Click on the top left corner.

  2. Click Administration.

  3. Click Variants.

  4. Select the Feature Model Project.

  5. Select a Master Specification Project and click .

    (Add as many Projects as needed.)

  6. Click Save or Cancel to cancel changes.

See the Propagation section for details on how configure Variant Management so that the selection of Variant Work Items is determined by the relations to their parents and their parents' restrictions.

Use different Configurations for all Variants via Work Item Custom Fields

  1. Click on the top left corner.

  2. Click Administration.

  3. Click Work Item and select Custom Fields.

  4. Click Edit to edit the existing variant-custom-fields.xml file.

    A Variant custom field should already exist in a Project created from a template that supports Variants, but if it wasn't create one as follows:

    1. Click Create new configuration.

    2. Select the Variant option and click Next.

  5. Add () the following IDs:

    • featureModelProject

    • masterSpecificationProjects

  6. Click Save on the top.

  7. Exit Administration, Expand the Work Item , select Variant and select a Variant from the list.

  8. TheCustom Fields section of the Variant now includes options to add a Feature Model and Master Projects that only apply to the selected Variant.

Legacy Cross-project Configuration

The legacy configuration via the definitionProject Custom Field that defines what project both the Feature Model and Master Specifications should be loaded from is still supported, but we recommended using one of the two options above.

Comparing Cross-project Variants

The comparison feature works the same as for single-project variant management. Just open a Variant that has the Definition Project field set to a different project, and click the Compare Variants button in the Feature Selection section of the Work Item Editor. Compare Variants shows all Variants that have same project selected in Definition Project field.

Propagation

If configured, then the selection of Variant Work Items is determined by the relations to their parents and the restrictions of these parents. (The restrictions can only be managed on the highest level of the hierarchy, not on all levels manually.) Therefore:

  • A child item with no restriction that is linked to a parent item, is included in the generated variant specification if its parent item is included, i.e. its restriction is evaluated as TRUE.

  • A child item with a restriction that is linked to a parent item:

    • Is included in the generated variant specification if both the child and parent's restrictions are evaluated as TRUE.

    • Produces a validation error if its own restriction and its parent's restrictions are evaluated differently.

Minimize exceptions when migrating existing data sets

When using the propagation of Work Items into a variant selection on existing data sets, the complexity of the migration can be substantial. By default the variant evaluation reports an error if propagation and restrictions contradict each other because the data is not consistent.

To simplify the adoption of propagation, it's possible to allow this inconsistency by setting the following property to true in the polarion.properties file. (The default setting is false.)

com.siemens.polarion.purevariants.propagationDeterminedByRestriction=true

When set to true, propagation is determined by restrictions. (If there is a conflict between propagation and restrictions, then the restriction is honored instead of throwing an evaluation error.)

Warning!

This behavior also has a consequence: If a child Work Item in the document structure is included into the variant selection via propagation, then its parent Work Item from the Document structure will also be included, even if its restriction does not allow it.

Normally this situation would trigger a validation error, but with com.siemens.polarion.purevariants.propagationDeterminedByRestriction set to true, it will be allowed and not reported to the user.

RECOMMENDATION:

Only use this property during the early adoption of propagation and remove it as soon as your data is in a consistent state.

Configure Propagation

Configured via the Variants section in Administration on the project level.

  1. Click on the top left corner.

  2. Click Administration.

  3. Click Variants.

The Propagation of Referenced Work Items

Under Propagation, when selecting the Work Item link roles to include, you can also generate from documents that contain referenced Work Items. If you do, then the configuration is taken from the Project that contains them.

Back-end Server Administration

The Variants topic of global and project Administration enables administrators to restart the Polarion VARIANTS back-end server and clean up the data. The Initialize Server button launches the operation.

This action should rarely be needed. It should only be invoked to recover from unexpected VARIANTS Server data corruption, caused by a power outage, for example.