Creating Relationships Between Model Objects

This chapter lists prerequisites and common elements and discusses how to:

• Create and edit expressions.

• Create externs.

• Create a relationship.

• Work with relationships.

• Create relationships outside the model with SQL queries.

Prerequisites

Visual Modeler provides graphical ways to express common configuration relationships. You can create relationships between classes, class attributes, selection points, and selection point attributes.

Before you create relationships, verify these setup requirements:

• To create a relationship by using internal domain members, the Internal flag must be set to True on the parent class.

• To create a relationship by using external data, the Internal flag must be set to False and you must have a valid database connection.

  See Connecting to a Database from Visual Modeler.

• The Elimination and Comparison constraints and relationships operate on expressions; therefore, expressions of the proper type—numeric, Boolean, string, and date—must be defined before they can be created.

Common Elements Used in this Chapter

Creating and Editing Expressions

An expression defines a variable. It associates a numeric, Boolean, date, or string value with a name. All relationships use expressions except summations and resource constraints.

An expression can contain:

• A literal value (to act as a constant).

• Selection point attribute values.

• A value that a user enters at runtime.

• Functions that operate on other expressions.

When you create an expression:

• The name appears in the Relationships or Expressions folder.

• The file name appears in the file list in the File view.

• The file name is automatically added to the project’s .csp file.

There are a few points to remember while using the expression editor. When you create an expression, the numeric, Boolean, date, or string value within it is assigned to the expression name. Data for use in expressions can come from constants, class attributes, and other expressions.

Expressions have their own editor, which opens when you click the Expression editor button on the toolbar. The expression editor has these elements:

The following figure shows the expression editor window.

To create an expression:

1. Click the Expression editor button.

   A name dialog box appears in which you name the new expression.

2. Click OK; the editor opens.

3. Write the expression in the Expression field by double-clicking the functions and insertable objects.

   Enter additional information as necessary. Indicate the data type of the result in the Return Type drop-down list box.

Warning! Limit attribute values to 10 characters or fewer. Otherwise, the model will not compile.

See Visual Modeler Expression Editor Functions.

To delete a relationship or expression, select its name in the Components view and press the Del key, or right-click the name and select Delete.

Static Variables

A static variable is an expression that performs no operations and always returns a constant value.

To create a static variable, create an expression, set the return type, enter a value, and then close the window. (You cannot make an explicit assignment, such as SalesTax=9.5, inside the expression editor.) For example, to create an expression named Airport Tax, set the return type to Numeric and enter the value 12 in the Expression window.

External Variables

Use the external variable to retrieve a value—float, numeric, string, Boolean, or date—from the user or a database at runtime.

You cannot assign a value to a variable and operate on it in the same expression. Any calculated value must be assigned to its own expression name. Expressions can be built by using many other expressions.

User-Defined Functions

If you do not find a function that is appropriate to your specific needs, you can create one that is. To create your own function, you must create a description of the function in XML and write a Java class that implements the interface of Advanced Configurator. Sample code and sample files are provided.

See Creating and Adding User-Defined Functions.

To display the user-defined functions in the function list of the Expression editor, click the Refresh Functions from Server button and compile the model.

Creating Externs

You can direct the model to pull data at runtime from outside sources such as the enterprise database. Externs can have the following types: float, integer, date, string, and Boolean. The modeler can specify a default value for each extern and specify whether the passed-in value is required. Defaults can be overridden by end-user input on the user interface (UI).

You can declare externs in the Extern Manager dialog box. The Extern Manager lists all externally referenced data for the component model:

Externs participate in the right-hand side of requirement constraints. Each extern has a Required check box in the cells of its column, which, when selected, makes the extern required if the left-hand side conditions are satisfied. The Required check box is the only setting that is available for the constraint-level use of externs.

Extern-based controls display violations and Control Why Help when the extern is declared as an argument or as part of an expression that serves as an argument. The arguments can be in a variety of relationships, including eliminations, comparisons, requirements, and compatibility constraints. Externs that are marked required at the object level in the Extern Manager display violations and Control Why Help only when running the completeness check.

At runtime, the system checks each type of extern for accuracy, but only date externs are also checked for formatting errors. If the value is not of the right type or format, an error message is displayed to the end user.

Because the requirement of an extern doesn’t affect propagation, the requirement of externs is determined after static and dynamic default selections are applied.

To declare an extern:

1. Select Project, Extern Manager to open the Extern Manager dialog box.

2. Click the Add button to add a new row to the table.

