Specifying Quantities on Selection Points

This chapter provides an overview of quantity setup and discusses how to:

• Specify the number of allowed selections and optional or required status.

• Specify single- or multi-select controls.

• Set quantity limits on domain members.

• Set default quantities and selections.

• Define a dynamic default quantity for a selection.

• Attach metadata to selection points.

Understanding Quantity Setup

After you have set up the model’s classes and objects and defined their relationships, you are ready to define the properties on their selection points, including the model's quantities. Use the selection point's property table to define its quantities.

To view a model’s selection points, select View, Show, Selection Points or click the View Selection Point button in the toolbar. Click the selection point to update the property table with its current property values.

Alternatively, you can click the selection point’s name on the Components tab.

Setting up quantities involves these general steps:

Specifying the Number of Allowed Selections and Optional or Required Status

This section describes how to specify how many different items (domain members) within the selection point—not the quantity of each selected item–that the end user can make in the control that is associated with the selection point. In the process, you also specify its optional or required status.

For example, in a selection point that contains items A, B, C, and D, a minimum of 2 means that the end-user must choose at least two items, such as B and C or A, C, and D. Note that a minimum greater than 1 designates the selection point as multi-select. If minimum = 0, the end user isn't required to choose any of the items—the selection point is considered optional.

Note. This section also describes how to specify single- and multi-select controls, and whether the end user is required to select at least one of its items. As described elsewhere in this chapter, you can use the Multi Sel and Optional properties to accomplish the same purpose. However, the Multi Sel and Optional properties do not allow you to specify a quantity; using the min/max quantity properties as described here gives you the full scope of the default quantity and min/max functionalities.

To specify the number of allowed selections, in the selection point’s property table, select Use Min/Max = True.

Note. If you are not interested in defining minimum and maximum limits on the selection point, you can use the Optional property to specify the selection point type. (Optional = False specifies a required selection; Optional = True specifies an optional selection.)

Click the Edit button for SP Min/Max. The Selection Point Min/Max dialog box for the selection point appears:

Specify a minimum number of selections in one of three ways:

• Static: Enter in the Number list box either 0 (the user is not required to select from this selection point), or a quantity of 1 or greater, not to exceed the number of different items in the selection point.

• Runtime, by expression: If you want the number of selections to be determined at runtime by an expression, select Expression and select the expression that was created earlier from the drop-down list box.

• Runtime, by SQL Query: If you want the number of selections to be determined by stored data, select SQL Query, write the query in the entry box, and specify the database by name.

  Note. Advanced Configurator looks for the selection value in question in the first column of the first row of the data returned by the SQL query. Thus, you should create a query that returns only one column and one row.

In the Explanation field, enter a message to be displayed to the user when the minimum and maximum quantities are not satisfied during runtime.

See Creating Parameterized Explanations.

Specifying Single- or Multi-Select Controls

You can designate a selection point's single- or multi-select property in two ways:

• Set a minimum of 2 or more, as in the previous section.

  You may, in fact, have already specified it.

• Set a maximum of 2 or more, as described in this section.

Note. If you do not intend to define quantities on the selection point, you can use the Multi Sel property to specify selection point type. (Multi Sel = False specifies a single-select selection point; Multi Sel = True specifies a multi-select selection point.)

When Use Min/Max is changed from False to True, the selection point’s properties provide the default values for the SP Min/Max and DM Min/Max dialog boxes. For example, if the selection point is Multi Sel=True, Optional=False, and Quantity=True, then changing Use Min/Max from False to True gives settings of SP Min = 1, SP Max = Unbounded, DM Min = 0, and DM Max = Unbounded.

To specify single- or multi-select, as you did for the selection point minimum, specify values for the maximum limit:

• Single-select: Number = 1.

• Multi-select: Number = 2 or greater, or Unbounded.

For multi-select controls, Unbounded allows the number of selections to be any number of domain members in the selection point. Using Unbounded makes model maintenance easier in cases where all domain members can be selected and the number of domain members may change over time.

In the Explanation field, write a message to be displayed to the user when the maximum number of selections is exceeded during runtime.

See Creating Parameterized Explanations.

Setting Quantity Limits on Domain Members

Use domain member limits to place a minimum or a maximum limit or both on the number of the selected domain member. These limits apply to all domain members in the selection point. You can set quantity limits on the domain members of both single- and multi-select selection points. In the following example, the end user can choose no more than three of any one item (it is a single-select control):

The following example shows the domain member for the Min/Max dialog box for the selection point ClassB:

