Creating Objects for the Model

This chapter discusses how to:

• Create a class.

• Delete a class.

• Change class structure.

• Add class attributes.

• Create internal domain members.

• Create external domain members.

• Create a “None” domain member.

• Assign values to attributes.

• Inputting date-type attributes manually.

• Set up binding for external domain members.

• Filter and manipulating table data.

• Work with selection points.

• Storing a dynamic default quantity in a database.

• Internalize data.

Creating a Class

A class has the following default properties:

Inheritance principles must be considered while a model is being built. Click anywhere in the model structure view to ensure focus on the modeling area.

To create a class:

1. Click the Create Class icon in the right margin, then click the parent class, or, select a class, then select Insert, Class.

   To create multiple classes, hold down the Shift key, click the Create Class icon, then click the parent class, or, select a class, then select Insert, Multiple Classes.

   The New Class dialog appears.

   Note. A class may have either subclasses or domain members. If a class has domain members, they must be deleted before a subclass can be added.

2. Type a name into the Name entry field of the New Class dialog. The dialog prompts with a .cms file name based on the string you enter. Before continuing be sure the name is correct according to the following:

   • Class names must be unique within a model.

   • The name cannot include \, =, <. >, :, ", (, or ). The initial character cannot be dollar ($) or underscore (_), but these characters can be included in other positions.

3. Click the Change button to specify a different file name. A class object can be saved to an existing .cms file.

   Once a name is accepted, the class name can be changed within the model, but the file name cannot change.

4. If you are adding a single class, click OK to end the process, or click Add Another to continue adding classes. Or, If you are adding multiple classes, type “Return” to make another, or click the cursor arrow in the menu bar to revert to the normal Windows cursor.

When a class is created the following events occur:

• The information for the new class is displayed in the context-sensitive properties editor (if it has focus).

• The class name appears in the Class list in the Components view.

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

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

• If the class is a leaf class, a corresponding selection point is automatically created.

Deleting a Class

To delete a class, select it and press the delete key.

Deleting a class:

• Removes the class, any subclass(es), and any domain members.

• Removes the class from any relationships that reference it.

To remove the corresponding file from the .csp file, click the File View tab. Locate the associated class file and right-click to open the context-sensitive menu, then select Remove File From Project. Note that deleting a class in Visual Modeler does not remove the corresponding .cms file from the file system.

Changing Class Structure

It is possible to reuse parts of a diagram with the Reparent and Copy and Paste features.

Compare the following two figures:

• a1 is copied and dropped on the Root class. Because the new class is a sibling of a1, a new name, a1_1 is automatically created.

• The original a1 is dragged and dropped onto a2. a1 becomes a subclass of a2; there is no need for a name change.

To reparent a class:

Drag and drop it on a class that does not have domain members.

To copy and paste a class:

Copy a class and paste it on another class that does not have domain members. The original class remains unchanged in the diagram. Any domain members and relationships will be transferred along with the copied class to its new location. If the class is on the same hierarchical level (a sibling) the class will be automatically renamed to keep it unique. If the class is not a sibling, the name is unchanged.

Note. Copying and pasting a class will not copy the corresponding selection points. If the copied class is a leaf class, a selection point will be created for it; however that selection point will have the default properties, not the properties, of the original class's selection point.

Adding Class Attributes

Class, domain member, constraint, and selection point values and attributes can be specified or edited in the context-sensitive Properties editor.

The figure shows the Properties editor for a class in which the user has defined attributes, and the Internal property is set to False, so that the attribute values will be imported from an external source.

Note. The SQL Query field is not shown unless Internal is set to False.

To add an attribute to a class:

Click the Add button at the top of the panel to open the Create a New Property dialog. You can either use the dialog to enter the name, type, and value, or click the OK button to add a blank row to the table for editing. Possible types are Boolean, float, int, String, and date.

An entry in the Value column becomes the default for child classes and for domain members. The value can be changed in the class in which it is defined, or in an internal domain member. When the SQL Query property is set to False, internal values are generally ignored, however, if a database happens to have a null value, the default value from the model will be substituted.

Creating Internal Domain Members

A domain member is an instance of a class. You can create any number of domain members. An internal domain member is one that is stored within the model rather than a database or another system file.

To create internal domain members:

1. To create a single domain member, click the domain member icon, then click the parent class.

   To create multiple domain members, hold down the Shift key, and click the domain member icon, then click the parent class. Alternatively, select a class, then select Insert, Domain Member or Insert, Multiple Domain Members.

