Defining the Feature Model

The Feature Model contains the name and description of every possible feature of every product in a product line. As noted in the overview section, the Feature Model in Polarion VARIANTS is a LiveDoc Document configured to contain a single Work Item type called Feature. The Feature items in the Document are structured with parent-child relationships (shown by indent levels) that denote features and sub-features.

The Feature Model Document

If you create your project from a project template that supports variant management (recommended), the Document, and the Feature Model space where it is stored, are created automatically. One Feature Model Document is allowed per project. For projects created from other templates, some manual configuration will be required. For information, please refer to the Advanced Topics section of this chapter.

This section discusses several considerations around your Feature Model Document that you may want to think about before beginning to work on it.

  • Document Type: Consider whether to define a Document Type for the Feature Model Document. Doing so enables you to have some configurations specific to that type, such as workflow and user permissions.

  • Document Workflow: Consider whether you need an approval process for your Feature Model Document. If so, you should configure a Document Type just for the Feature Model, and configure the Document workflow for that type to require user signatures before one or more status transitions... a status such as "Draft" to a status such as "Approved" for example.

  • User Permissions: Consider whether you need to control access to your Feature Model differently from other Documents and/or Work Items in the project. For example, you may want to restrict who can approve a Feature Model Document, or who can create or modify Feature type Work Items. If so, work with your Polarion administrator to set up the controls you require.

  • Work Item Type: If you know that Documents can be configured to contain more than one Work Item type, you may be considering configuring your Feature Model Document with multiple types. This is fine of other types of Documents, but your Feature Model should contain only one type: Feature. If your project is created from a template with variant management support, the Feature Model document will be created automatically and this type will be pre-defined in the project configuration and set up in the Document presentation configuration.

How to Create a Feature Model

This section describes how to go about creating a Feature Model in a variant management project. Some topics are only applicable in projects not created from a project template with variant management support, and are noted as such.

Creating the Feature Model Space

It is good practice to keep your Feature Model in a dedicated space. A space named "Features" is automatically set up in projects created from templates supporting variant management. You only need to create a dedicated Features space if your project is not one that was created from one of these project templates.

A new space can be created from the Index page of any existing space by clicking the Create New button on the page toolbar and clicking the Create New Space link in the resulting dialog.

Creating the Feature Model Document

In projects created from Polarion project templates with variant management support, a Document named "Feature Model" is automatically created in the Feature Model space, and there is an icon in Navigation that opens it for editing. In projects not created from a variant management project template, you should create a new Document in your Feature Model space:

  1. In Navigation, expand the Feature Model space and click on Index to open the space's Index page.

  2. On the page tool bar, click the Create New button, and in the Create New dialog, select LiveDoc Document, and follow the guidance in the next dialog. Name the new Document "Feature Model" and select Feature as the Work Item type.

    The Feature type should already be defined in your project and appear in the list of Work Item types. If it does not, cancel the operation and work with your administrator to create this type. (The Feature type is pre-defined in projects created from Polarion's variant management project templates.)

With the Feature Model Document in place, you are ready to begin constructing the feature model for your product line.

Creating Feature Items

To build your feature model, create a new Feature type Work Item for every feature of every product in your product line. Click the (Feature) icon in the Document Editor toolbar, or press your Enter/Return key when your insertion cursor is in an existing Work Item.

In new Feature items, the attributes you need to specify are:

  • Title: The title identifies the feature for all stakeholders. It appears in feature selection lists and restrictions.

  • Description: The description is optional. It can be used to provide some additional details.

    Be careful not to specify requirements for a Feature in its description. Requirements should be defined independently in a dedicated requirements specification Document that has a relevant Work Item type.

  • Variation Type: This describes the Feature's inclusion in product specifications. (For information, see Terminology: Variation Type.) In project templates supporting variant management, this is a custom field of the Feature type Work Item, of field type Enum, configured with the options as described in the linked Terminology section.

TIP

The Status field is one of the standard fields of all Work Items of all types, and the Work Item Properties shows it by default in all Documents. However, the value of the Status field in Feature type Work Items has no impact on any aspect of variant management. You can safely ignore it when defining Feature items.

Setting Variation Type

You specify the Variation Type for a Feature in the Work Item Properties sidebar. If that sidebar is not open, place your insertion cursor anywhere inside any Feature item in the Document, then drop down the Show Sidebar menu on the Document Editor toolbar, and select Work Item Properties.

If the Variation Type field does not appear in the sidebar, take the following steps to show it:

  1. On the Work Item Properties sidebar header, click the icon (Pane Settings) icon, and choose Select fields.

  2. In the Select Fields dialog, make sure the Variation Type field appears in the list on the right. If it doesn't, locate it in the list of fields on the left, select it, and click Add.

  3. In the list on the right, select the Variation Type field and select Show in Sidebar only or Show in Document and Sidebar, and click Apply.

The sidebar configuration is saved per user and the setting persists if you navigate away from the Document, and between logins.

Defining the Feature Model Structure

Product line feature modeling is a discipline in itself and teaching it is beyond the scope of this help. The Feature Model Document is a tool that enables variant managers to capture the product line features and their relationship to one another, so that specifications for variant products can be generated which use a subset of Feature Model features. The main relationship that needs to be captured is a parent-child relationship to show that some feature is a sub-feature of some other feature. For example, in a car, a parent feature might be "Headlamp", which has child features such as "Halogen Headlamp", "Mercury Headlamp", etc.

You can create the parent-child structure of Feature items in a Feature Model Document by indenting the items. You can decide when to create the structure. You may choose to do it as you create new Feature items, or after all Feature items have been created, or a combination of these approaches. In any case, you should undertake a comprehensive review of the Feature Model before beginning to create Variants.

TIP

An administrator can configure the Document workflow for your Feature Model Document to support a review and sign-off process.

Development of the Feature Model can be a collaborative effort, with different people working to specify different feature areas. For example, for a car product line, different people might specify the features for the braking system, the drive train, the driver electronics, etc.

Linking Features for Validation

When designing your Feature Model, you can create links between different features with special link roles that define dependency or exclusion between the linked features. Two link roles are pre-defined in Polarion's variant management project templates, which can be used for this purpose:

  • requires: denotes that, for example, Feature A requires Feature F. There is an opposite role, is required by that can be applied if linking from the other direction: specifying that Feature F is required by Feature A.

  • conflicts with: denotes that one feature cannot coexist in the same specification as another. For example, a feature such as "Halogen Headlamp" cannot coexist with a feature such as "Mercury Headlamp", so these features can be linked with this link role.

Note

Currently, these are the only link roles supported by the Polarion VARIANTS back-end server in its feature validation process.

You can use these link roles in conjunction with Variation Type to provide more parameters for the back-end process that validates features included in Variant Specifications. Variation Type provides a first layer. For example, two features in a group might have the Variation Type "Alternative feature", which allows only one to be included if the parent is included. These features conflict because of Variation Type, so there is no need to link them with the conflicts with role. It would, however, make sense to link features in different groups this way. For example, suppose two features like "Sensor North America" and "Sensor Europe", and neither one should ever be used in the same variant specification. Linking them as conflicting with each other ensures that the validation process will raise an error if the two are included in the same Variant.

For information on how to link items, see the User Guide topic Linking Work Items. The section Using Quick-link outlines the approach recommended when working with Documents.