3. Specify the properties of each:

   Type	Select Boolean, Date, Float, Int, or String.
   Default Value	Enter a default value to appear in the UI when the configuration session begins or when it is reset.
   Required	Select this check box if you want the extern to be required on a model-global basis. To make an extern required when constraint conditions are met, do not select the Required option in the Extern Manager, but rather in the constraint itself by inserting the extern as a column in the right-hand side of the relationship and selecting the Required check box in the cells.
   Invalid Type Explanation	Enter the message that you want to appear to the user when the type of the data does not match that specified for the extern variable. You can define parameters for explanations to indicate the objects involved. See Creating Parameterized Explanations.

4. Click OK.

   The externs now appear in lists of objects for building requirement constraints.

Creating a Relationship

You can start a relationship from either the Insert menu or the relationship palette of icons on the right margin of the application window. Depending on the type of relationship, one of two editors appears:

• The table-based editor, for compatibility and requirement constraints, and for dynamic defaults.

• The participant-list editor, for resource constraints and summation relationships.

The dialog boxes for compatibility constraints, requirement constraints, and dynamic defaults provide an opportunity to name the relationship and select the class or domain member attributes to constrain against. These relationships are created by using a table interface.

See Relationships Between Objects.

The dialog boxes for resource constraint and summation relationships differ slightly because each participating object takes a specific role in the constraint. These constraints are created by using a simple list of participants.

See Relationships Between Objects.

To launch the relationship editor:

1. From the Insert menu, select a relationship.

   Alternatively, click a relationship icon on the palette.

   If the relationship is an elimination or a comparison, the relationship editor appears immediately.

   For all other relationships, you can draw a line to indicate the relationship after the relationship icon is selected. Position the cursor over a class; the class is highlighted. Click and drag to draw a line to another class; when the target class is highlighted, release the button. You can also a draw a line from a class to a selection point.

2. Provide a name for the relationship.

   Note that the relationship name is assigned to a corresponding .cms file. To change a relationship name, click the Change button.

The dialog boxes for compatibility constraints, requirement constraints, and dynamic defaults provide an opportunity to name the relationship and select the class or domain member attributes to constrain against. These relationships are created by using a table similar to that shown in the example that follows.

See Relationships Between Objects.

Creating Relationships that Have Expressions

All relationships use expressions, with the exception of summations and resource relationships. The figures below show a numeric elimination, numeric comparison, and Boolean comparisons, respectively. To create a comparison or elimination relationship, click its icon on the palette. The comparison editor lists operators and available expressions; the elimination editor lists operators, selection points, and expressions. From these lists you can build an elimination or comparison expression that determines when a conflict will occur. If you have no expressions of a given type, the corresponding editor field is empty.

To include an expression in either the left- or right-hand side of the relationship:

1. Click the heading of the column to the right of where you want to insert the expression.

2. Click the Add Column button.

   The Object Selection window displays, listing the available objects.

3. Scroll to the expressions, which are at the end of the list, and double-click the one that you want.

   It is inserted into the new column.

4. If the relationship is a requirement constraint, dynamic default, or a compatibility constraint, define the relationship for each domain member:

   1. Click in the cell of a domain member column to open a drop-down list box that contains the allowed domain member options.

      For instance, rows of the selection point columns contain lists of domain members; expression columns contain subcolumns for operators, expression type (function or constant), and value.

   2. In the same row as the domain member, click the cells of the expression subcolumns.

      The first subcolumn, beginning left to right, contains a list of the allowable operators for the expression. The second subcolumn is the argument type, constant or function f(x), of the value that is operated on. The third column is the value. If you chose the constant type in the preceding subcolumn, type the value. Be sure that it is the correct data type for the expression. If you chose the function argument type, use the cell drop-down list box to insert the expression.

      Note. The allowed choices for comparison operators depend on the return type of the expression argument. Similarly, allowed choices for the constant values depend on the expression argument’s return type. Selecting an operator with the function symbol f(x) narrows the allowed choices in the values subcolumn to a list of expressions that are compatible with the column’s expression type.

   3. Repeat these steps for each domain member.

5. On the other side of the relationship, select the argument for the relationship from the list for the domain member or selection point.

Note. You can't add expressions to the right-hand side (RHS) of a compatibility, requirement, or dynamic default constraint.

Working with Relationships

When a relationship is created:

• The name appears in the Relationships folder.

• The file name appears in the file list in the File view.

• The file name is automatically added to the project’s .csp file.