2. Click OK to complete the process, or click Add Another to continue adding domain members on the same class. The New Domain Member dialog appears.

3. Type in a name. The name cannot include \, =, <. >, :, ", (, or ). The initial character cannot be dollar ($) or underscore (_), but these characters can be included in other positions. An asterisk (*) cannot be used alone, but it can be used in combination with other characters.

4. When you are finished creating domain members for this class, select another class, or click Cancel.

   Or,

   To stop creating multiple domain members, click the cursor icon in the Windows menu bar to revert to the normal Windows cursor.

Creating a “None” Domain Member

When a control is single-select, an item named None is automatically displayed in the Model Tester when you launch it. If the selection point flag Optional is set to True, None is computer-selected (unless a default was set). It is important to understand that this “generated” None is not a domain member, and it has no value. As such, None does not participate in constraints.

When a user selects None at run time, it means “there is no selection made on this selection point.”

None is not generated for a multi-select control.

For required single-select controls, none has no meaning, so the Model Tester has an option to hide None on required controls.

If you want an item named None to be selectable on a multi-select or single-select control, you must create a domain member for that purpose. It is helpful to name this domain member something other than None, such as “No Thanks” or “I don’t want any” to avoid confusion with the “generated” None.

Assigning Values to Attributes

Type appropriate values in the Value column. The figure shows the attributes for an internally defined domain member. The naming restrictions for domain members also apply to attributes.

Note the use of font styles in the Properties editor:

• Items that cannot be changed are shown in black bold face. For example, the Name and File Name types cannot be changed.

• Items shown in plain text can be modified, that is, the value of the name can be changed.

• Items defined in an ancestor class—for example, the attribute price in the figure, are shown in italic font.

Inputting Date-Type Attributes Manually

You can input date-typed attributes on classes and domain members manually, through the Property Editor, and through an SQL query from a database. The Visual Modeler also supports date-typed data in compatibility, requirement, and dynamic default constraints.

You can express values for dates using the full ISO 8601 format. However, any time zone, hour, minute, and sub-second information will be truncated during the compilation process to yield a YYYY-MM-DD format. The validity of dates is checked during the compilation process and error messages are generated for any invalid dates detected. Advanced Configurator stores the dates as strings in their YYYY-MM-DD format since many date operations can be performed on the ISO 8601 format using string manipulation and comparison functions.

Date values loaded from a database are retrieved and converted to the YYYY-MM-DD format. Thus, you can store and retrieve date values in formats other than YYYY-MM-DD.

Note. Strings can be input directly from the user interface if they are in a parseable date format.

You can also use date data in expressions.

See Creating and Editing Expressions.

Setting Up Binding for External Domain Members

Relationships can be created between classes or selection points and domain members obtained from a database. Setting up the modeling environment to work with external objects requires:

• Configuring the database.

  See Database Interface Configuration.

• Configuring your system so that you can see external data in the model.

  See Connecting to a Database from Visual Modeler.

• Specifying the appropriate values for properties in the JNDIDBName.properties file so that you can compile and run a model with external data.

  See Configuring JNDIDBName.properties.

Selecting a Primary Table

Select a class, and in the Properties editor, set Internal to False. The SQL Query field appears. Click the Edit button to display the primary table dialog. (If no databases are listed in the drop down on the upper left, the Visual Modeler is not connected to a database.)

See Specify a Database Connection.

Simple Queries

Simple queries, where a database table column corresponds exactly to the model needs, do not require an advanced SQL query.

To write a simple query:

1. Type the database table name into the Primary Table field.

   Note. The table name and all other names associated with the database are case-sensitive.

2. Type a Column name from your database into an empty Table Column cell. To map the values to class attributes, make a selection in the corresponding Class:Attribute drop down.

3. (Optional) Enter a Where clause. The SELECT and FROM portions of the query are derived from the dialog inputs. You need only enter the WHERE portion.

4. (Optional) Check the Distinct check box to ensure that repeated values are not displayed.

5. Click the Domain Member Key box next to the value you want displayed on the domain member. At least one row must be chosen as Domain Member Key. The Domain member key does not have to match the Primary Key in the database.

Note the following important points about queried data:

• Data queried for a Domain Member key must be unique. The Domain Member key data will be used as an identifier for domain members at run time.

• If two domain member keys are chosen, both will be displayed on the imported domain members. The topmost key will be displayed first.

  If more than one domain member key is chosen, the union of all keys will be used to identify domain members at run time; the combined list cannot have duplicates.

