Creating a Master Specification

In a variant management project, a Master Specification is a LiveDoc Document that contains all the specifications for all the products in a product line. For example, a Master Specification might contain all the requirements, test cases, risks, etc. for a product line. For a large product line you can have multiple Master Specifications. For example:

The same goes for other artifact types: risks, regulations, etc. You can be even more specific with a given artifact type. You might have Master Specifications for different kinds of requirements: functional, non-functional, software, electrical, mechanical, etc. The main thing to remember is that each Master Specification Document should contain all the artifacts of the given type for the entire product line.

You can take advantage of all the features of Polarion LiveDocs in your Master Specifications. For example, you might configure a project to have a different Document type for each type of Master Specification, and then configure appropriate workflows for each type, including an approval process which includes different stakeholders for different Document types. You can also configure more specific user permissions applicable to different Document types.

Polarion's project templates for variant management come pre-configured with a space named "Master Specifications", which contains two Master Specification Documents: "System Requirements Specification" and "Test Specification".

Creating the Work Items

Each Master Specification Document should be configured to contain the desired Work Item type or types, depending on the approach you decide upon. For example, the Document might be configured to contain only Requirements, or both Requirements and Test Cases, as shown in the following figure.

Figure 21.2. Work Item Insertion and Configuration

Work Item Insertion and Configuration

Document configured to contain two Work Item types

You can create new Work Items in your Master Specification using the menu on the toolbar of the Document Editor, or by pressing your Enter/Return key when your insertion cursor is inside an existing Work Item.

Structuring the Work Items

You can easily create a hierarchical structure of parent-child relationships between Work Items in your Master Specification by indenting them to different levels. This is a common practice with requirements. Such structuring automatically creates links in the Work Items with a link role of "has parent" or "is parent of". These link roles can subsequently be queried for reports, dashboards, etc.

It is recommended that you complete and review the structure of the Work Items in your Master Specifications before creating Variants that draw items from them.

Figure 21.3. Structured Work Items in a Master Specification

Structured Work Items in a Master Specification

Example of a Master Requirements Specification using indentation to create parent-child relationships.

Defining Restrictions

Restriction is an attribute of Work Items in a Master Specification. It is what ties any given item to Features in the Feature Model so that variant specifications can be generated from the Master Specification, which contain only those Work Items relevant to the specification for a specific product. Restrictions are specified using the pvSCL language, the language of the Polarion VARIANTS Server Add-on. Reference documentation for the language, developed by Pure Systems and widely used in their variant management systems, is provided in the distribution of the extension

If no Restriction is specified for a Work Item in Master Specification, then it will be included in all generated Variant specifications. So you specify restrictions to indicate that some requirement (for example) should be included in Variant specifications only if the restriction expression evaluates to TRUE. Otherwise (if the restriction is evaluated to FALSE), the item won't be included.

A special editor for specifying Restrictions in pvSCL is implemented in Polarion VARIANTS and appears in the Restriction field of Work Items in Master Specification Documents included in variant management project templates. The Restriction Editor can be toggled in and out of Full Screen mode using the F11 key. It has an auto-completion feature, invoked via the keyboard shortcut CTRL + Space. You can access the Restriction Editor in the Document Editor (see the following section), or you can open Work Items in the Work Item Tracker and find it in the Custom Fields section of the page. The pvSCL editor is case insensitive.

Setting Up the Sidebar

If you want to use Restriction Editor in a Document, you need to open the Work Item Properties sidebar when focused on a Work Item in a Master Specification Document. The editor is not shown by default, so you will need to perform the following steps to show it:

  1. Place the insertion cursor inside any Work Item in the Document, and open the Work Item Properties sidebar if it is not open.

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

  3. In the Select Fields dialog, make sure the Restriction 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.

  4. In the list on the right, select the Restriction field and select Show in Sidebar only, then click Apply.

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

Figure 21.4. Restriction Editor

Restriction Editor

Edit Restrictions from a Document or the Work Item Tracker

Specifying a Restriction

Important

Your Feature Model should be complete before you begin specifying Restrictions in the Work Items in a Master Specification.

The Restriction Editor has built-in completion assistance. The Ctrl + Space (Control + Space) shortcut opens a list box containing the Features in your project's Feature Model, and logical and Boolean operators. You can add any item in the list to the Restriction expression in the editor field by double-clicking the item in the list (see the previous figure).

The following steps assume you have a Master Specification Document open, and the Work Item Properties sidebar configured to show the Restriction Editor, as described earlier in this section. You may find it useful to have the Feature Model Document open in another browser tab or window.

To specify a Restriction:

  1. In the Document body, place the insertion cursor anywhere inside the Work Item for which you want to specify Restriction.

  2. In the Work Item Properties sidebar, click inside the Restriction field.

  3. Press Control + Space and in the list of Features, expressions and operators, double-click the item you want to add to the Restriction.

  4. Repeat the above to add expressions, operators, and Features as needed to construct a complete Restriction expression in pvSCL.

    If you know pvSCL, you can type the complete Restriction expression in the Restriction Editor, or build it in a text editor and paste the finished expression into the editor.

You need to fully specify all Restrictions in all Master Specifications before you can create Variants and generate product-specific specifications.

TIP

You can search for the Requirement using a Restriction query followed by the Feature ID.

pvSCL Expression Language

The pure::variants expression language pvSCL is a simple language to express constraints, restrictions and calculations. It provides logical and relational operators to build simple but also complex boolean expressions. Polarion VARIANTS uses a subset of the pvSCL language to link Features with Work Items, and to express relations between Features.

Boolean Values

Expressions can resolve to a Boolean value, that is, TRUE or FALSE. An expression is said to fail if its Boolean value is FALSE, and to succeed otherwise.

Syntax: TRUE or FALSE

Example: NOT(TRUE = FALSE)

Logical Combinations

Expressions can be logically combined. For this purpose the expressions are evaluated to their Boolean values. It is an error if this conversion is not possible. The logical operator is then applied to the Boolean values resulting in TRUE or FALSE. The simplest restriction will be just the name of a feature but it is also possible to build restrictions out of a combination of logical operators and multiple feature names.

The following logical operators are supported:

  • AND - Binary operator that yields TRUE if both operands are TRUE.

  • OR - Binary operator that yields TRUE if at least one operand is TRUE. If the first operand is TRUE then the second operand will not be evaluated.

  • NOT - Unary operator that yields TRUE if the operand is FALSE.

Syntax:

  • expr AND expr

  • expr OR expr

  • NOT(expr)

Example: FeatureA AND NOT(FeatureB OR FeatureC)