This section covers several topics of a more advanced nature, which may not be applicable for or needed by the average Polarion VARIANTS user.
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.
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.
Enter Administration in the target Project.
Click Work Items
Types
Enter variant as the ID and Name, click 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.
Enter a Description, and click then .
Now you have to setup a workflow for the newly created type. (Project Administration
Work Items
Workflow)
Click Variant Work Item to get started.
to the right of the newly created(See Configure a Workflow for more details on how to configure a Work Item workflow.)
A recommended Status enumeration can be fairly simple. For example, something like: Draft, In Review, Defined and Rejected.
Click then .
Define the following custom fields for the new Type. (Project Administration
Work Items
Custom 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.)
Update the Work Item form layout. (Project Administration
Work Items
Form 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.)
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
Enter Administration in the target Project.
Click Work Items
Types
Enter feature as the ID and Name, click 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.
Click then .
Now you have to setup a workflow for the newly created Feature type. (Project Administration
Work Items
Workflow)
Click Feature Work Item to get started.
to the right of the newly created(See Configure a Workflow for more details on how to configure a Work Item workflow.)
A recommended Status enumeration can be something like: Active and Obsolete.
Click then .
Define the following custom field for the new FeatureType. (Project Administration
Work Items
Custom 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.)
Configure additional link roles between the Feature type Work Items. (Project Administration
Work Items
Enumerations
workitem-link-role-enum.xml
)
(See Configuring Enumerations for more details.)
Define a link rule for both requires and conflicts with roles, so that the links are only used between two Features.
(Projectworkitem-link-role-enum.xml
)
(See Link Roles and Rules for more details.)
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
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: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).
You can manage Variants across multiple projects, and select multiple Master Specification projects that are separate from the Feature Model.
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.)
Configured via the Variants section in
Administration on the project level.
All the configuration fields in Variants Administration are optional.
Leaving them as --not selected-- will simply default to the current Project
Click on the top left corner.
Click Administration.
Click Variants.
Select the Feature Model Project.
Select a Master Specification Project and click .
(Add as many Projects as needed.)
Click
or 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.
Click on the top left corner.
Click Administration.
Click Work Item and select
Custom Fields.
Click 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:
Click
.Select the Variant option and click .
Add () the following IDs:
featureModelProject
masterSpecificationProjects
Click
on the top.Exit Administration, Expand the
Work Item , select
Variant and select a Variant from the list.
TheCustom Fields section of the Variant now includes options to add a Feature Model and Master Projects that only apply to the selected Variant.
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.
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 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.
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.
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.)
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.
Only use this property during the early adoption of propagation and remove it as soon as your data is in a consistent state.
Configured via the Variants section in
Administration on the project level.
Click on the top left corner.
Click Administration.
Click Variants.
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.
The Variants topic of global and project Administration enables administrators to restart the Polarion VARIANTS back-end server and clean up the data. The 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.