• Queried data has the same restrictions as internal data. A query cannot return a name that includes \, =, <. >, :, ", (, or ).

  The initial character cannot be dollar ($) or underscore (_), but these characters can be included in other positions. An asterisk (*) cannot be used alone, but it can be used in combination with other characters.

• None is displayed on single-select controls at run time. This “generated” None is not a domain member. If you want a domain member to perform this function, you must create one in the database.

  See Creating a “None” Domain Member.

Secondary Table Option

To join a secondary table to a Primary table, click the Secondary Table button. Database-to-class property mapping is similar to that for the Primary window, with these exceptions:

• The SQL query is a Join clause. Typically, a secondary table is used to add an attribute from another table to an external domain member. The secondary table has at least one column in common with the primary table. The common column is used to state the join condition.

• Columns cannot be mapped to domain members in this dialog.

• Multiple secondary tables are allowed. Click Add New Table. Each table appears on a separate tab in the Secondary Table(s) window.

Note. Limit using secondary tables to situations where they are truly necessary. Secondary tables are preferred to defining advanced queries, but they slow Visual Modeler performance and increase compilation time.

Advanced Queries

An Advanced Query is required if filtering must be applied to the table data and if you plan to do any data manipulation in the SQL. For example, you could calculate someone’s age based on the current date and their birth date and return that value as AGE. You may also need an advanced query if you are using nested select statements or complex joins.

When you use an advanced query, the runtime system can not dynamically read additional database data as requested by run time components. Any data needed must be provided by the query specified in the Advanced Query specification.

You can not request additional attributes on the UI with advanced queries. For example, with a simple query, you don’t have to map LONG_DESCRIPTION into the model, but you can still display it at run time since it is added onto the query for the class. With advanced queries, all attributes that will be displayed or otherwise referenced (for example., in pricing) must be mapped into the model.

Note. An advanced query must be written such that the first column returned is returned as “$NAME”. This should be the domain member key (or equal to the domain member key).

To enter an advanced query:

1. Click the Advanced Query check box. The Primary Table field will disappear.

2. Type an SQL Server or Oracle query into the Enter Advanced Query field to:

   • Generate the domain-member name column from the key columns.

   • Return it as column 1 and call it '$NAME'.

     This part of the query looks like:

     (tbl1.keycol1 || tbl1.keycol2 || tbl2.keycol1) AS '$NAME', tbl1.col2 WHERE ...
     

     Examples

     SQL-Server:

     (single-column key)

     SELECT (cast( tbl1.keycol1 as nvarchar(4000))) AS '$NAME', tbl1.col2 WHERE ...

     (multi-column key):

     SELECT (cast( tbl1.keycol1 as nvarchar(4000)) + '_' + cast( tbl1.keycol2 as⇒
      nvarchar(4000)) + '_' + cast( tbl2.keycol1 as nvarchar(4000))) AS '$NAME',⇒
      tbl1.col2 WHERE ...

     Oracle:

     (single-column key):

     SELECT (tbl1.keycol1) AS "$NAME", tbl1.col2 WHERE ...

     (multi-column key):

     SELECT (tbl1.keycol1 || '_' || tbl1.keycol2 || '_' || tbl2.keycol1) AS "$NAME",⇒
      tbl1.col2 WHERE ...

     (You can also leave out the table prefix (“tbl1.”, “tbl2.”) if there is only one table being queried.)

3. Add the data call portion of the query:

   In an example where a class’ attributes name, attr1, and attr2 are taken from tableX, and there is a need to order by attr1, the query (for Oracle) is similar to this:

   select name as "$NAME", attr1, attr2 from tableX order by attr1

   The column mappings are:

   $NAME -> tableXID(domain member key)
   attr1 -> columnA
   attr2 -> columnB

4. Perform the remaining steps as described in the preceding instructions “Simple Queries.”

   Note. Do not use the Advanced query unless it is absolutely necessary. The simple query is preferred because it can be optimized at run time.

Using Table Aliases

Using a table alias helps allows you to:

• Refer to the same table/view more than once in a single query.

• Refer to a table by a sorter name in the where clause.

In particular, a table alias can help you create joins and differentiate between multiple instances of the same table. To create a table alias, follow the table/view name with a name of your choosing—the alias. When you refer to that table instance in the where clause, prefix the column name with the prefix. The SQL below is what the system actually generates at run time. Note the prefix names used in the WHERE section—you can see them defined in the FROM section.

