Variability parameters allow you to specify a value for a Variant in the Decision Set Editor and Variant Selector.

The value that is set for a variability parameter can then be used to set properties of artifacts in a Product Model. In addition, variability parameters can be used in Derivation Scripts and Validation Scripts, and can be passed from one Variant to another through Requires Dependencies.

This topic contains the following sections:

Cabin example model

The Examples database includes the Cabin model that demonstrates the use of variability parameters. The Cabin model demonstrates how variability parameters can be used to set property values of artifacts in product models. The Cabin model also demonstrates parameter propagation, derivation and validation.

Creating variability parameters on variants

To create a parameter on a Variant: open the Property Pages of the Variant, click the Parameter tab, and then select the Has Parameter check box.

Use the properties that appear on the Parameter tab to define the Parameter, for example, its type and default value. See Creating a parameter for a variant.

When a Variant is shown on a diagram, the default value of its parameter is shown as follows:

How parameter values affect the status of a variant

When working with parameter values in the Decision Set Editor and Variant Selector, the Status of a Variant depends on the Decision, whether the parameter has a default value, and whether the parameter value has been changed or set.

The Status of a Variant can be set through its parameter:

In this example we demonstrate how the Status of a Variant that has a parameter can be set in the Decision Set Editor. Variation Point1 is linked to three Variants.

We create a Decision Set and open the Decision Set Editor.

The Value column indicates whether a Variant has a parameter:

Initially the Decision for each Variant is Undecided and the Status of each Variant is Undecided.

We set the Decision of each Variant to Include. The Status of Variant1 is set to Included because it has a default value. The Status of Variant2 remains as Undecided because it does not have a value set for its parameter.

We set the Decision of each Variant back to Undecided, change the value of Variant1 to 200, and set the value of Variant2 to 300. The Status of Variant1 is set to Included because we changed its default value, and the status of Variant2 is set to Included because we set a value.

For more detailed worked examples that demonstrate how the Decision Set Editor and Variant Selector set the Status of a Variant that has a parameter, see How the status of a variant can be set - decision set editor or How the status of a variant can be set - variant selector.

Passing a parameter value from one variant to another variant

Through a Requires Dependency you can pass a parameter value from one Variant to another Variant.

To pass a parameter value, the Requires Dependency must be set up to propagate the parameter value and then the parameter is passed only when the Status of the source Variant is Included.

The target Variant does not require a parameter to be defined, but if it does have a parameter defined that parameter will be overridden by the parameter and its value from the source Variant.

In this example, we demonstrate how a parameter can be passed between variants.

we can see that there is a Requires relationship between Variant1 and Variant2, and a Requires relationship between Variant1 and Variant3.

We have defined a parameter for Variant1 and Variant2, but have not defined a parameter for Variant3. On the Property Pages of the Requires Dependencies we have selected the Propagate Parameter Value check box.

We create a Decision Set and open the Decision Set Editor. We can see that Variant1 and Variant2 have a parameter with no value set (<x> appearing in the Value cell) and Variant3 has no parameter (blank Value cell).

We set the value of Variant2 to 50.

We now set the value of Variant1 to 100. The Requires Dependencies propagate the parameter value of 100 from Variant1 to both Variant2 and Variant3, overriding the value of 50 that we set for Variant2. The Decision Set Editor sets the Status of each Variant to Included because each Variant has its parameter value set.

Note that because the values of Variant2 and Variant3 have been set through propagation, those values are read only.

Setting a parameter value of a variant through the parameter of a requires dependency

You can create a parameter for a Requires Dependency and then use that parameter to set the parameter value of the target Variant when the Status of the source Variant is Included.

You cannot set the value of a parameter on a Requires Dependency through the Decision Set Editor or Variant Selector, so the parameter must have a value. You can set the value of the parameter as a default value or through a derivation script.

The source Variant must not have a parameter. The target Variant does not require a parameter to be defined, but if it does have a parameter defined that parameter will be overridden by the parameter and its value from the Requires Dependency.

In this example, we demonstrate how a parameter on a Requires Dependency can be used to set the parameter value of a Variant.

We can see that Variant1 requires Variant3 and the Requires Dependency has a parameter with a default value of 1. Variant2 also requires Variant3 and that Requires Dependency has a parameter with a default value of 2.