To delete a relationship or expression, select its name in the Components view and press the Del key, or right-click the name and select Delete. The constraint is removed from its .cms file. If the .cms file is then empty, you can delete it and manually remove the file name from the .csp file from the File view.

To display relationships in the Model Structure view, click a participating object, such as a class. Red lines appear, connecting all participants. The relationship name appears on the connecting lines. Double-clicking the name opens the relationship editor.

The costTotal relationship between subclasses cost and kit and subclasses cost and component

When an object is selected, the Attributes tab shows the relationship or expression name and the path to the file containing the relationship.

To reopen an editor, double-click its name in the Components tab.

Relationships Displayed as a Table

Compatibility, requirement, and dynamic default relationships are created by using a table-based editor.

The Relationship Editor toolbar appears directly above the table. The buttons are:

When inserting columns in a directional constraint, click to the right or left of the bar before clicking the Add Column button.

To resize columns, position the cursor over a header’s vertical border and then drag left or right.

To move a column, position the cursor over its name, then drag the column to a new position; a red vertical line appears when a possible location is reached.

Note. The column of check boxes cannot be moved.

In the preceding example of an expression, if the value of Married is greater than the value of SpouseAge, then the default selection is Main Applicant.

Table-based relationships have the Format property, which enables you to define them within a database table.

See Creating Externs.

Expressions (Boolean, numeric, string, and date expressions) can participate as arguments (that is, columns) only on the left-hand side (LHS) of the expression; only the dynamic default can have expressions in both the left-hand and right-hand sides of table-based relationships. Each row of the expression column comprises two subcolumns—the comparison operator subcolumn followed by the values subcolumn. The allowed choices for the comparison operators depend on the return type of the expression argument. In turn, input validation for the constant values depends on the expression argument’s return type. To reference other expressions in the values subcolumn, the term f(x) is attached to copies of the allowed comparison operators. If the relationship is on the RHS and you choose a f(x)version of the operators, you narrow the allowed choices in the values subcolumn to a list of other expressions that are compatible with the column’s expression type.

Relationships Displayed with Participant Lists

For the resource constraint and summation relationship, the relationship editor displays a list of the attributes that are involved. They differ somewhat from table-based relationships in that each participating object takes a specific role in the constraint.

Editing Compatibility Constraints

In a compatibility constraint, the constraint type can be toggled from Compatible to Not Compatible. Typically, the majority of domain members are compatible. Check the Description window to verify that you have the expected setting.

ANY and ALL

The selection option ANY can appear in each row and column where internal data is used. ALL appears where external data is used.

Note. ALL does not exist in the database; it is merely a shorthand representation that Visual Modeler displays so that you can select all queried domain members. ALL implies that any queried value is acceptable.

Editing Requirement Constraints

The requirement constraint is displayed in a table similar to the compatibility constraint. ANY and ALL behave as they do in compatibility constraints.

See Also

Requirement Constraint

Editing Dynamic Defaults

A dynamic default is a way to specify that a particular item will be preselected in response to a runtime event, such as a user selection. An end user can override a dynamic default without violating a constraint. (If a user overrides a constraint, a violation occurs, which can prevent a user from completing a valid configuration unless the selections are altered.) Regardless of the default, if all but one choice is constrained away, the remaining choice will be computer-selected. This behavior occurs automatically; no programming is required.

The dynamic default relationship table is similar to that of the compatibility or requirement constraints. ANY has the same significance. Dynamic defaults include the option NONE for every row. Selecting NONE means that there are no defaults for that combination of domain members, or that every combination of class and domain member properties is to be ignored. NONE allows you to work with queried values without knowing the specific domain members.

Note. Do not confuse the relationship editor NONE option with the None that is displayed at runtime.

See Creating a “None” Domain Member.

By default, the Comment area displays an equation for each selected combination.

Editing Resource Constraints

For the resource constraint, the relationship editor initially displays the classes or attributes that were selected or defined when the constraint was created. However, the system allows multiple providers and consumers. Clicking the Add Provider, Add Consumer, or Remove button displays a list of all attributes in the model.

Note. For the constraint to work correctly at runtime, the provider must be a selection point. The Model Tester automatically supplies controls for the provider and consumer so that you can monitor resources as choices are made.

The following figure shows an example in which a lens is arbitrarily assigned as a resource that can contain no more than three coatings. The coatings might take the form of a tint or other coating type, such as an anti-reflective coating.

Editing Summation Relationships

