KEY

The KEY keyword establishes a property as a key. Keys are used to determine the name space of modeling elements in the encyclopedia. The KEY keyword is also one of the allowed arguments following the FORMAT keyword in the DISPLAY command: see KEY (used for display).

By default, every modeling element in an encyclopedia is distinguished by its class (whether it is a diagram, symbol, or definition), its type (whether it is a UML Use Case diagram, a BPMN Process diagram, and so on), and its name (for example, the Reservation_System Use Case diagram versus the Human_Resource_System Use Case diagram). In addition to these built-in defaults, you can also specify additional keys for a definition modeling element; for example, a class attribute definition is keyed by its containing class definition, and that class’s containing package definition.

To use the KEY command, you specify it in the property that you want to be a key of a definition. The KEY command can be placed almost anywhere in the description of a property, but because of its importance, it is customary to place it as the first item in the property’s braces, just before the EDIT keyword.

For a property that is a key and that “points at” another objects (for example, a LISTOF or ONEOF property, not a simple TEXT or NUMERIC property), you must specify the class and the class type of the referenced objects when entering a value for the property while working in System Architect.

The following example indicates that the property “Use Case Name” refers to a definition of type “Use Case”. Definition is the default when no class is specified (class in the System Architect sense: Diagram, Symbol, or Definition).)

The property value itself often contains all the necessary remaining material needed to identify the objects actually being referenced. If the referenced class/type of the property has no key properties, the reference value is just be the object’s Name (because the class and type are known), but if the referenced class/type has key properties (such as “Use Case” in the above example, which has key property “package”), System Architect must know the values of these key properties in order to properly identify the reference object.

You either code this into USRPROPS.TXT so that System Architect gets the values for the user, or force the user to type in the fully qualified name, with periods separating the key parts.

•If a KEYED BY clause is not given for the property, System Architect expects these additional key values to be given in the reference itself: in other words, the user must type the fully qualified name of the reference object, with periods separating key values.

For example, for a Use Case Step called “Specify email” in a Use Case called Order_Product in a package called “Order System”, type:

Heterogeneous reference properties are different in this respect. See HETEROGENEOUS (ONEOF, LISTOF).

One other use for the KEYED BY clause is that it enables you to build a list of things that are all related. For example, all the Use Case Steps referred to in the property “Use Case Steps” of a Use Case definition belong to the same Use Case; as it happens, the one containing the “Use Case Steps” property. Where a multiple reference property (like ListOf) refers to objects all belonging to the same parent object, it is advised to use one or more other properties to identify the parent object. In these situations, a KEYED BY clause is used to tell System Architect which other properties to use.

Key properties of a definition are not shown in a grid formed by an ASGRID command. For example, in a Use Case definition, Use Case Steps are depicted in a grid formed by an ASGRID command, however, the key properties of Use Case Steps (owning package and Use Case) are not shown in the grid of Use Case Steps.