SELECT DISTINCT ( CAST(kit.PROD_COMPONENT_ID AS NVARCHAR(4000))) AS '$NAME'
FROM 	PS_PRODKIT_COMPS kit, PS_EOEP_PRICE_LIST list, PS_EOEP_PRICE_LIST recur, PS_⇒
PROD_ITEM prod
WHERE	kit.SETID = 'COM01'
		and kit.PRODUCT_ID = 'TEL200002' 
		AND list.RECURRING_FLG = 'N' 
		and list.PRICE_LIST_ID = 'COM_PRICE' 
		and list.SETID = kit.SETID 
		and list.PRODUCT_ID = kit.PROD_COMPONENT_ID 
		AND recur.RECURRING_FLG = 'Y' 
		and recur.PRICE_LIST_ID = 'COM_PRICE' 
		and recur.SETID = kit.SETID
		and recur.PRODUCT_ID = kit.PROD_COMPONENT_ID 
		AND prod.SETID = kit.SETID 
		and prod.PRODUCT_ID = kit.PROD_COMPONENT_ID

Filtering and Manipulating Table Data

An Advanced Query is required if filtering must be applied to the table data and if you plan to do any data manipulation in the SQL. For example, you could calculate someone’s age based on the current date and their birth date and return that value as AGE. You may also need an advanced query if you are using nested select statements or complex joins.

Storing a Dynamic Default Quantity in a Database

A special character is used to separate the quantity values and policy from the constraint value. For instance, if you want to default four fans with a SUM policy, the string “FANA~4~SUM” might appear in the database to denote that default. The format for a value stored in a database can be one of the following:

<value>
<value><delimiter><quantity-or-expression>
<value><delimiter><quantity-or-expression><delimiter><policy>

The <value> token is the value to be used by the constraint. In the prior example, this would be the symbol FanA. The <delimiter> token is the special separation character. In the example, this was the character ‘~’. You can specify the delimiter character in the Project, Settings dialog.

The <quantity-or-expression> token is either a numeric quantity or the name of an expression. The <policy> token is SUM, MIN OF, or MAX OF.

Retrieving Expression Values and Externs from a Database

You can populate LHS expressions and RHS extern values from stored data. Visual Modeler and the compiler recognize data output from the database in specific format and will populate the rows of constraints with that data.

The format for LHS expressions is:

<comparator><space><"const" or "f(x)"><space><value or expression name>

Examples: <= const 2 and > f(x) expSum

Format for RHS externs is < “true” or “false”> to indicate whether it is required (true) or optional (false).

You should have one column in the database for each expression or extern in the constraint.

Working with Selection Points

The selection point is the model component that communicates directly with the HTML control in the UI. By default, a selection point is created for every leaf class that participates in a relationship.

A selection point has these properties, which are displayed and editable in the properties table:

To view a model’s selection points, select View, Show, Selection Points or click the selection point icon in the toolbar. The selection points are displayed on the left side of the model structure view.

A selection point participates in all relationships that refer to the original parent class. If a relationship is made directly between a selection point and another object, that relationship is confined to the selection point. To add a selection point, drag a class from the components view into the selection point area, or drag a class from the Model Structure View into the selection point area.

To delete a selection point, select it in the Model Structure View, then press the Delete key. Once created, a selection point can participate in relationships with classes or class attributes members in the modeling editor.

Note the Properties Editor entries for selection points. Because selection points interface with the UI, settings made here determine how controls behave at run time. A selection point can be designated as multi-select (the user can select more than one of its items), and/or optional. If a control is optional, the user does not have to make a selection on the control. If a selection point is required, the model will not be considered valid until a selection is made. Selection point properties (Table Editor) New selection points appear at the bottom of the selection points area, and at the end of the selection points listing in the component view.

A class can have many attributes, but if attribute values are to be selectable at run time, they must be made visible from the selection point. To do this, right-click on a selection point that has attributes, select Set Visible Attributes, and check any attributes that you want to display at runtime. When an attribute is made visible, it will be shown on all the selection points for a class. The display of an attribute cannot be confined to certain controls.

Internalizing Data

External data can be extracted from the database and automatically inserted and defined in the model as for manually entered data.

This is a necessary step if the model is to be deployed in an another environment where configuration will take place locally on a standalone version of Advanced Configurator. The Configurator Administration Console has a more comprehensive internalization function than does Visual Modeler. It can internalize data stored in files other than those in a database.

Internalizing data is a “one time” operation. Once it is performed, changes to the data in the database will no longer be reflected in the model. To internalize data on an ongoing basis, use the option available with the compile command on the Server’s Administration page.

To internalize external data using the Visual Modeler, use the Project, Internalize Model command.

See Also

Administration Console