Attribute summation uses a dialog box similar to that of the resource provider relationship. It simply lists all of the classes that contain the attribute that you want to sum. The total is placed in a domain member attribute on the class specified in the Attribute to store sum in field. The sum automatically appears in the Model Tester.

Note. The attribute that is used to store the sum must be different from the attribute that is totaled, or it must be a child of a class that is not participating in the summation relationship.

A summation constraint cannot calculate quantity. Instead, you must use an expression that uses sumWithQty( ). An expression can use sum() or the + operator to accomplish the same task as this relationship. An expression has the additional capability to sum external variables.

Editing Elimination Constraints

An elimination compares a specific attribute value on a selection point with the value of a numeric, Boolean, string, or date expression. For example, you might create an elimination constraint so that domain members of the selection point HardDriveSelection are eliminated if the value of the selected hard drive’s Watts attribute exceeds the value passed in by externExpression.

The layout of the options in the elimination editor allows you to build a constraint in logical order. The following table details each of the editor’s options:

To create a definition, select:

1. A selection point from the members of column.

2. An attribute from the where column.

3. A comparison operator from the is column.

4. Either the to the expression or to the constant option.

5. A selection from the Allow column.

Repeat selections 2 through 4 for each attribute of the selection point class.

Note. The attribute type must match the expression or constant type.

During runtime, the system uses the comparison operator in the is column to compare the domain attribute value to the value that is supplied by the specified expression or by the constant.

If the comparison evaluates to true, the system adds the domain member to a list of domain members that satisfy the condition of the elimination.

Editing Comparison Constraints

The comparison editor, like the elimination editor, is designed so that you can build and view the constraint in logical sequence.

Like the elimination editor, the comparison relationship editor allows you to enter an arbitrary constant for comparison. You can use this constant instead of creating an expression to represent the value.

To create a comparison, select one item from each of the columns. Operators presented in the is column depend on the type of expression that is selected in the Generate a conflict where column.

Note. Attribute types for the expressions (and constant if used) must match.

Creating Relationships Outside the Model with SQL Queries

You can use the SQL query feature to define constraints. This feature removes the constraint definition from the model altogether and places it in a database.

The SQL query uses a SELECT DISTINCT statement to dynamically retrieve the domain member combinations that are compatible. To update compatibilities, you edit the database entries rather than the constraint definition in the model, eliminating the need to recompile the model. Thus, SQL query constraints allow you to store the compatibility of product options in a SQL table and drive product logic dynamically from within a database.

The first two rows of the example in the figure state: “Desktop comes with a 20G drive and in 128M and 256M Memory versions.”

To create a SQL query constraint:

1. Set up the classes by associating each column in the table with an attribute in the class.

   Note. Don’t use the system-defined attribute Name as a constraint item. You must add your own attribute. In the example, an attribute was created called chassis, and then the value in the attribute that corresponds to the distinct values in the table was added. For example, the Desktop Chassis domain member has an attribute called chassis, and its value is Desktop. (Optional step) Set up a SQL Query for the domain members as well. The SQL statement for the class retrieves its data from the Chassis column in the table. Then, using a DISTINCT clause in the SQL statement, it retrieves all of the possible values for the domain member list. This step saves having to add these values manually.

2. Define the constraint:

   1. Create the constraint by using the compatibility constraint editor.

      The New Compatibility Constraint dialog box appears first, in which you select the attributes.

      Warning! In the New Compatibility Constraint dialog box, be sure to select the correct attribute for the constraint arguments, as this is critical for the constraint to work properly. The constraint will not work if you use the default constraint argument.

   2. Make the constraint nondirectional by clicking the button on the editor toolbar.

   3. Change the format in the Properties panel to SQL Query.

      The Constraint Query dialog box appears.

      Note. Table and column names are case-sensitive.

   4. Specify a standard SQL query for each column in the constraint, separating the queries with a comma.

      Make sure that the RHS columns and LHS columns of the constraint are present on the attribute that it is being mapped to, rather than just the selection point name. You can specify that a space or another separator be used in the query output to allow for current data formatting.

   5. Click OK.

      The constraint is populated with values.

If a dynamic default contains default quantities, you can specify the quantities in the database if the column refers to a selection point with quantity. Do so by separating the policy, quantity, and value using a user-definable quantity and policy separator. For example, if @ is the separator, an entry in the database would be MIN@4@Tires. The policy can be MIN OF, MAX OF, or SUM, and the quantity must be a number.

Note. The quantity cannot be an expression reference.