We create a Decision Set and open the Decision Set Editor. We can see that none of the Variants have a parameter (their Value cells are blank).

We set the Decision of Variant1 to Include. Variant1 requires Variant3 and the Requires Dependency sets the value of Variant3 to 1.

We set the Decision of Variant1 to Undecided and set the Decision of Variant2 to Include. Variant2 requires Variant3 and the Requires Dependency sets the value of Variant3 to 1.

Setting the value of an artifact property from a parameter value

Through an Artifact Dependency you can use the parameter value of the source Variant to set a selected property of the target artifact. The value of the artifact property is set when the Product Model is created.

In this example, we use a parameter value of a Variant to set the multiplicity of an Attribute in the Product Model.

We can see that Variant1 is linked to Attribute1 through an Artifact Dependency. Variant1 has a parameter that can be set through the Decision Set Editor or Variant Selector.

We open the Property Pages of the Artifact Dependency and on the Variability Options tab we set the Artifact Property property to Multiplicity Text.

On the diagram, the name of the selected Artifact Property is shown on the Artifact Dependency.

We create a Decision Set, open the Decision Set Editor and set the value of the Variant1 parameter to 4.

We create a Product Model from the Decision Set, and in the Product Model we can see that the Multiplicity of Attribute1 has been set to 4.

Setting a parameter value through a derivation script

The value of a Variant parameter can be derived through VBScript that is defined for that Variant.

The Derivation Script can use parameter values that have been set for Variants in the context of the Decision that is being edited in the Decision Set Editor or Variant Selector.

The Cabin model demonstrates the use of derived parameters.

For more information about VBScript, see the VBScript user's guide and reference guide on the Microsoft MSDN website.

You can show the derivation script of a Variant or Requires Dependency on a diagram: right-click the Variant or Requires Dependency, point to Add, and then click Derivation Script.

In the following example we demonstrate how a parameter value can be derived from the parameter value of another Variant.

Our model has two Variants named Variant1 and Variant2. Variant1 has a parameter that has a default value of 10.

We open the Property Pages of Variant2 and on the Parameter tab we select the Derived check box.

We click Derivation Script tab and can see that a framework script has been added for deriving the value of the parameter.

We delete the <parameter expression> place holder and add the text that follows for deriving the parameter value. The script should set the value of Variant2 to the value of Variant1 multiplied by 10. Note that Variant1 is a model object reference that we created by dragging Variant1 to the script.

We create a Decision Set and open the Decision Set Editor. We can see that the value of Variant2 is set to the value of Variant1 (10) multiplied by 10.

We change the value of Variant1 to 55 and can see the derived value of Variant2 is updated to 550.

For more information about derivation scripts, see Script functions, attributes and objects - derivation scripts for variability parameters and Script functions, attributes and objects - overview.

Validating a parameter value through a validation script

The value of a Variant parameter can be validated through VBScript that is defined for that Variant.

Through the Validation Script you can validate the value of a parameter. If the value is invalid, you can mark the Variant as inconsistent and display the reason in the Reason column.

The Cabin model demonstrates the use of validation script.

For more information about VBScript, see the VBScript user's guide and reference guide on the Microsoft MSDN website.

You can show the validation script of a Variant or Variation Point on a diagram: right-click the Variant or Variation Point, and select Add > Validation Script.

In the following example we demonstrate how a parameter value can be validated through the Validation Script.

Our model has a Variant named Variant1. Variant1 has a parameter that has a default value of 2.

We open the Property Pages of Variant1 and click the Validation Script tab.

We select the Has Script check box and see that a framework script has been added to the script.

We delete the <constraint is met> place holder and add the text that follows to validate whether the value equals 10. We change the Script.Result text to 'Value does not equal 10'.Note that Variant1 is a model object reference that we created by dragging Variant1 to the script.

We create a Decision Set and open the Decision Set Editor. The Status of Variant1 is not Included, so its value is not validated.

We set the Decision of Variant1 to Include. The default value of 2 is now validated against the Validation Script. The Validation Script sets EvaluateConstraint to False that makes Variant1 inconsistent. The Script.Result text is displayed in the Reason column.

We set the value of Variant1 to 10. The value now equals 10 so the Validation Script sets EvaluateConstraint to True and the value is treated as valid.

For more information about validation scripts, see Script functions, attributes and objects - overview or Script functions, attributes and objects - validation scripts for variants and variation points.