Number	Enter a numeral to be used as an absolute number.
Expression	If you want the minimum quantity to be determined at runtime by an expression, select this option and then select the expression from the drop-down list box.
Attribute	If you want the minimum number to be determined by an attribute value, select this option and select the attribute from the drop-down list box.
Explanation	Enter a message to be displayed to the user when the minimum and maximum quantities are not satisfied during runtime. See Creating Parameterized Explanations.
Unbounded	Click this button to Indicate that there is no upper limit.

To set minimum and maximum limits on domain members:

1. On the selection point's property table, set Quantity to True.

2. Set Use Min/Max to True.

3. Click the Edit button for DM Min/Max to access the Domain Member for Min/Max dialog box.

4. Select either Number, Expression, or Attribute to indicate the source of the value for the minimum quantity.

5. In the Explanation field, enter a message to be displayed to the user when the minimum and maximum quantities are not satisfied during runtime.

   An example message is: “Please enter a quantity of at least 3 racks.” Be sure that the message is specific enough to be helpful but that it makes sense for all domain members in the selection point.

6. Enter settings for the maximum quantity as you did for the minimum quantity.

   Use the Unbounded button to indicate that there is no upper limit on the quantity.

Setting Default Selections and Quantities

You can set the selection point to display one or more default selections with quantities, to be displayed when the end user starts the configuration. The source for these quantities can be:

• Explicit: The modeler specifies the default value in the model.

• Attribute: The modeler specifies an attribute of the domain member from which to retrieve the value at runtime.

Quantity Policy

Specify the quantity-choosing behavior to apply when constraints derive quantity values of their own in response to runtime input. Overridable, Overridable f(x): The quantity applied by the dynamic default or requirement constraint will be the final configuration quantity for that domain member. See Interaction between Default Quantities and Min/Max Settings at Run Time. Min of, Min of f(x): Apply the quantity value or expression result as a minimum quantity that will be selected as a default for the domain member. Max of, Max of f(x): Apply the quantity value or expression result as the upper limit of the quantity that will be applied to the domain member. Sum, Sum f(x): Add the quantity of each default selection of the domain member with the dynamic defaults and requirement constraints. For instance, if ItemA has a default of 2 and a dynamic default that specifies the quantity 2, then the runtime quantity of the domain member is 4.

Quantity Value/Expression

Click in the cell of the desired domain member and select or enter a numeral ( 0 to n), or an expression that depends on the quantity policy that is selected. If you select an expression, the value resulting from the expression is used. 0 indicates that the domain member is not selected by default.

Setting Explicit Default Choices and Quantities

To set up default selections and their quantities:

1. On the selection point's property table, set Quantity to True.

   The table adds the property Use Min/Max.

2. Click the Edit button for Defaults to display the Defaults editor.

3. Enter the desired quantity (1 to n) in the appropriate Quantity Value/Expression cell for the domain member.

   0 indicates that the domain member is not selected by default.

4. In the selection point’s property table, set Use Min/Max to True.

5. Click the Defaults Edit button to open the Defaults editor dialog box again.

6. If you want the default quantity to be determined by an expression, select the f(x) version of the displayed quantity policy in that cell’s drop-down list box.

   Return to the Quantity Value/Expression column and select the expression from the drop-down list box. (Expressions are defined in the Expression editor).

7. If there are dynamic default constraints or requirement constraints that could select a domain member during runtime, consider whether you want the default quantity entered in the table cell to remain in effect if one (or more) of the dynamic defaults and requirement constraints picks the domain member.

   If not, leave the policy at Overridable, the default. The quantity applied by the dynamic default or requirement constraint will be the final configuration quantity for that domain member.

   See Interaction between Default Quantities and Min/Max Settings at Run Time.

8. If you want the entered (static) quantity to be evaluated against the runtime quantities, designate a new quantity policy:

   • Min of, Min of f(x): Apply the quantity value or expression result as a minimum quantity that will be selected by default for the domain member.

   • Max of, Max of f(x): Apply the quantity value or expression result as the upper limit of the quantity that will be applied to the domain member.

   • Sum, Sum f(x): Add the quantity of each default selection of the domain member with the dynamic defaults and requirement constraints.

     For instance, if ItemA has a default of 2 and a dynamic default that specifies the quantity 2, then the runtime quantity of the domain member is 4.

9. Click the quantity policy of the domain member whose quantities you want to edit, and select the policy to apply with the quantity.

