KEY

The KEY keyword is used to establish a property as a key. Keys are used to determine the name space of modeling elements in the encyclopedia. The KEY keyword also has a second usage – it is one of the allowed arguments following the FORMAT keyword in the DISPLAY command. For that latter usage, 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 may 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 may 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), the end user must specify the class and the class type of the referenced object(s) when entering a value for the property while working in System Architect.

The statement above 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 will contain all the necessary remaining material needed to identify the object(s) actually being referenced. If the referenced class/type of the property has no key properties, the reference value will 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 automatically gets the values for the end user or you force the end 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 in the fully qualified name of the reference object, with periods separating key values (for a Use Case Step called "Specify email" in a Use Case called Order_Product in a package called "Order System" the user would need to type in "Order System".Order_Product."Specify email".

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.