10. If you want to set up default quantities that apply for all domain members as a group, select Use Quantity Policy for All Domain Members and enter the policy or quantity.

    Setting the policy and quantity at the selection point level offers these advantages:

    • It simplifies model maintenance if domain members do not require different quantity settings.

    • If there are no default choices at the domain member level, it allows you to apply static quantities for those domain members that are not defaulted (quantity = 0).

    • If there are default choices at the domain member level, you can set a baseline quantity for all domain members that satisfies a quantity check at the selection point level.

      Similarly, click the value in the Quantity Value/Expression cell for the domain members) and enter the quantity or select the expression that supplies the quantity for the domain member if it's selected.

Getting Default Selections and Quantities at Runtime Through Attributes

You can specify a static default quantity on each domain member by creating an attribute on its parent class and assigning each of the domain members a value for the attribute. One useful application of this feature is to automate the populating of a bill of materials by using a domain member attribute to set a flag on selected items.

To specify runtime defaults:

1. In the Model Structure view, select the class that contains the domain members for which to set defaults.

2. In the properties table, click the Add Property button to add a new row to the table.

3. In the pop-up dialog box, enter a name and data type.

   If you want the domain members to have a default value, enter it in the Value field. Click OK.

4. If you want an external source to supply values for the attribute, change the Internal property to False.

   The SQL property appears. Write the SQL statement to retrieve the desired values.

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

   See Setting Up Binding for External Domain Members.

5. If you want to assign static values, select each of the domain members in turn and enter the value in the Value column of the attribute that you just created.

   Be sure that the value does not exceed 10 characters.

Defining a Dynamic Default Quantity for a Selection

Another way to set up default quantities that are determined at runtime is to write dynamic default relationships with quantities. If you have dynamic default relationships that select by default one or more domain members, you may need to define the quantities in those relationships.

The following example shows default settings that indicate how many of which free gifts to give to a customer based on the investment attribute:

Quantity policy settings are:

To define quantity selection behavior for a dynamic default relationship:

1. Open the relationship editor by double-clicking the name of the relationship on the Components tab.

   Look for the Quantity Policy and Quantity Value columns in the right-hand side (RHS) of the editor. There should be one of each of these for each selection point in the right-hand side of the relationship. If these columns are not present, then the selection point is not set up for quantity definitions. To enable quantity definition on the relationship, close or minimize the relationship editor. Display the selection point properties on the table editor and set the quantity to True. Then reopen the relationship. If you still do not see the quantity columns, check that the relationship binds a class and a selection point rather than a class and a class.

2. If a default selection requires one or more of the selected domain member(s):

   1. Click on the appropriate LHS row to display the relationship.

   2. Click the policy of the domain member.

   3. Select the policy from the drop-down list box.

   4. Enter the quantity in the value column.

      As with other quantity definitions, you can obtain the value from an expression as well.

The resulting dynamic quantity is then subjected to further evaluation against any static default quantities that you may have set in the preceding steps. The result is the final quantity, which is returned for display in the control.

Note. If configuration conditions are such that a default quantity (static or dynamic) would cause a violation, it will not be applied.

Attaching Metadata to Selection Points

To attach metadata to a selection point, you must place an attribute on the selection point. This attribute serves as the source of static default quantities for each domain member in the selection point. The stored metadata can be retrieved by the front end to perform ancillary operations. At runtime, selection point attributes are read-only. Advanced Configurator uses the default value for a selection point attribute if a value is not specified for a selection point attribute.

Float, integer, string, date, and Boolean data types are supported. Selection point attributes can be inherited by subclasses.

Attributes on selection points can be inherited by subclasses but not by domain members; they can't participate in constraints, and they can't be filled from external data using a SQL query.

The selection point attribute is the On Output property in the property table.

Note. A selection point attribute and domain member attribute within a class cannot have the same name.

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

ERROR: Compilation of model <modelname> failed: On GCL class “<classname>”, domain member “<domain member name>” has a value for attribute “<attribute name>” of “<value>” which cannot be converted to type _Integer.

The following example shows the property table for the class HardDrives, with the selection point attribute AvailDate:

To attach metadata to selection points:

1. In the Model Structure view, select the class.

2. In the properties table, add a new row.

   Click the Selection Point Attribute button to add a row in the properties table for the selection point attribute.

3. If you want to provide a default value for all domain members in the selection point, enter it in the Value column.

   Otherwise, the system uses the value from the input source that you have assigned for the attribute.

4. If you want the default to be different for one or all other selection points of the class, create a separate selection point for each domain member.

   Select one of the new selection points in the Model Structure view. The attribute appears in its property table. Enter the desired value in the Value column. Repeat for each selection point for the class.

5. If your application is integrated with Order Capture and you want the attribute's value to be output, enter the selection point attributes on the Output tab of the Schema page the same way as for regular attributes.